Key idea
Anything your app writes to its own filesystem disappears when the spherelet is replaced. Keep data somewhere built to keep it: a database, object storage, or a SphereFiles volume.
The spherelet's filesystem is scratch space
Each spherelet starts with a fresh copy of the filesystem from your image. Your app can write to it, but those writes belong to that one spherelet and vanish when it's replaced.
That happens more often than you'd expect: on every restart and every redeploy that applies a change, after a crash, and when you scale. A new spherelet never sees files an old one wrote.
So a service that saves uploads to /app/uploads works in testing, then loses every file on the next deploy. With two spherelets it's worse: an upload lands on one, and the next request may reach the other.
Stateless is the goal
A stateless service keeps nothing it needs on its own disk. Any spherelet can answer any request, so you can replace, restart or add spherelets without losing anything. Most web services and workers can be written this way.
Temporary files are still fine: a file you write, use and delete in one request, or a cache you can rebuild. The rule is only that losing the file must never lose data.
Where state belongs
| Kind of data | Where it belongs | Example |
|---|---|---|
| Records you query: users, orders | A database | SphereDB (managed PostgreSQL), or a database from a provider |
| Files your services read and write at a path | A volume (SphereFiles) | Uploads, media, generated reports |
| Files fetched by URL, or very many | Object storage | A bucket from your cloud or storage provider |
| Values that are cheap to lose | Memory or a cache | Rendered pages, rate-limit counters |
Object storage is a service that stores whole files by name over HTTP; "S3-compatible" means it speaks the same API as Amazon S3, so most libraries work with it.
For records, ComputeSphere runs SphereDB, managed PostgreSQL in your environment, or you can bring a database from a provider and connect with secrets (lesson 5.5.3). For object storage, bring a bucket from a provider. For files your services keep, it provides SphereFiles volumes: a volume stays in your environment when the spherelets using it are replaced, and several services can mount it at once.
What survives a redeploy
/app/uploadsfiles written emptynew spherelet, fresh from the imageFiles are gone
/datamounted volume/datasame volume, mounted againData is kept
Shared. A second spherelet mounts the same volume and sees the same files.
A volume or a database?
A volume looks like a folder, which makes it tempting for everything. It's a good home for files: every spherelet of every service that mounts it sees the same ones, so a service with a volume can still scale out. Copies of the files for recovery are up to you.
It's a poor home for records. A volume is network storage built for files, not for a database's own files, and two spherelets writing the same file at once can clash. A database handles connections from many spherelets at once and gives you queries and transactions (several changes that succeed or fail together). If you query it, put it in a database.
A quick test for any service
Imagine it running on three spherelets, then restarted. Would any request fail, or any data be missing? If yes, find the file or in-memory value that caused it and move it to one of the places in the table.
Variables and secrets are configuration, not data. Keep them in the service's settings rather than baked into the image, so the same image runs in every environment.
Check yourself