Upgrade and backup

What to keep

Keep the complete Starling data directory or the Compose starling-data volume, including the generated TLS certificate. Clients remember the certificate fingerprint as the server’s identity. Also back up your starling.toml, any included TOML files, and secrets kept outside the data volume. A distributed deployment may use external databases or object storage; back those up using their own consistent snapshot tools.

Stop the stack before copying its local data volume so SQLite files form a consistent snapshot. Docker Compose down keeps the volume; adding -v deletes it. Record the actual volume name with docker volume ls, since Compose normally prefixes it with the project name.

Upgrade

Read the Starling release notes, take a backup, then pull the new image and restart:

docker compose pull
docker compose up -d --wait
docker compose logs gateway

If you use a local build, update the source and run Docker Compose with —build instead. Keep the data volume mounted across restarts.

Migrate an existing deployment

Follow Migrating to Starling for configuration conversion, database import, and the checks to complete before switching clients.