Maintenance

A self-hosted instance needs three things from its operator: updates, a backup, and an eye on certificates. All of it happens on the server, on the System page of the dashboard, or under Settings, Advanced. Managed beta instances are maintained by us, so this page only applies to self-hosted installs.

Updating

Releases are git tags in the form vX.Y.Z, built by CI into a Docker image. When a newer release exists, the System page shows its release notes and an update button. Automatic updates are set under Settings, Advanced.

Manual Updates

The System page shows an "Update to vX.Y.Z" button. It swaps the app to the new version with all data intact and takes about a minute, during which the dashboard is unreachable. Only the owner can start it, because it changes the running code for every member.

cd /opt/knecht
git fetch --tags && git checkout vX.Y.Z
sed -i 's/^KNECHT_VERSION=.*/KNECHT_VERSION=vX.Y.Z/' .env
docker compose pull && docker compose up -d

Automatic Updates

Under Settings, Advanced, the panel "Automatic updates" has a field for a cron expression in server time, for example 0 3 * * * for nightly at 03:00. Once set, Knecht updates itself as soon as a new release exists and no run is active. Leave the field empty to update by hand.

Host-Level Updates

The in-app update covers the app only. Docker, the DDEV CLI, and the DDEV image warm-up live on the host and are not touched. When a release needs a newer DDEV or a changed host setup, the release notes say so, and the provisioning script has to be re-run once:

sudo KNECHT_UID=1000 KNECHT_GID=1000 /opt/knecht/scripts/provision-host.sh

The script is idempotent and safe to run at any time.

Pre-Releases

Tags with a hyphen, such as v0.3.0-rc.1, are pre-releases. CI builds them like any release, but they are never offered as an update and a normal install ignores them. To test one, fetch the installer from that tag and pin the same tag with KNECHT_REF, so installer and version cannot diverge:

curl -fsSL https://raw.githubusercontent.com/knecht-works/knecht-cloud/v0.3.0-rc.1/scripts/install.sh \
  | sudo env KNECHT_DOMAIN=knecht.example.com KNECHT_REF=v0.3.0-rc.1 bash

Once the matching stable release is published, the instance offers it as a regular update. Updating from a stable version to a pre-release is not possible.

Backup and Rollback

All state lives in /data/knecht/data: the SQLite database, run archives, and uploaded database dumps. Back that folder up, or snapshot the whole server. Project checkouts under /data/knecht/projects are disposable, Knecht clones them again when needed.

Database migrations run forward only. Checking out an older release does not roll the schema back. Take a copy of /data/knecht/data before an update if you want a safe way back, and restore the copy together with the older tag.

On a Mac, both folders live inside the Lima VM. Reach them through limactl shell knecht, or back up the VM disk as a whole.

Certificates

Caddy handles TLS on its own. It fetches the certificate for the dashboard on first start and one certificate per preview hostname on demand, so the first visit of a new preview URL takes a few extra seconds. Nothing needs renewing by hand.

Let's Encrypt issues at most 50 new certificates per week per domain. Each newly visited preview hostname uses one, renewals do not. A team with many sessions per week can hit that limit. The way out is a wildcard certificate for the preview zone:

1. Delegate the preview subzone to a DNS provider with an API, for example preview.knecht.example.com NS -> Hetzner DNS. The main zone stays where it is.
2. Build Caddy with the matching DNS plugin.
3. In /opt/knecht/Caddyfile, replace on_demand with tls { dns <provider> }.