Deploy
Updates and backups
Update in place, back up the database, uploads and secret, and restore from a backup.
Updating
git pull
docker compose --env-file deploy/.env up -d --build
Migrations run automatically when the API container starts.
What to back up
- The database: all your data.
- 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.
deploy/.env: it holdsBETTER_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.
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/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
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:
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
| Symptom | Fix |
|---|---|
| Sign-in does nothing, or says invalid origin | The address in the browser doesn't match APP_URL. Use it exactly, or add the other address to TRUSTED_ORIGINS. |
| Everyone was signed out | BETTER_AUTH_SECRET changed or was lost in a restore. Calendar connections need reconnecting too. |
| Invites aren't emailed | MAIL_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 allocated | On a local network, leave DOMAIN and COMPOSE_FILE unset and change HTTP_PORT. |
| Lost the setup link | Run docker compose restart api and check the log again. |
| Locked out as the only owner | Promote another member in the database: update workspace_members set role = 'owner' where user_id = '…'; |