Skip to content

Deploy

Updates and backups

Update in place, back up the database, uploads and secret, and restore from a backup.

Updating

terminal
git pull
docker compose --env-file deploy/.env up -d --build

Migrations run automatically when the API container starts.

What to back up

  1. The database: all your data.
  2. The uploads volume: images and attachments. The database only holds their names. Skip it if you use S3 storage and rely on the bucket's versioning.
  3. deploy/.env: it holds BETTER_AUTH_SECRET. A database restored without the same secret signs everyone out, disconnects every calendar and resets every kiosk PIN.

Take the database dump and the uploads copy at about the same time, so they match.

terminal
docker compose --env-file deploy/.env exec -T db pg_dump -U knotworking knotworking \
  | gzip > knotworking-$(date +%F).sql.gz

A nightly backup

A script that dumps the database, the uploads and the settings, encrypts them, keeps 14 days locally and copies them off the machine:

/usr/local/bin/knotworking-backup
#!/usr/bin/env bash
set -euo pipefail
cd /opt/knotworking
dest=/var/backups/knotworking
key="$(cat /root/backup-key.pub)"
mkdir -p "$dest" && chmod 700 "$dest"
stamp=$(date +%F)

docker compose --env-file deploy/.env exec -T db pg_dump -U knotworking knotworking \
  | gzip | age -r "$key" > "$dest/db-$stamp.sql.gz.age"
age -r "$key" -o "$dest/env-$stamp.age" deploy/.env
docker compose --env-file deploy/.env exec -T api tar -C /app/data/uploads -czf - . \
  | age -r "$key" > "$dest/uploads-$stamp.tar.gz.age"

find "$dest" -type f -mtime +14 -delete
rclone copy "$dest" remote:knotworking-backups   # off the machine, so a dead disk doesn't take the backups too
crontab
15 3 * * * /usr/local/bin/knotworking-backup >> /var/log/knotworking-backup.log 2>&1

Every few months, restore the latest backup into a throwaway database to check it works.

Restoring

Restore into a fresh installation, before anyone signs in, with the same deploy/.env:

terminal
docker compose --env-file deploy/.env up -d db
gunzip -c knotworking-DATE.sql.gz \
  | docker compose --env-file deploy/.env exec -T db psql -U knotworking knotworking
docker compose --env-file deploy/.env up -d

If the API already ran against the new database, it created empty tables. Stop api and web, drop and recreate the database, then restore as above. Put the uploads back into the volume before people start uploading.

Health checks

The api, web and mcp containers have Docker health checks. The API's only checks that the process answers HTTP. It does not query the database, so a suspended hosted database still shows as healthy. For monitoring, check the sign-in page or a real request.

Troubleshooting

SymptomFix
Sign-in does nothing, or says invalid originThe address in the browser doesn't match APP_URL. Use it exactly, or add the other address to TRUSTED_ORIGINS.
Everyone was signed outBETTER_AUTH_SECRET changed or was lost in a restore. Calendar connections need reconnecting too.
Invites aren't emailedMAIL_FROM isn't a sender your provider accepts, or the scheme doesn't match the port. The API log shows the SMTP error.
Port 443 or 80 is already allocatedOn a local network, leave DOMAIN and COMPOSE_FILE unset and change HTTP_PORT.
Lost the setup linkRun docker compose restart api and check the log again.
Locked out as the only ownerPromote another member in the database: update workspace_members set role = 'owner' where user_id = '…';