Upgrades and backups

Upgrade

Pull the new images and recreate the containers. Migrations run on startup.

docker compose pull && docker compose up -d

If you use the local AI profile, rebuild the Laya image after an upgrade:

docker compose --profile ai build laya

Background jobs and the worker

Background work (maintenance today, and mail sync and the AI pass as they land) runs inside the same container. The image runs campbooks-server all, which is the API plus the job worker. Jobs live in Postgres, so nothing is lost on restart.

To run the worker separately, add a second service with the same image and environment and these two settings:

• command: ["worker"]
• healthcheck: { disable: true }, because the health check probes the API, which a worker does not serve.

Then give the first service command: ["api"]. Worker settings are the CAMPBOOKS_JOBS__* block in Configuration.

What to back up

Back these up together, at about the same time:

What	Where	Holds
Postgres	postgres-data volume (use pg_dump)	Everything except files and the instance secret key: accounts, sign-in keys, grants
Files	blobs-data volume, or your bucket	Raw messages, attachments, documents
Instance secret key	server-secrets volume	The key that opens the sign-in keys and stored credentials in Postgres

Also keep a copy of your .env and of the client secret files in deploy/secrets/. They are not in any volume.

:::warning Keep a copy of the instance secret key server-init generates the key once, on first boot. It seals the sign-in keys and the credentials of connected accounts. The key cannot be recovered if you lose it, so keep a copy somewhere safe, apart from your backups.

Without the right key, the server refuses to start. If the key is truly lost, you can start over with a new one:

1. Delete the rows of identity.signing_keys in Postgres.
2. Remove the key: docker compose run --rm server-init rm /secrets/secret-key.
3. Run docker compose up -d && docker compose restart server.

Everyone signs in again, and connected mailboxes show "needs reauthorisation" until their owner connects them again. Mail and documents already stored are not lost. :::

Restore Postgres and the files from the same point in time. A file that is missing from the store while Postgres still lists it cannot be read. So take the database dump first, then copy the files: files uploaded in between are only harmless extras. For a bucket, turn on versioning (and keep old versions for a few days) instead of copying.

Back up the local volumes with a throwaway container. For the files:

docker run --rm -v campbooks_blobs-data:/data -v "$PWD":/backup busybox:1.37.0-musl \
  tar czf /backup/blobs-data.tgz -C /data .

And for the instance secret key:

docker run --rm -v campbooks_server-secrets:/data -v "$PWD":/backup busybox:1.37.0-musl \
  tar czf /backup/server-secrets.tgz -C /data .

The archive holds the key itself, so store it somewhere only you can read.

Upgrading from the Rauthy sign-in

Earlier releases shipped Rauthy as the identity provider: the idp, idp-init and idp-provision services and the idp-data volume. Campbooks now signs people in itself, and the new compose.yaml has none of them.

1. Copy the new compose.yaml over yours, then remove the three old containers:

   docker compose up -d --remove-orphans

   Nothing breaks if you leave the old services running. They are just unused.

2. Accounts that lived in Rauthy are not carried over. Those people sign in again with Google, Microsoft, Zoho or a passkey, and get a new Campbooks account.

3. Move the old CAMPBOOKS_IDP_* provider settings to CAMPBOOKS_GOOGLE__*, CAMPBOOKS_MICROSOFT__* and CAMPBOOKS_ZOHO__*. Keep each client secret in deploy/secrets/<provider>-client-secret. See Sign-in.

4. Add ${CAMPBOOKS_PUBLIC_URL}/auth/callback/<provider> as a redirect URI in each provider's OAuth app.

5. The idp-data volume is left in place. Once you are sure you do not need it, delete it:

   docker volume rm <project>_idp-data

Monitoring (optional)

Campbooks writes JSON logs to stdout and exports nothing by default.

docker compose logs server

The CAMPBOOKS_TELEMETRY__* settings turn on a Prometheus page or OTLP export. See .env.example.