Deployment

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.

Updated

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.

AboutEphemeral storage (the default)Persistent storage
A file the app writesGone at the next restart, redeploy or move to another server.Kept until the app deletes it.
Two or more replicasEach replica sees only its own files.Every replica sees the same files.
Pausing and resuming the appThe app comes back with an empty disk.The app comes back with the same files.
SpeedLocal disk speed.Network speed: fast for large files, slower for thousands of small ones. See Good to know.
Which user the app runs asThe 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 caseWhat goes in the folderExample
User uploadsPhotos, avatars and attachments that your users send./data/uploads
Content managementThe media library of a CMS or blog: images, PDFs and files that editors upload./data/media
Web servingImages, 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 learningModel files and datasets, downloaded once and then loaded by every replica and after every restart./data/models
Shared cacheA cache that is slow to rebuild, such as resized images./data/cache
Not for databases

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.

01

Open the app's Settings tab

In the console, open Apps, choose the app, then Settings.
02

Enter the path

Under Storage path, type the folder inside the app, for example /data, and choose Add storage path.
03

Wait for the new release

ProductEcho restarts the app with the folder mounted, without rebuilding it. The card then shows the path and the user the app runs as.

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:

text
/productecho-plugin:productecho-deploy give the photo-app application a storage path at /data for user uploads
Files already at that path are hidden

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.

FrameworkWhere the path goes
DjangoMEDIA_ROOT = os.environ.get("MEDIA_ROOT", BASE_DIR / "media"), with MEDIA_ROOT=/data/media on ProductEcho.
Rails Active StorageIn config/storage.yml, set the root of the Disk service to a folder under the path, such as /data/storage.
Express with multermulter({ dest: process.env.UPLOAD_DIR }), with UPLOAD_DIR=/data/uploads on ProductEcho.
PHPPass 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 modelsSet 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 /data or /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/run or /tmp.
  • It is not at or under /workspace, /layers or /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 imageThe app runs as
Names a numeric user that is not root, such as USER 1001That user. Nothing changes for the app.
Runs as root, or names no userThe 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:

  • chown inside the storage path is refused. Start scripts that try to change who owns the folder fail.
  • Changing to another user with sudo, su, gosu or su-exec does 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.

Removing the path or deleting the app deletes the files

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.

Read PostgreSQL databases