Skip to content
Self-hosted

Self-hosted Kubernetes

Install the Permafrost Helm chart with cluster values, secrets, an external database and TLS ingress.

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.

One chart, one app replica

The chart has been exercised on k3s 1.31 with the restricted Pod Security Standard. Amazon EKS and Google GKE are planned, not yet tested. The same chart is intended for standard Kubernetes clusters with Linux nodes.

On AKS, Microsoft sign-in, first sync, ingress, an external Azure database and workload identity have not yet been tested.

The image is published for linux/amd64 and linux/arm64; we have not yet tested the ARM (arm64) image.

Keep replicaCount: 1. Setup codes are process-local. The chart enforces one app replica and uses Recreate so old and new app processes do not overlap. Upgrades have downtime. The scheduler runs separately.

Cluster value files
Target
Support
Values file
Configuration
Standard Kubernetes (k3s 1.31, restricted Pod Security Standard)Testedvalues.yamlYour ingress host and storage class
Azure AKSInstallation tested on AKS (Kubernetes 1.36, release 0.1.2, bundled database, restricted Pod Security).aks.yamlYour ingress host and storage class
Amazon EKSPlanned, not yet testedeks.yamlYour ingress host and storage class
Google GKEPlanned, not yet testedgke.yamlYour ingress host and storage class
Docker Desktop KubernetesShould workdocker-desktop.yamlYour local host and storage class

Prepare secrets and an external database

Follow the registration and Microsoft app setup steps. Create the namespace and secrets before installing. Keep credentials out of values files and command-line arguments. Save the licence key in a private file at /secure/permafrost-license-key without a trailing newline.

kubectl create namespace permafrost
kubectl label namespace permafrost pod-security.kubernetes.io/enforce=restricted
umask 077
printf '{"auths":{"registry.permafrostepm.com":{"auth":"%s"}}}' \
  "$(printf 'license:%s' "$(cat /secure/permafrost-license-key)" | base64 | tr -d '\n')" > /secure/permafrost-registry.json
kubectl -n permafrost create secret generic permafrost-registry \
  --type=kubernetes.io/dockerconfigjson --from-file=.dockerconfigjson=/secure/permafrost-registry.json
kubectl -n permafrost create secret generic permafrost-licence \
  --from-file=PERMAFROST_LICENSE_KEY=/secure/permafrost-license-key

Delete /secure/permafrost-registry.json after the Secret is created.

The Secret named by existingSecret needs AUTH_SECRET, CRON_SECRET, PRINT_SIGNING_SECRET, AZURE_AD_TENANT_ID, AZURE_AD_CLIENT_ID and AZURE_AD_CLIENT_SECRET. Use independent random AUTH_SECRET and CRON_SECRET values of at least 32 characters. The Secret named by license.existingSecret needs PERMAFROST_LICENSE_KEY. The image pull Secret named in imagePullSecrets uses registry.permafrostepm.com, username license and the licence key as password.

Use an external Postgres 16 database for production. Set postgres.enabled: false. The example below reads DATABASE_URL from a pre-created Secret through externalDatabase.urlKey. Include database TLS parameters in that URL. This is separate from HTTPS ingress. Configure databaseTLS.mode and databaseTLS.ca, databaseTLS.client or databaseTLS.crl to pass PGSSL* settings and mount database certificates in both the app and migration containers.

replicaCount: 1
image:
  repository: registry.permafrostepm.com/permafrost/app
  tag: "0.1.4"
imagePullSecrets:
  - name: permafrost-registry
existingSecret: permafrost-app
authUrl: https://permafrost.example.org
license:
  existingSecret: permafrost-licence
  secretKey: PERMAFROST_LICENSE_KEY
postgres:
  enabled: false
externalDatabase:
  existingSecret: permafrost-database
  urlKey: DATABASE_URL
ingress:
  enabled: true
  className: YOUR_INGRESS_CLASS
  blockInternalPaths: false
  hosts:
    - host: permafrost.example.org
      paths:
        - path: /
          pathType: Prefix
  tls:
    - hosts: [permafrost.example.org]
      secretName: permafrost-tls

Alternatively set externalDatabase.host, port, name and user, with passwordKey naming the password in its Secret. Bundled Postgres is enabled by default for evaluation and small installs. It uses DB_PASSWORD from existingSecret and has no TLS between app and database. Its storage class and size are configurable.

The chart passes PRINT_SIGNING_SECRET from existingSecret to the app. Set an independent random value of at least 32 characters to enable PDF exports.

Configure ingress before installing

Install controller-specific blocks for /api/cron and /api/healthz before using the example. Only then set ingress.blockInternalPaths: false to acknowledge those controls. The chart cannot create portable deny-path rules and otherwise refuses to render an enabled ingress.

Create the TLS Secret referenced by ingress.tls. Plain HTTP requires an explicit ingress.allowPlainHttp: true and is for local testing. Keep the Service at its default ClusterIP. NodePort and LoadBalancer need equivalent network controls and service.allowDirectExposure: true.

The database NetworkPolicy is enforced only when the cluster has a network policy engine. On AKS, create the cluster with a network policy option, such as Azure CNI powered by Cilium or --network-policy; other clusters need a network plugin configured to enforce Kubernetes NetworkPolicy.

If enabling networkPolicy.enabled, configure ingressFrom for your ingress controller and databasePeers for the external database. Allow outbound HTTPS to licensing and Microsoft APIs. See licensing for proxy and certificate settings.

Install and complete setup

Save your configuration as values.yaml.

helm registry login registry.permafrostepm.com --username license --password-stdin < /secure/permafrost-license-key
helm install permafrost oci://registry.permafrostepm.com/charts/permafrost --version 0.1.4 --namespace permafrost --values values.yaml --wait --timeout 15m
kubectl -n permafrost logs deployment/permafrost-permafrost -c app

The app pod waits for the database, then applies migrations in an init container before starting. Read the setup code from the app log, open your external origin at /setup and complete the five setup steps. Use the Deployment name printed by Helm if you changed fullnameOverride. The code expires after 60 minutes.

Upgrade

We support the two most recent versions and ship security fixes for both. Back up the database, verify the new image and chart, update image.tag or image.digest, and run helm upgrade with the same values and the new chart version. image.digest takes precedence over image.tag.

Migrations run on each app pod start under a database lock. A failed migration leaves the pod in init failure and makes the upgrade with --wait fail. Read its migrate-container logs. helm rollback does not undo database migrations. Automated GitOps installation has not been verified.

Secret changes do not change the pod template. Restart the app and scheduler Deployments after rotating secrets. Recreate keeps one app process during the restart.

Verify what you run

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}}'.