Backups and restoring
Back up the one SQLite file safely, use the backups that updates make, stream changes with Litestream, and restore.
Everything ChronoSlice knows is in one SQLite database file. This page shows how to copy it safely, what the server backs up for you, an optional way to stream every change to remote storage, and how to restore.
What to back up
- The database,
/var/lib/chronoslice/chronoslice.db. It holds your time entries, clients, invoices, attached files, settings, your Stripe secret key, and your licence key. - The settings file,
/etc/chronoslice/env, and your Caddy or nginx configuration. They aren't in the database.
The database runs in WAL mode, so you may see chronoslice.db-wal and chronoslice.db-shm beside it while the server runs. Don't copy chronoslice.db with cp while the server is running, because you can catch it mid-write. Use one of the methods below.
[!WARNING] The database contains your Stripe secret key and everything about your clients. Keep every backup private.
A copy with sqlite3
sqlite3 .backup makes a consistent copy while ChronoSlice runs. Install the sqlite3 program if you don't have it (sudo apt install sqlite3).
sudo -u chronoslice sqlite3 /var/lib/chronoslice/chronoslice.db ".backup '/var/lib/chronoslice/chronoslice-copy.db'"
To do it every night, save this as /usr/local/bin/chronoslice-backup, make it executable, and keep the last 14 days:
#!/bin/sh
set -e
dir=/var/lib/chronoslice/backups
mkdir -p "$dir"
sqlite3 /var/lib/chronoslice/chronoslice.db ".backup '$dir/chronoslice-$(date +%F).db'"
find "$dir" -name 'chronoslice-*.db' -mtime +14 -delete
Run it from cron as the chronoslice user. Put this in /etc/cron.d/chronoslice-backup:
15 3 * * * chronoslice /usr/local/bin/chronoslice-backup
A backup on the same disk doesn't help if the disk dies. Copy the folder to another machine or to remote storage as well.
The backups that updates make
Each time you run chronoslice update, it copies the database before it swaps the program. The copy is backup-pre-<version>.db, in the same folder as the database, where <version> is the release you're installing. If that name already exists, it adds -2, -3 and so on. See Updating.
These are full copies and they pile up. Delete the old ones when you're sure the update went well.
Litestream (optional)
Litestream is a separate program that copies every change to the database to S3-compatible storage within seconds, so a lost server loses at most a few seconds of work. ChronoSlice doesn't need it or configure it. Install it from litestream.io/install. These steps are for Litestream 0.5.
Put this in /etc/litestream.yml:
access-key-id: YOUR_ACCESS_KEY_ID
secret-access-key: YOUR_SECRET_ACCESS_KEY
snapshot:
interval: 24h
retention: 168h # keep a week of restore points
dbs:
- path: /var/lib/chronoslice/chronoslice.db
replica:
url: s3://your-bucket/chronoslice.db
For storage other than Amazon S3, add the provider's endpoint and region to the URL. Litestream's documentation lists them for each provider. Then start it:
sudo chmod 600 /etc/litestream.yml
sudo systemctl enable --now litestream
journalctl -u litestream -f
Keep the bucket private, and give its access key only the rights it needs on that one bucket.
Restore
Restore onto a stopped server. Keep the files you're replacing until you know the restore worked.
- Stop ChronoSlice.
- Move the current database and its
-waland-shmfiles out of the way. A stale-walfile from the old database must not sit beside the restored one. - Put the backup in place under the database's name, and give it to the
chronosliceuser. - Start ChronoSlice.
sudo systemctl stop chronoslice
sudo mkdir -p /var/lib/chronoslice/old
sudo mv /var/lib/chronoslice/chronoslice.db* /var/lib/chronoslice/old/
sudo cp /var/lib/chronoslice/backups/chronoslice-2026-11-12.db /var/lib/chronoslice/chronoslice.db
sudo chown chronoslice:chronoslice /var/lib/chronoslice/chronoslice.db
sudo systemctl start chronoslice
To restore from Litestream onto a new server, before you start ChronoSlice:
sudo litestream restore -config /etc/litestream.yml /var/lib/chronoslice/chronoslice.db
sudo chown chronoslice:chronoslice /var/lib/chronoslice/chronoslice.db
Try a restore to a scratch path once, such as litestream restore -config /etc/litestream.yml -o /tmp/restore-test.db /var/lib/chronoslice/chronoslice.db, so you know it works before you need it.
Restoring and your licence
The licence key and this server's install id are stored in the database, so a restored database brings them back. To move to a different server on purpose, remove the key from the old one first. See Moving to another server.
Related
- Updating explains the database copy an update makes.
- Troubleshooting covers a server that won't start after a restore.
Still stuck?
Send us a request: it goes to the people who build ChronoSlice, and the reply comes by email. Include your ChronoSlice version (Settings › Licence shows it) and what you tried.