Skip to content
Self-hosted

Self-hosted operations

Backups, upgrades, supported versions, health checks and logs for your Permafrost installation.

Test-environment key

One test key per account is available from your account page. Test keys need version 0.1.2 or later. It is valid while your production licence is valid. You are billed on the larger of your production and test installs each day, independently for human and non-human identities. A test install cannot be switched to production: use a new install to change environment. Requesting the test key again replaces its key and releases its install. Only an operator can restore an operator-revoked test key.

Backups are yours

You own the database and its backups. Back up Postgres 16 before upgrades and test restoration in your environment. Compose stores database data in the postgres-data volume. Keep a separate protected copy of configuration and secrets. Do not remove the database volume when stopping the app.

For Kubernetes, back up your external database or bundled Postgres volume. The bundled database is for evaluation and small installs. You operate its backups, recovery and availability. Uninstalling the chart retains its database PVC; it is not a backup.

Upgrades and supported versions

We support the two most recent versions and ship security fixes for both. Review release instructions, back up your database and verify the new image signature before upgrading. Set PERMAFROST_IMAGE=registry.permafrostepm.com/permafrost/app:0.1.4 in your environment file, or pin the verified digest. Log in with username license and your licence key as the password.

docker compose -f deploy/selfhost/docker-compose.yml --env-file deploy/selfhost/.env pull
docker compose -f deploy/selfhost/docker-compose.yml --env-file deploy/selfhost/.env up -d
docker compose -f deploy/selfhost/docker-compose.yml --env-file deploy/selfhost/.env ps -a

The migrate service must complete successfully before the app starts. Check its exit status after upgrading. For Helm, update the chart version and image tag or digest, then follow the Kubernetes upgrade steps. Recreate upgrades have downtime. A rollback of the image or chart does not undo database migrations.

Health endpoint

curl --fail http://localhost:3000/api/healthz

A healthy response is {"ok":true,"db":"ok"}. A database failure returns HTTP 503 with {"ok":false,"db":"error"}. This checks the app and database, not cloud access, licence validity or first sign-in. Block /api/healthz and /api/cron at external ingress. Helm readiness uses /api/healthz; startup and liveness probes use TCP port 3000.

Logs and stopping

docker compose -f deploy/selfhost/docker-compose.yml --env-file deploy/selfhost/.env logs app migrate scheduler
docker compose -f deploy/selfhost/docker-compose.yml --env-file deploy/selfhost/.env down

Inspect migration exit status, app logs and scheduler logs if startup or collection fails. Omit the volume-removal option when stopping. Keep logs private: the app log contains the initial setup code. The image supplies its own init process for signal handling, including plain docker run and Kubernetes.

For Kubernetes, use kubectl logs with the app, migrate or scheduler container. The Licence page at /licence inside the install holds the check audit log. Before an administrator exists, licence recovery is at /setup.

Sign-out and member removal

Sign out clears the local Permafrost session even when the licence has stopped. On an external HTTPS origin it also redirects to Microsoft sign-out. Localhost returns to the install without ending the Microsoft session.

Use Remove member in Settings to deactivate a member and revoke API keys they created. A user with member-management permission can do this, including during the read-only licence period. The last active administrator cannot be removed. Remove their assignment from the Microsoft Entra enterprise application too when withdrawing directory sign-in access.

When a licence lapses

After trial expiry without payment, payment failure, revocation or expiry of the 72-hour signed pass, the portal becomes read-only. Reads and exports remain available; collection and other writes stop. After 30 days normal portal access stops. Licence recovery and sign-out remain available, and data is not deleted.

Open /licence to inspect the reason and check again after restoring service. Correct a changed key in the environment and recreate the app. Use your account to replace keys or release an install before moving it. New pulls require a valid licence. See licensing for the outbound host and proxy settings.