Persistent storage

Mount volumes, files and server folders so data survives a redeploy.

A container's own filesystem is deleted every time it is recreated. Uploads, caches and databases need a mount to survive a deploy. Everything here is in the app's Settings -> Storage, in the Mounted storage card.

KindWhat it isNeeds permission
VolumeDisk space Deplo creates and keeps for this app, named deplo-<slug>-<name> on the server. The normal choiceno
FileA text file you write in the browser, kept in the app's Files and placed inside the app. For config filesno
BindA folder that already exists on the server, shared with everything else on that machineBind server folders
  • Removing a row stops mounting it. The data stays.
  • A File is written before the container starts, so Docker never turns it into an empty folder by mistake. It holds at most 1 MiB of text; a binary or bigger file already there stays as it is.
  • A Bind reaches outside Deplo, so an instance admin grants Bind server folders in Settings -> Users. See Host access.

Add storage

Open Storage

Open the app, then Settings -> Storage. Click Add storage and choose Volume, File or Bind.

Settings -> Storage of a built app with nothing mounted yet, where a volume, a file or a server folder is added

Fill the source

  • Volume: a Name such as uploads. Left empty, Deplo derives one from the path.
  • File: the Path in Files, such as config.toml or conf/nginx.conf, then the content.
  • Bind: the Path on the server, such as /srv/media.

Set the mount path

The Path inside the app, for example /app/uploads. For an app Deplo builds it can stay blank: uploads lands in /app/uploads, the folder your code runs in. For a prebuilt image or a Compose service, type the full path.

Optional: pick a container

In a Compose app, Which service uses this data? picks the service that mounts it. Automatic uses the main one.

Click Save storage: it applies on the next production deploy. Every row can also turn on Let the app read but not change it (ro).

Bind options

A Bind row adds What if something is mounted inside this folder?:

OptionWhat the container sees
Only what is already there (rprivate)The folder as it was when the container started. The default
Keep up with the server (rslave)Mounts that appear on the server later show up inside too
Keep up, and let the server see this app's own (rshared)Both directions: a mount the container makes appears on the server too

Without rslave, a network share or a FUSE mount attached after the container started never appears inside it.

A Compose app's own mounts

A Compose app can declare storage in its own docker-compose.yml and also have Storage rows.

Settings -> Storage of a Compose app: the mounts its own compose file declares
  • The compose file's mounts are listed read-only, under From docker-compose.yml. Change them in the compose file under Deployments.
  • The compose file wins on the same path. A Storage row on a path it already mounts is ignored.
  • A ./<path> source that does not exist yet is created before the container starts: a name that looks like a file (config.yml, nginx.conf, Caddyfile, .env) becomes an empty file, anything else (./data, ./conf.d) an empty folder.
  • A service name the compose file lacks is an error, never a silent remount.

What deleting the app removes

KindWhen you delete the app
VolumeErased. Deplo removes deplo-<slug>-<name> on the server
FileErased. The app's files directory goes with the stack
BindLeft alone. The folder belongs to the server, not to Deplo

A Compose app's own volumes are erased too, named deplo-<slug>_<key>. One marked external: true or with its own name: survives.

A Bind is yours to remove

Deleting the app does not delete a bound folder, and server cleanup never removes server folders. Note the paths before you delete the app, and remove them on the server yourself.

Move an app to another server

Settings -> General, then Move on the Server card (shown only with more than one server). Pick the new server and confirm.

  • Deplo redeploys the app there and copies its data first. The app is offline during the copy.
  • If the copy fails, the app goes back to its old server. If the old server cannot be reached, the app is kept stopped on the new one: redeploy when the old server is back, or press Deploy anyway to start without the data.
  • Apps it reached by name stay behind. The dialog names them before you confirm.
  • A volume missing on the old server is named in the deploy log, and the old server's volumes are kept in case the data lives under another name.
  • A cluster is in the same list, as a group: Any server lets it pick, or pick one of its servers. An app with a volume then waits for its server when it stops. See Move to one server of a cluster and Apps with stored data.
  • What does not move: a Bind, an external: volume, and a Compose app's ./ folders in the repository's copy on the old server. The deploy log lists them.

Good to know

  • Data is never deleted by a redeploy, a source change, or removing the row. Only deleting the app erases Volumes and Files.
  • A Volume cannot replace a system folder such as /etc, /usr, /proc or /var/run.
  • Do not put a database's data in a Bind. A managed database already has its own volume.
  • An app backup includes its Volumes and Files, not a Bind and not its databases.

Troubleshooting

  • The data disappears on deploy - the path the app writes to is not mounted.
  • Permission denied inside the container - the container's user does not own the directory. For a Bind, fix ownership on the server. For a Volume, make sure the image creates the directory as its own user.
  • A Bind row will not save - you do not have Bind server folders.

More in Servers and agents.

Next steps

Did this page help you?

On this page