Persistent storage
By default, an instance file system is ephemeral: files written by the application disappear when the instance restarts, receives a new version, or is replaced. Persistent storage keeps a directory you choose across restarts and deployments.
Without persistent storage, each instance uses a temporary disk with the size included in the plan, plus 1 GB reserved for temporary files and logs. It needs no setup and follows the plan when you change plans. Everything the application writes outside persistent storage, including /tmp, stays on this disk, not in the instance memory. When an instance exceeds that limit, the platform replaces it with a new one: it shows up under Instances as replaced, with the reason, and if e-mail alerts are on you receive a notice. Reduce temporary files, move to a plan with more disk or keep the files in persistent storage.
When to use it
Use persistent storage when the application needs to:
- keep user uploads;
- store generated files, such as PDFs, reports, or exports;
- preserve data of ready-made applications, such as n8n, Metabase, or WordPress;
- keep working files between processing steps.
Do not use it when data can be recreated at any time (local cache, temporary build files) or when a managed database is the right tool. Structured data, queries, and transactions belong in a database, not in files.
How to configure
Storage is defined when you create the HTTP project, in the Configure storage step:
- Choose Yes for Does the application need to keep files?. With No, the Console only shows the temporary disk included in the plan.
- Set the capacity, between 1 GB and 250 GB.
- Enter the directory to persist: the absolute path, inside the application, where files are written. Examples:
/data,/app/uploads,/var/www/html/wp-content.
Important: the persisted directory cannot be changed after creation. Check your application or image documentation for the path that stores its data.
Some plans include a storage allowance; capacity above it is billed as shown in the summary before you confirm. The price per GB comes from the storage catalog: with hourly billing, the charge is proportional to time (monthly price ÷ 720 per hour); with a monthly contract, the monthly price per GB is charged at creation; with a yearly contract, 12 times that amount.
Durability
Persistent storage data is replicated in three copies. If a Zenifra server fails, the files remain available to the project.
Replication is not a backup: a file deleted or corrupted by the application is deleted or corrupted in every copy. Keep external copies of critical data.
Changing capacity
| Payment model | What is possible |
|---|---|
| Hourly | Increase capacity at any time. Decreasing is not allowed. |
| Monthly or yearly | Capacity is fixed during the contracted period. |
| Free plan (legacy) | Capacity cannot be changed. |
This applies to persistent storage; the temporary disk follows the plan. You can increase capacity while the project is running or stopped. If the organization has pending payments, increases are blocked until the balance is settled.
You can increase it in Edit project or through the storage API, with the project.storage.update permission. The API returns STORAGE_SIZE_CANNOT_DECREASE for reductions and STORAGE_UPDATE_NOT_ALLOWED_FOR_CONTRACT when the payment model does not allow the change, and STORAGE_UPDATE_NOT_ALLOWED_FOR_FREE_PLAN on the Free plan.
Monitoring usage
On every plan, the console shows used space on the project page. Through the API, use GET /project/:id/storage/usage with project.metrics.read. Track growth and increase capacity before reaching the limit: an application without disk space usually fails to write files or to start.
Preview environments
Previews get new, empty storage. Files from the main project are not copied. See Preview environments.
Next steps
- Environment variables
- Project configuration
- Create an HTTP project in the console
- Production checklist
FAQ
Can I add persistent storage after creating the project?
Storage activation and directory are defined at creation. If the project was created without storage, create a new project with the desired configuration and migrate the application.
Do multiple instances share the same files?
Yes. The persisted directory is the same for all of the project's instances. Still, for data that several instances must read and write consistently at the same time, prefer a database or a managed service.
What happens to the files when I delete the project?
Deleting the project permanently removes the storage and its files. Back up before deleting.
Last updated on
Environment variables
Set environment variables and secrets in Zenifra projects via console, CLI or API: up to 50 per project, restart on save, build-time use and best practices.
Network and access control
Choose a public or private Zenifra HTTP project, understand the *.clients.zenifra.com subdomain and restrict access by IP with CIDR whitelist and blacklist.