The short answer
On Pro, a persistent volume is one absolute mount path on one service. The app has to write there. Redeploy once and read a test record back. That is how you check the data survives a redeploy.
The container filesystem is not that path. A deploy, a restart, or a reschedule can replace the container, and files that lived only on it go with it. A backup to an S3-compatible destination you control is a third thing: a copy, not the live disk.
A volume is not a backup. Redeploying does not restore data.
The product page is persistent files. The reference is Persistent storage and backups. The walkthrough is Configure persistent storage and backups, and the app layout is Deploy an application with persistent files.
Container filesystem vs persistent volume
Application containers are replaceable. Treat files written only to the container filesystem as temporary.
| Container filesystem | Persistent volume | |
|---|---|---|
| Lifetime | Temporary. A deploy, restart, or reschedule can replace the container. | A durable path for one service, when the app writes to the mount. |
| Scope | That container. | One service, one absolute path inside the container. |
| Replicas | Not a shared disk. | A volume-backed service runs one replica. |
| Recovery | A redeploy does not bring those files back. | Not a backup. Reset, Detach, and deleting the service delete the data. |
On Free, an idle app sleeps, and memory and temporary files are reset when it sleeps. Free does not include persistent volumes. Both are on pricing.
A missing file after a redeploy is not the same failure as a crash. If the deployment itself stopped, read the stage in Debug a failed deployment. An application rollback promotes a previous deployment. It does not restore a database, a volume, or an external side effect.
Choose what belongs on the volume
Keep installed dependencies and compiled code in the image. Put uploaded files or application data under a dedicated path such as /data.
Do not mount over the application directory. A mount can hide files that were part of the built image.
If several services or replicas need the same files, use external object storage or a database. An Unbroker volume is attached to one service, and a volume-backed service runs one replica. It is not a shared filesystem. The same split is how a Compose file’s volumes are sorted in Docker Compose in production.
For a database template, keep the volume mounted at the engine’s expected data directory. Moving the mount without moving and validating the data can make the engine look empty even though the files are somewhere else.
Make the data path configurable
Point the process at the mount with an environment variable. The persistent-files guide uses DATA_DIR for a Node.js illustration:
const directory = process.env.DATA_DIR;
if (!directory) throw new Error("DATA_DIR is required");
The rest of that illustration creates the directory, writes settings.json through a temporary file, and renames it into place. It is a single-writer settings file, not a concurrent database. Serialize writes in the app. The fixed temporary filename is not for simultaneous writers. The full snippet is in Deploy an application with persistent files.
For records that need transactions or concurrent updates, use PostgreSQL or another database. That choice is the last section of this note.
A Node service starts from Deploy Node.js. A container starts from Deploy Docker.
Mount, deploy and verify
The guide’s walkthrough uses mount path /data and DATA_DIR=/data. Check that the runtime user can read and write that directory.
The documented volume commands are:
ubctl apps volumes ls
ubctl apps volumes attach svc_123 --path /app/data --size 10
ubctl apps volumes resize svc_123 --size 20
svc_123, /app/data, 10, and 20 are the examples on the volumes CLI. Use the absolute path the app writes to. The guide’s /data and the CLI’s /app/data are two examples of that path, not two mounts. Volumes can grow and cannot shrink. Reset and detach are not in this CLI. Those actions are in the service’s Storage settings.
Then prove the mount:
- Deploy and create a harmless test record through the app. Note the value.
- Redeploy the same service and read the record again.
- Confirm the new code is visible and the test data is still there.
That catches an app still writing to a relative directory outside the mount. Also try the app when the filesystem is nearly full, or when a write fails.
A post-deploy command runs in a one-off copy of the new image and does not mount the persistent volume, so it cannot seed that disk. That limit is in the deployments CLI.
Volume actions and their cost
Open the service’s Settings tab. The Storage section lists the volume. Every action applies immediately. None of them waits for the next deploy. The cost in this section is the data. The invoice is the next section.
| Action | Effect |
|---|---|
| Grow | Raises the size, up to 50 GB. The volume grows online without a restart. Storage billing moves to the new size at once. It cannot shrink. |
| Reset data | Deletes everything on the volume and restarts the service on an empty one. The volume keeps its size and mount path. A database restarts freshly initialized with its current credentials. |
| Detach volume | Deletes the volume and its data, and keeps the service. The service stops, then redeploys its current image without persistent storage. Scheduled backups for it are turned off. |
| Delete the service | Deletes the attached volume and its data. |
Databases need their volume, so they offer Reset data and not Detach.
Reset and Detach cannot be undone. Both ask you to type the service name. Both wait until any running deployment, backup, or restore has finished. Do not use them to troubleshoot a startup problem without a recovery plan. The current behavior is in Persistent storage and backups.
Backups are a separate system
Cloud Apps can send volume backups to an S3-compatible destination that you control. A schedule defines when backups run and how many are retained. A restore asks for the service name before it runs. The volume is still not a backup.
The storage CLI documents this example. Replace the placeholders. Keep the destination credentials out of the repository.
export UBCTL_S3_ACCESS_KEY="..."
export UBCTL_S3_SECRET_KEY="..."
ubctl apps backups destinations create \
--name primary \
--endpoint https://s3.example.com \
--region us-east-1 \
--bucket app-backups \
--prefix unbroker
ubctl apps backups destinations ls
ubctl apps backups schedule svc_123 --destination dst_123 --cron "0 3 * * *" --retain 7
ubctl apps backups run svc_123
ubctl apps backups ls svc_123
ubctl apps backups restore svc_123 backup_123 --confirm orders-db
0 3 * * *, --retain 7, and --confirm orders-db are that example, not a default schedule or a default name. --confirm is the service name.
Check that a scheduled backup finishes and that the destination has the recovery files you expect. For a database, follow the engine’s backup requirements and test the restored database, not only that the files exist. When you can, rehearse the restore on an isolated target: records, permissions, and application startup. A green health check does not tell you the recovery point or how long a restore takes. Record both.
The destination’s own charges sit outside the Unbroker volume rate. Count the provisioned volume and those charges before the disk fills up. One layout that keeps a user folder on a volume and Postgres beside it is Self-host n8n.
Billing notes
Persistent volumes require Pro. The plans table lists them as not available on Free and available on Pro. Pro is $25 a month with $25 of usage credit. The credit resets each cycle and does not roll over. If eligible usage stays under the credit, the monthly charge is still the plan price. Current figures are on pricing and in Plans.
Storage is billed from provisioned bytes, not from the bytes the files occupy. The pricing page lists storage at $0.2 per provisioned decimal GB-month. Billing docs state that rate as $0.20 per provisioned decimal GB for a 720-hour month. Platform sizes are commonly expressed in binary GiB, so a 10 GiB volume is 10.73741824 decimal GB and costs approximately $2.15 per 720 hours at that rate. The pricing page shows the same example as 10.74 decimal GB and about $2.15 per 720-hour month. Partial intervals are prorated. The rate, the unrounded 10 GiB figure, and that proration are in Billing and usage.
A volume’s size counts even when the app stores little data. It can grow and it cannot shrink, so pick the first size and the growth plan against storage behavior and pricing. Growing the volume moves storage billing to the new size at once.
When to use a managed database instead
A volume fits single-writer files on one service. It does not fit concurrent updates, transactions, or several services reading and writing the same records.
Use PostgreSQL or another database for that. On Unbroker the two shapes are different. A managed Postgres or MySQL cluster is provider-operated and requires Pro. An Apps database node is a database image and a persistent volume you operate, including recovery of that volume. Managed databases are not on Free. The plan list is managed Postgres. How to run the server you chose is Postgres in production.
Checklist
- On Pro, decide which files must survive a new container. Leave code and dependencies in the image.
- Pick one absolute path, such as
/data. Do not mount it over the application directory. - Point the app at that path. For the Node illustration, set
DATA_DIRand write only under it. - Attach the volume at that path. Confirm the runtime user can write there.
- Create a test record, redeploy, and read it back. Confirm the new code is live and the record stayed.
- Leave the size where you can grow later. You cannot shrink. The cap is 50 GB.
- Treat Reset, Detach, and deleting the service as deleting the data. Databases offer Reset, not Detach.
- Send backups to an S3-compatible destination you control. Restore once on an isolated target before the data is irreplaceable.
- If more than one service or replica must share the data, use a database or external object storage instead of this volume.
FAQ
Why do my files disappear after a redeploy?
They were on the container filesystem. Application containers are replaceable, and a deploy, restart, or reschedule can replace that container. Files written only there should be treated as temporary. A persistent volume is a different path. If the app never wrote to the mount, the volume can be empty after the old container is gone. That is Persistent storage and backups.
Does a persistent volume survive a redeploy?
Yes, when the app writes to the mounted absolute path. Create a test record, redeploy, and read it again. New code can be live while that record stays. A redeploy does not restore files that were never on the volume, and it does not undo Reset, Detach, or deleting the service.
Is a volume a backup?
No. A volume is the live disk for one service. A backup is a separate copy on an S3-compatible destination you control. The storage page says a persistent volume is not itself a backup, and to configure and test backups before placing irreplaceable data on it.
Can I shrink a volume?
No. A volume can grow, up to 50 GB, and it cannot shrink. Grow runs online without a restart, and storage billing moves to the new size at once. Choose the first size with that limit in view.
Do volume-backed services support multiple replicas?
No. A volume belongs to one service, and a volume-backed service runs one replica. It is not a shared filesystem for several replicas or several services. When more than one writer needs the same data, use a database or external object storage.
Does Free include persistent volumes?
No. The plans table lists persistent volumes as not available on Free and available on Pro. Pro is $25 a month with $25 of usage credit. See pricing and Plans.
What happens if I delete the service?
Deleting the service deletes the attached volume and its data. Reset and Detach also delete volume data. Neither can be undone. Both ask you to type the service name, and both wait until any running deployment, backup, or restore has finished.
How much does storage cost?
The pricing page lists storage at $0.2 per provisioned decimal GB-month, from the size you provision, not from how full the disk is. Billing docs state that rate as $0.20 per provisioned decimal GB for a 720-hour month. A 10 GiB volume is 10.73741824 decimal GB and costs approximately $2.15 per 720 hours. The pricing page shows that example as 10.74 decimal GB and about $2.15. Partial intervals are prorated.