Key idea
A SphereFiles volume is shared storage that lives in an environment. You mount it on a service, which makes it appear as a folder such as /data, and whatever your app writes there survives when a spherelet is replaced. Every spherelet of every service that mounts it sees the same files.
Two pieces, two places
You set up storage in order: a volume in the environment, then a mount on each service that needs it. SphereFiles comes with every plan, and is available in US East and EU (Sweden).
- A volume has a fixed size, picked from a list that runs from Files 10 GB to Files 16 TB. You pay for the size you pick, at $0.25 per GB a month, so Files 10 GB is $2.50 a month. Billing starts when it's created.
- A mount attaches the volume to a service at a path. One volume can have up to 63 mounts, across the services of its environment.
What each plan can create:
| Plan | Volumes per environment | Largest size |
|---|---|---|
| Hobby | 1 | Files 10 GB |
| Pro | 5 | Files 1 TB |
| Team | 10 | Files 4 TB |
| Enterprise | Any | Files 16 TB |
Sizes you can't pick show greyed, with the reason: Above your plan's largest size, or Not offered in this region right now when the region has no room for them. Today that's every size above Files 500 GB.
1. Create a volume
- Open the environment, and from its options menu choose Storage management.
- Under SphereFiles volumes, choose New volume.
- Enter a Name, for example
notes-data, and pick a size. The dialog shows what the volume adds to your bill. - Choose Create volume.
The list shows each volume with its size and its mounts. Choose Open on a volume to manage it.
2. Mount it on a service
- Open the volume, and under Mounts choose Add mount.
- Under Service, choose the service.
- Enter the Mount path, for example
/data. It must start with/. - Choose Mount volume.
The service's spherelets restart one at a time to pick up the volume: a new spherelet is ready before an old one stops, so there's no downtime. Repeat Add mount for each service that needs the same files.
Your app must write to that exact path. If it writes to /app/data and you mounted /data, the files still land on the spherelet's own filesystem and are lost.
Things to design around
- Scaling is fine. A service with a volume can run several spherelets, and every one sees the same files.
- Several writers need a plan. Services and spherelets can all write at once. If two might write the same file at the same moment, use file locks in your app or give each writer its own folder. One writer with many readers needs nothing extra.
- It's for files, not databases. A volume is network storage built for uploads, media and shared files. Records you query belong in a database (lesson 5.5.3).
- Mount a folder your app owns, not one your image already fills (like
/app). The volume hides what was at that path.
Read-only mounts, unmount, grow and delete
- Read-only: in a mount's actions, choose Make read-only. That service can read the files but can't change them. It applies within a few seconds, with no restart.
- One folder: when you add a mount, Folder of the volume (optional) mounts one folder inside the volume instead of the whole volume, for example
uploads. A folder can't contain... - Unmount: in a mount's actions, choose Unmount. The files stay on the volume, and that service's spherelets restart without it.
- Grow: under Size, choose Make larger. Growing pauses the volume, which usually takes a few minutes: services can't read or write its files during the pause, then carry on. A volume can't be made smaller.
- Delete: in the Danger zone, choose Delete volume. Unmount it from every service first. Deleting a volume deletes every file in it, and it can't be undone.
Under Files, Browse files opens a file browser for checking what your app wrote, and for uploading and downloading files. From a terminal, csph volumes ls lists an environment's volumes and csph files cp copies a file to or from one. Mounts are made in the console.
Check yourself