Skip to main content

Persistent Storage & Volumes

By default, a container's filesystem is ephemeral — anything written inside it is lost when the container is replaced by a new deploy. Persistent volumes let you mount a directory that lives on the host server, so data written there survives redeploys and restarts.

Adding a volume​

Go to your app → Storage tab → Add Volume.

Enter an absolute path inside your container where you want the directory mounted — for example:

/var/www/storage/app/public
/data/uploads
/app/cache

Click Save, then redeploy your app. The path is mounted on the next deploy and from then on it persists across all future deploys.

Path rules​

  • Must start with /
  • Cannot be a reserved OS path (/, /etc, /usr, /bin, /sys, /dev, /proc, etc.)
  • Cannot contain spaces
  • Each path must be unique (no duplicates)

Where data is actually stored​

Vessl stores volume data on the host server at:

/vessl/volumes/<app-id>/<slug>

Where <slug> is derived from the container path (slashes replaced with underscores). You can see the exact host path shown below each volume entry in the Storage tab.

Checking disk usage​

Once a volume is mounted, go to the Storage tab → Disk Usage section and click Refresh. Vessl fetches the current size of each volume directory from the host server via SSH.

Multiple volumes​

You can add as many volume paths as your app needs. Each path gets its own directory on the host.

Removing a volume​

Remove the path from the Storage tab and save. The volume is unmounted on the next deploy. The data directory on the host server is not deleted automatically — you'd need to clean it up manually via SSH if needed.

Multi-replica and volumes

If your app runs more than one replica, all replicas share the same host volume directory. Concurrent writes from multiple instances can cause data corruption. For multi-replica workloads, use external object storage (S3, Cloudflare R2, etc.) instead of host volumes.

What to persist

Good candidates for volumes: user-uploaded files, compiled assets, application cache directories, SQLite database files. Poor candidates: session data (use Redis instead), build artifacts (rebuild on deploy), temp files.