Storage and filesystem
Choose the right location for temporary files, persistent application data, and backups.
Application files are read-only
Section titled “Application files are read-only”The image contains code, assets, and installed dependencies. Its root filesystem is read-only at runtime. Writing beside source files, installing packages at startup, or creating a cache under the application directory can fail.
Build executable files and dependencies into the image. Point framework caches, session files, and uploads at a writable directory. An unprivileged application user must also have permission to write there.
Use /tmp for disposable files
Section titled “Use /tmp for disposable files”The temporary directory is writable and limited to 100 MB. Use it for small intermediate files the application can recreate. Its contents do not survive container replacement.
The temporary mount does not allow execution. Do not download a binary into /tmp and expect to run it. Clean up temporary uploads and processing files promptly so one request cannot exhaust the available space.
Use the data mount for durable files
Section titled “Use the data mount for durable files”Each application has a named data volume mounted at /data by default. Files there survive container restarts and replacements on the same worker. Configure the mount path in application settings when a framework expects another location.
Store SQLite databases, uploads, and necessary local state here. Test filesystem ownership with the production image user. The data mount does not allow execution; application binaries belong in the image.
UPLOAD_DIRECTORY=/data/uploadsSQLITE_PATH=/data/app.db
Understand where files are stored
Section titled “Understand where files are stored”The volume belongs to the worker hosting the application. It is not a shared filesystem across regions or independent apps. Do not assume recreating the app on another worker transfers its files.
Deleting an application removes its data volume. Export data before deletion or migration. Resource limits apply to stored data too; monitor disk usage and clean up files no longer needed.
Keep backups outside the application
Section titled “Keep backups outside the application”Back up to an independent destination and test restoration. Use database-aware backup methods for SQLite or another database so backups are consistent while the application runs.
Use external object storage for large uploads or files that need storage and distribution independent of the app. A mounted volume preserves files across redeployment, but does not replace a backup plan.