Volumes & backups

An instance from the template keeps bytes in a handful of places. They are not equally precious, and treating them alike is how a box loses its certificates to a cache cleanup, or backs up gigabytes it could have rebuilt. Every one of them is one of three kinds:

• State — the store itself, or something it cannot run without. Back it up; never delete it to rebuild.
• Record — what happened (logs). Nothing breaks without it, but it is what you read when something did. Keep it across a rebuild if you are diagnosing; it does not need a backup.
• Disposable — a copy of something that lives elsewhere. Delete it freely; it refills, at the price of a slower first visit.

The classification

What	Where	Kind	Back up?	On a rebuild of the box
The database	your managed Postgres (DATABASE_URL) — not in the compose file	State — products, orders, customers, apps’ data, the audit trail	Yes: snapshots + point-in-time recovery, and a restore you have tested	Untouched — it is not on the box
FORGE_VAULT_KEY	your secret store (env-source.sh)	State — it decrypts the payment and ERP credentials apps keep in the database	Yes, separately from the database backup	Must be the same key, or those credentials are unreadable
Media	your bucket (s3 / gcs driver)	State	The bucket’s own versioning or lifecycle	Untouched
The instance directory	forge.lock, compose.yml, .env, caddy/, extensions/, i18n/	State — it is the instance: the pin, the config, your apps	In git	Clone it again
caddy_data	volume	State you can rebuild — the TLS certificates and the ACME account	Optional	Keep it. Without it the edge requests every certificate again, which needs DNS already pointing at the box and counts against the issuer’s rate limits
caddy_config	volume	Disposable — Caddy’s own autosave, regenerated from the Caddyfile	No	Delete freely
caddy_logs	volume	Record — the edge’s access log, bounded (see Edge access log)	No	Keep it if you are diagnosing; otherwise delete freely
storefront_cache	volume	Disposable — the storefront’s cached reads of the kernel (see Storefront data cache)	No	Delete freely; the first visit to each page is slower until it warms. Empty it after a long rollback
redisdata	volume	Disposable, with a cost — cache and sessions	No	Losing it signs shoppers and operators out and slows the first requests; nothing else

⚠️ The local media driver. With no bucket configured the kernel uses the local driver, and with FORGE_MEDIA_LOCAL_DIR unset that driver keeps uploads in the kernel’s memory: they are gone at the next restart. A production box uses a bucket. If it must keep media on its own disk, set FORGE_MEDIA_LOCAL_DIR to a directory on a volume you add to the kernel service — and that volume is then state, backed up with the database.

Rebuilding without losing state

docker compose down        # stops and removes the containers; every volume is kept
docker compose up -d

docker compose down -v removes every named volume of the project — the certificates and the access log included, not only the caches. To drop one disposable volume, name it:

docker compose rm -sf storefront
docker volume rm <project>_storefront_cache
docker compose up -d storefront

What a backup does not need

Nothing disposable, and nothing that is a record. A restore is the database, the vault key, the bucket and the instance directory; every volume on the box can be recreated empty from those four.

See also

• Upgrade & roll back — the snapshot before a bump is the data’s only undo.
• Disk alarm — the box tells you before any of this fills its disk.