Files and persistent storage

A deployment replaces the application filesystem with the files built for that version. Data written by the running app needs a persistent directory when it should survive that replacement.

Last updated

AI agent? Start with llms.txt.

Use /tokay/data for files new code writes, or mark an existing application directory as persistent.

Code resets while app owned data persists

Files included in the build are recreated on each deploy. This makes a deployment and rollback reproduce the version that was built.

Files under /tokay/data are different. They belong to the Service across deployments and restarts. Tokay also provides the path through TOKAY_DATA_DIR so the code can avoid hardcoding it.

A file written beside the source, such as ./uploads/photo.jpg, is temporary unless that directory is marked persistent.

Keep an existing application path

Open the Persistent Storage section in Service settings and add the directory the app already uses. Tokay also suggests write paths it detects in the code.

A newly attached persistent directory starts empty. If the build contains files at the same path, the empty persistent directory covers them on the next deployment. The confirmation explains this before the change is applied.

Detaching a directory stops mounting it but keeps its stored data. Deleting the data is a separate action. If important files already exist in a temporary path, rescue them before the current instance changes. See Service files.

Persistent data is protected outside the VM disk

Your persistent directories and managed databases live on your workspace's data volume, and we replicate it to a second server, so a hardware failure doesn't take your data with it. We also back it up offsite every day and keep 7 daily and 4 weekly backups, a recovery point for severe failures or data that was deleted by mistake. To restore from a backup, contact Tokay support.

Choose persistence based on the file type

User uploads, generated reports, and a SQLite database file need persistent storage. Caches and temporary files usually should reset with the release.

Files in /tokay/data and persistent directories belong to one Service, so other Services in the Project cannot read them. Files several Services read go in the Project's shared directory, described below. Data that the app searches and updates, or that several processes change at once, usually fits better in a Project database such as Postgres or Redis. You can query it from the dashboard and export it, and Tokay snapshots it before each migration. See Databases.

Content that changes more often than your code, such as generated pages or refreshed datasets, belongs in a database or persistent storage rather than in your code, because every push is analyzed, built, and deployed.

Share files between Services in a Project

Every Service in a Project, including its scheduled jobs and one-off tasks, can read and write one shared directory at /tokay/shared. Tokay also provides the path through TOKAY_SHARED_DIR. A file one Service writes there is ready for the others, the way two programs on your computer share a folder. It suits large files such as datasets, models, and generated output.

Each file keeps the owner and permissions of the process that wrote it, as on any computer. A file uploaded through Saved files belongs to the user of the Service it was uploaded through. Services Tokay builds run as the same user, so this matters only when a Service's own Dockerfile picks a different user. That Service can read files another user wrote but cannot replace or delete them.

The shared directory is persistent like /tokay/data. It survives deploys, is protected the same way, and stays until the Project is permanently deleted. Its disk use appears on the Project's Usage page.

A directory does not tell anyone that a file changed, so send messages between Services through Redis or an HTTP call. Release commands, which run before a new version takes traffic, see neither directory. Because every Service in the Project can write here, a Service should trust these files only as far as it trusts the others.