Persistent storage: shared files that survive restarts
Persistent storage for your app: one network folder every replica shares, kept through restarts, redeploys and pauses. For uploads, media and models.
What persistent storage is on ProductEcho
Persistent storage is a folder inside your app whose files are kept when the app restarts, is redeployed or is paused. On ProductEcho you add it to a full-stack app by choosing a storage path, such as /data. Every replica of the app, meaning every running copy, mounts the same folder, so a file that one replica writes is there for the others at once.
The folder is a network file system (NFS): an ordinary tree of folders and files that lives apart from the server your app runs on. It grows as you add files, so there is no size to pick and nothing to resize later.
- Shared by every replica. All copies of the app read and write the same files, including the old and the new copy that run side by side during a redeploy.
- Kept through restarts, redeploys and pauses. The files also stay when ProductEcho moves the app to another server.
- Encrypted. Files are encrypted at rest and on the network between your app and the folder.
- One folder per app. No other app can open it, including the other apps in your workspace.
Persistent storage vs ephemeral storage
Without persistent storage, a full-stack app has only ephemeral storage: its own disk, which starts empty every time the app starts. The table shows what changes when you add a storage path.
| About | Ephemeral storage (the default) | Persistent storage |
|---|---|---|
| A file the app writes | Gone at the next restart, redeploy or move to another server. | Kept until the app deletes it. |
| Two or more replicas | Each replica sees only its own files. | Every replica sees the same files. |
| Pausing and resuming the app | The app comes back with an empty disk. | The app comes back with the same files. |
| Speed | Local disk speed. | Network speed: fast for large files, slower for thousands of small ones. See Good to know. |
| Which user the app runs as | The user its image names, root included. | Never root. See Which user your app runs as. |
Persistent storage is a setting on a full-stack app. Static sites have no running process, so they cannot have a storage path.
Use cases: uploads, media, models and more
These use cases share one trait: the app creates the files while it runs, and every replica must see them. Each row names a folder you could use under a /data storage path.
| Use case | What goes in the folder | Example |
|---|---|---|
| User uploads | Photos, avatars and attachments that your users send. | /data/uploads |
| Content management | The media library of a CMS or blog: images, PDFs and files that editors upload. | /data/media |
| Web serving | Images, downloads and generated pages that the app serves, so every replica serves the same file. | /data/public |
| Per-user folders (home directories) | One folder per user or customer, created by the app. | /data/users/42 |
| Machine learning | Model files and datasets, downloaded once and then loaded by every replica and after every restart. | /data/models |
| Shared cache | A cache that is slow to rebuild, such as resized images. | /data/cache |
Do not put a database's data folder in persistent storage, SQLite included. The folder is reached over the network, so database writes are slow, and two replicas writing one database file can corrupt it. Use PostgreSQL instead.
Code and dependencies do not belong there either. They come from your image at every deploy, and folders such as node_modules hold thousands of small files, which are slow to read over the network.
Add persistent storage to an app
You add persistent storage by giving the app a storage path, in the console or through your coding agent.
Open the app's Settings tab
Enter the path
/data, and choose Add storage path.Wait for the new release
When you deploy a new app from the console, you can set it at once: open the Compute section, tick Keep files across restarts and enter the path. A connected coding agent can do the same, when it deploys the app or later:
If your image already has files at the path you choose, the app no longer sees them: the shared folder sits on top of them. Nothing is copied into the shared folder. Choose an empty folder, or have the app copy its starting files in when it starts.
Point your framework at the folder
Your app then saves its files under the storage path, for example /data/uploads/avatar-42.png. Read the path from an environment variable, set on the app's Environment tab, so that the same code also runs on your computer with a local folder.
| Framework | Where the path goes |
|---|---|
| Django | MEDIA_ROOT = os.environ.get("MEDIA_ROOT", BASE_DIR / "media"), with MEDIA_ROOT=/data/media on ProductEcho. |
| Rails Active Storage | In config/storage.yml, set the root of the Disk service to a folder under the path, such as /data/storage. |
| Express with multer | multer({ dest: process.env.UPLOAD_DIR }), with UPLOAD_DIR=/data/uploads on ProductEcho. |
| PHP | Pass a path under the storage path, such as /data/uploads/, to move_uploaded_file(). For the web server to serve the files directly, make the storage path a folder inside your web root. |
| Hugging Face models | Set HF_HOME=/data/huggingface, so a model is downloaded once and every replica loads it from there. |
Paths you can use
- It starts with
/, for example/dataor/app/uploads. - It uses letters, digits and
. _ - /only, up to 255 characters. - It has no
.,..or empty parts, and it is not/itself. - It is not at or under a system folder:
/proc,/sys,/dev,/etc,/bin,/sbin,/lib,/lib64,/usr,/run,/var/runor/tmp. - It is not at or under
/workspace,/layersor/cnb, where an app built from source keeps its own code.
Mounting a folder over a system folder would break the app or let it start in a broken state, so these paths are refused with a message that names the problem.
Which user your app runs as
An app with persistent storage never runs as root, because the folder is reached over the network and shared by every replica. ProductEcho decides the user each time the app is released:
| Your image | The app runs as |
|---|---|
Names a numeric user that is not root, such as USER 1001 | That user. Nothing changes for the app. |
| Runs as root, or names no user | The storage folder's own user, a number from 20000 up. |
Names its user by name, such as USER appuser (apps built from source without a Dockerfile do this too) | The storage folder's own user, because ProductEcho cannot be sure what number the name stands for. |
The Settings tab shows the user and the reason, for example "Runs as user 20001". Inside the storage path the app can always read and write: every file there belongs to the folder's user, whatever user the app runs as.
When the app runs as the folder's user, folders that your image created for its own user may become read-only to it. Write to the storage path instead. A few other things to know:
chowninside the storage path is refused. Start scripts that try to change who owns the folder fail.- Changing to another user with
sudo,su,gosuorsu-execdoes not work. Images that switch users at start usually detect this and keep running as the user they were given. - If your image expects its user to exist by name, for example to use its home folder, it can fail. Give the image a numeric non-root user to avoid this.
Good to know: speed and shared writes
- Speed. Persistent storage is reached over the network, so large files are fast and many small files are slower. Measured from an app on ProductEcho in November 2026: a 100 MB file was written in 0.37 seconds, while 1,000 small files took 9.5 seconds to write and 3.1 seconds to read, about 10 ms and 3 ms per file.
- Shared writes. When several replicas may write the same file at once, the app must take a lock first, as with any shared folder. Giving each file its own name, such as an upload ID, avoids the problem.
- Size. There is no fixed limit. The folder grows as you add files and shrinks as you delete them.
Change or remove the storage path
To move the files to another path, choose Change path on the Settings tab, enter the new path and choose Move files. The same files appear at the new path after the app restarts. Nothing is copied or lost.
To stop using persistent storage, choose Remove and type the app's name to confirm. ProductEcho restarts the app without the folder, then deletes the folder and every file in it.
There are no backups. Removing the storage path, or deleting the app, deletes its files within seconds, and they cannot be recovered. Copy anything you need out of the app first.
Common questions
Can every replica write to persistent storage at the same time?+
Yes. Every replica mounts the same folder with read and write access, and a file that one replica writes is visible to the others at once. Take a lock when two replicas may write the same file.
Do the files stay when I pause the app?+
Yes. Pausing stops every replica but keeps the folder and every file in it. The app sees the same files when you resume it.
Can two apps share one storage path?+
No. Each app's folder belongs to that app alone. Another app, including one in your own workspace, cannot open it. To share files between apps, have one app serve them to the others.
Are my files backed up?+
No. Files survive restarts, redeploys, pauses and server replacement, but a file that is deleted, or a storage path that is removed, is gone for good.
What is ProductEcho's persistent storage built on?+
An encrypted Amazon EFS file system, mounted into the app over NFS 4.1 with TLS. Each app gets its own folder, which only that app can open.