Volumes
Configure persistent storage volumes for your QuickStack applications: storage classes, access modes, and gotchas.
Volumes provide persistent storage for your applications. Data written to a volume path survives container restarts and redeployments.
Use volumes for: databases, file uploads, logs, any data that must persist.
For injecting read-only config files, see File Mounts instead.
Configure a volume
-
Open the app in the Project Canvas and go to Settings → Storage.
-
Click Add Volume.
-
Fill in the fields:
- Mount Path — path inside the container (e.g.
/data,/app/uploads) - Size in MB — storage to allocate. You can increase but not decrease after creation.
- Storage Class —
local-pathfor single-node;longhornfor multi-node clusters. - Access Mode — see below.
- Mount Path — path inside the container (e.g.
-
Click Save, then Deploy.
Deploy required Click Deploy in the app drawer header after adding or modifying a volume for changes to take effect.
Access modes
Access Mode is permanent The Access Mode cannot be changed after the volume is created. Plan before deploying.
| Mode | What it means | When to use |
|---|---|---|
| ReadWriteOnce (RWO) | Mounted by a single node at a time | Single-instance apps, databases |
| ReadWriteMany (RWX) | Mounted by multiple nodes simultaneously | Apps with replicas > 1 sharing writes |
Replication rule If your app runs with more than one replica and instances write to a shared path, you must use RWX. RWO with multiple replicas will cause mount conflicts.
Storage classes
| Class | Works on | Characteristics |
|---|---|---|
local-path | Single-node only | Fast, no replication, data lost if node fails |
longhorn | Multi-node | Replicated, supports failover, required for HA |
Manage volumes
- Resize — increase only; you cannot reduce a volume's size.
- Change mount path — allowed, requires a redeploy.
- Delete — permanently destroys all data on the volume. There is no undo. Back up first.
Troubleshooting
| Symptom | Fix |
|---|---|
| App can't write to volume | Verify mount path matches app config; check container file permissions |
| Volume not mounting | Verify the target node is online and has free disk space |
| Wrong access mode | Delete and recreate with the correct mode (backup data first — it will be lost) |
| Multi-replica app failing | Confirm you're using RWX, not RWO, for shared write paths |
Related
- Shared volumes — mount one volume in several apps
- File browser — browse and download volume contents
- File mounts
- Volume backup schedules
- Cluster node management (node affinity)