Docs Contact support
Docs menu

Backups and restoring

Back up the one SQLite file safely, use the backups that updates make, stream changes with Litestream, and restore.

Updated Nov 14, 2026 4 min read

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.

  1. Stop ChronoSlice.
  2. Move the current database and its -wal and -shm files out of the way. A stale -wal file from the old database must not sit beside the restored one.
  3. Put the backup in place under the database's name, and give it to the chronoslice user.
  4. 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.
Was this helpful?

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.