Skip to content
Self-hosted

Self-hosted Docker Compose

Get your licence, configure Docker Compose and complete setup through the first sync.

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.

Get a licence key

Register at /self-hosted/register with your company email, company name and country. Accept the licence agreement and verify your email. Each company receives one 30-day trial. The trial starts when verification creates the account.

Your key is shown once. Save it privately. Use your account to replace a lost key or release an install before moving it. Replacing a key invalidates the old credential immediately; an issued signed pass can last until its 72-hour expiry.

Start a 30-day trial

Log in and verify the image

The image is published at registry.permafrostepm.com/permafrost/app. Enter your licence key as the password for username license. A valid licence is required for new pulls.

docker login registry.permafrostepm.com --username license
docker pull registry.permafrostepm.com/permafrost/app:0.1.4

The release workflow signs the image and chart by digest. It attaches an SPDX software bill of materials (SBOM) to the image. Resolve the image tag, verify its digest with the exact signing identity below, then pin that digest in your deployment.

docker buildx imagetools inspect registry.permafrostepm.com/permafrost/app:0.1.4 --format '{{.Manifest.Digest}}'
# Replace sha256:DIGEST with the returned digest.
cosign verify --certificate-identity https://github.com/dunesoftwarestudios/permafrostepm/.github/workflows/selfhost-publish.yml@refs/heads/main --certificate-oidc-issuer https://token.actions.githubusercontent.com registry.permafrostepm.com/permafrost/app@sha256:DIGEST

Resolve the chart digest with helm show chart oci://registry.permafrostepm.com/charts/permafrost --version 0.1.4. Verify it with the same identity and issuer, using registry.permafrostepm.com/charts/permafrost@sha256:DIGEST as the target. Inspect the attached image SBOM with docker buildx imagetools inspect registry.permafrostepm.com/permafrost/app@sha256:DIGEST --format '{{json .SBOM}}'.

Download and configure Compose

From your signed-in account, download the Compose file and environment example. Save them as deploy/selfhost/docker-compose.yml and deploy/selfhost/.env.example under your working directory.

cp deploy/selfhost/.env.example deploy/selfhost/.env
openssl rand -hex 32

Run the random-value command separately for POSTGRES_PASSWORD, AUTH_SECRET and CRON_SECRET. Use distinct values. AUTH_SECRET and CRON_SECRET need at least 32 characters; POSTGRES_PASSWORD needs at least 16. Keep the environment file private. Set PERMAFROST_IMAGE=registry.permafrostepm.com/permafrost/app:0.1.4, or use the verified image digest.

Set AUTH_URL to your external HTTPS origin and PERMAFROST_LICENSE_KEY to your key. Set AZURE_AD_TENANT_ID, AZURE_AD_CLIENT_ID and AZURE_AD_CLIENT_SECRET from your own single-tenant Microsoft Entra app. Use the client secret value, not its ID. Certificate-only sign-in is not implemented. An independent PRINT_SIGNING_SECRET enables PDF exports.

Compose includes Postgres 16 and builds database URLs from its DB_* settings. For an external database, set both DATABASE_URL and DATABASE_URL_UNPOOLED in the same environment file. The bundled database still starts and POSTGRES_PASSWORD is still required. Set database TLS parameters in both URLs, such as sslmode=verify-full and sslrootcert, sslcert or sslkey when needed. Mount referenced certificate files into both app and migrate services. PGSSLMODE, PGSSLROOTCERT, PGSSLCERT, PGSSLKEY and PGSSLCRL are supported; non-empty certificate paths in the environment override URL paths, and the stricter TLS mode wins.

For another environment-file location, set SELFHOST_ENV_FILE to its absolute path and pass that same path to --env-file.

Prepare Microsoft sign-in and collection

In your app registration, add these Web redirect paths under AUTH_URL: /api/auth/callback/microsoft-entra-id, /api/onboarding/callback and /api/onboarding/attach/callback. Configure the logout origin too.

Configure Microsoft Graph delegated User.Read and the OpenID Connect openid, profile and email scopes for sign-in. Grant the collection permissions displayed during setup as application permissions for unattended Graph collection. ARM user_impersonation is delegated. A Global Administrator or Privileged Role Administrator must complete the connection proof.

In Enterprise applications, enable Assignment required and assign only people who may administer installation. Any assigned user with the setup code can attempt to claim the first administrator.

Start and check health

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 logs app
curl --fail http://localhost:3000/api/healthz

The migrate service must exit successfully before the app starts. A healthy response is {"ok":true,"db":"ok"}. Database failure returns HTTP 503 with {"ok":false,"db":"error"}. The default published address is 127.0.0.1:3000. Use a TLS reverse proxy for remote access and block /api/cron and /api/healthz there.

Find Permafrost setup code: in the app log. Keep the code private. It is single-use and expires after 60 minutes. Five attempts are allowed per rolling 15-minute window. Restart the app for a new code while no active administrator exists. Run one app instance; the code is held in that process.

Complete the five setup steps

Open AUTH_URL followed by /setup.

  1. 1. Licence. Wait for a valid licence or select Check again. Results are cached for up to one minute. Correct a missing key in the environment file and recreate the app.
  2. 2. Sign in with Microsoft. Use an account in the configured directory. Correct any settings named on the page before continuing.
  3. 3. Claim administrator access. Enter the setup code. Sign-in alone does not create administrator access.
  4. 4. Connect the tenant. Review permissions and complete Microsoft admin consent and the directory-role proof. This queues the first sync.
  5. 5. Monitor first sync. Keep the scheduler running. If the sync fails, inspect the status and retry with Sync now. Select Open dashboard when it completes.

After changing the environment file, run the Compose command with up -d to recreate containers with the new settings; docker compose restart does not re-read the environment file. See operations for upgrades and recovery.