Volumes and persistent storage

Last updated

A volume is the only place your data survives. Everything else in the container's filesystem is discarded when the container is recreated — which happens on every deploy and every configuration change, not just when you intend it.

Add one

On the app's Volumes panel, add a volume and give it a container path — /data is a good default. Adding or removing a volume restarts the app to apply it.

Then make sure your application actually writes there. The usual mistake isn't the volume, it's the path:

# discarded on the next deploy
DB_PATH = "./app.db"

# survives
DB_PATH = os.environ.get("DB_PATH", "./app.db")   # set DB_PATH=/data/app.db on the app

Making the path an environment variable lets the same code run locally and deployed.

The failure is silent

This is worth stating plainly: when data is written outside a volume, nothing errors. Your app recreates an empty database or an empty upload directory and carries on, so you find out when someone mentions their data is gone.

If you're unsure whether a volume is working, use the Files tab to look at the path while the app is running.

One volume, one application

A volume belongs to exactly one app. Two applications cannot share one, which decides more architecture than people expect:

  • A bot and a web dashboard that need the same data need a real database, not a shared file.
  • An uploader and a processor can't pass files through a volume.

If more than one process needs the data, see Databases.

Disk is an account-wide limit

Your disk usage is the total size of all your volumes. Images and build layers don't count.

If that total exceeds your account limit, every application in the account is stopped and none can start until it drops back below. Not only the app that filled up.

So anything that grows on its own deserves a pruning policy from the start:

  • User uploads
  • Log files written to a volume
  • Database backups
  • Message or conversation history

Watch the trend rather than the level, and prune on a schedule rather than when something breaks.

Backups

Nothing is backed up for you. A volume is durable storage, not a backup — it doesn't protect against your own code deleting the wrong thing, or against the app being deleted.

For a small project, taking a dump and downloading it from the Files tab is a complete routine, and better than the automated backup you haven't written. For anything you'd be upset to lose, write the dump on a schedule and ship it off the platform.

System volumes

Some deploy paths create a system volume for your application directory. These can't be removed — add your own volume for application data rather than trying to reuse it.