Skip to main content

Operations

Running it once it is up: the first account, updates and backups.

The first administrator​

There is no console step. On an empty database the instance says so, and one request creates the first account as an administrator. It stops working as soon as any account exists.

curl -s https://your.instance/api/instance
# {"needs_setup":true, ...}

curl -s -X POST https://your.instance/api/v1/setup \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada","email":"ada@example.org","password":"a long enough password"}'

Through the web client the same thing happens in a form: it reads that answer and sends you to /setup before offering to sign you in.

:::danger Create it immediately Between the moment the instance becomes reachable and the moment that request is made, setting up is open to anyone who finds the address, and whoever gets there first becomes the administrator. Do it as the first thing after the domain resolves, not tomorrow. :::

Updating​

The Quadlet unit is labelled AutoUpdate=registry, so a newer image is picked up with:

sudo podman auto-update

Enable podman-auto-update.timer to have it checked periodically. With Compose:

podman compose pull app
podman compose up -d

Either way, migrations run automatically on start, so there is nothing to do afterwards.

:::warning Changing the PostgreSQL major version is not an update Application updates are safe to apply as above. Moving PostgreSQL itself between major versions, say 17 to 18, is a different operation: the data directory format changes, and the new server will refuse to start on the old one. It needs pg_upgrade, or a dump taken with the old version and restored into the new. Never just change the tag on a volume that has data in it. :::

Backups​

Two things to copy, and one of them is easy to forget. See Configuration for the volume names.

# The database
podman exec kinkeep-db pg_dump -U kinkeep kinkeep_prod > kinkeep-$(date +%F).sql

# The uploaded media
podman volume export kinkeep-uploads --output kinkeep-uploads-$(date +%F).tar

A database dump on its own restores the records but not the photographs, and the application will show broken images for every one of them.

:::tip A backup you have not restored is not a backup Restore into a scratch instance once, and find out then whether anything is missing, rather than on the day you need it. :::

Logs​

# Quadlet
sudo journalctl -u kinkeep.service -f
sudo podman logs -f kinkeep

# Compose
podman compose logs -f app