Minctrl Docs
Guides

Self-hosting — Kubernetes, Hetzner and the data region

Run Minctrl on your own infrastructure with the Helm chart or the Hetzner Terraform, keep its data in one region, and know exactly what is tested and what stays yours to do.

Minctrl ships two ways to run it yourself, both built from the same images and the same environment contract as the hosted production stack:

  • Kubernetes — the Helm chart in deploy/helm/minctrl (API, UI, migrations, optional bundled Postgres and Redis, Ingress or Cloudflare Tunnel, backups to S3 with a weekly restore test);
  • one Hetzner server — the Terraform in deploy/terraform/hetzner (server prepared by infra/prod/bootstrap-server.sh, SSH-only firewall, kept IP addresses, optional volume and backup bucket), then scripts/deploy-prod.sh as for production.

The honest limit. The chart is tested by helm lint, helm template with several value sets, kubeconform schema validation and rendered-manifest tests; the Terraform by terraform validate and terraform test against mocked providers. Neither has been applied to your cluster or your cloud account by us — doing that, and running what it creates, is the operator's.

Kubernetes with Helm

  1. Build and push the two images at the commit you deploy (deploy/helm/minctrl/README.md, "Images"). The chart never assumes :latest.
  2. Create the Secrets: the API env (JWT_SECRET, MINCTRL_SECRETS_KEY, email and model keys — the keys of infra/prod/minctrl.env.example), the database password, and — for backups — the bucket's S3 keys. The chart accepts no secret in values and renders no Secret.
  3. Install:
helm install minctrl deploy/helm/minctrl -n minctrl \
  --set dataRegion=eu-central --set appUrl=https://minctrl.example.com \
  --set existingSecret=minctrl-env --set postgres.existingSecret=minctrl-db \
  --set image.api.repository=registry.example.com/minctrl-api --set image.api.tag=$sha \
  --set image.ui.repository=registry.example.com/minctrl-ui --set image.ui.tag=$sha
  1. Prove it: the migrate Job's log ends ok migrations applied, and /health shows your commit, database: ok and your data region.

Upgrades run migrations first (a pre-upgrade hook with the new image; it fails unless every migration file applied, and a failed hook leaves the running release as it was). Rollback is helm rollback: images and manifests go back, the additive schema stays.

Several API replicas. Every background worker inside the API — SLA sweeper, notification dispatcher, SIEM sinks, timestamping, schedule triggers — is safe with any number of instances. The startup cleanup of orphaned workflows is not, so the chart refuses api.replicaCount > 1 or autoscaling unless api.multiInstance.enabled=true, which runs that cleanup under a Postgres advisory lock (MINCTRL_STARTUP_CLEANUP_LOCK=1).

One Hetzner server with Terraform

cd deploy/terraform/hetzner
cp terraform.tfvars.example terraform.tfvars    # data_region, server_type, ssh_key_names
export HCLOUD_TOKEN=…
terraform init && terraform plan -out minctrl.tfplan && terraform apply minctrl.tfplan

Then follow infra/prod/README.md from "Secrets". deploy/terraform/README.md lists what is not automated: the account and token, Object Storage keys (Hetzner issues them only in its Console), secrets on the server, DNS and the tunnel, every deploy, and region moves.

The data region

MINCTRL_DATA_REGION declares where an installation keeps its data:

idwhereserver locationdefault backup endpoint
eu-centralEU · Germany (Falkenstein)fsn1 (nbg1 allowed)https://fsn1.your-objectstorage.com
eu-northEU · Finland (Helsinki)hel1https://hel1.your-objectstorage.com
us-eastUS · Virginia (Ashburn)ashnone — name an in-region S3 endpoint

It is a deployment setting, read-only in the product:

  • /health reports data_region (id, label, jurisdiction) and the backup location the deployment declares — an explicit MINCTRL_BACKUP_S3_ENDPOINT, else the region's default, else source: "none"; never a guess.
  • Settings → Install shows Data region and Backup location; unset reads "not set".
  • Evidence packs record it: manifest.json → data_region, settings.json → deployment.
  • The Helm chart (dataRegion) and the Terraform (data_region) pick the backup endpoint and the server location from it, and refuse a location outside it or a bucket where the region has no object storage.
  • An unknown id stops the API at startup: a typo never reads as a region.

Keeping data in-region

The setting declares; it does not move data. To keep everything in the region you declared:

  • Database and Redis — on Kubernetes, pin postgres.nodeSelector (and the API's, UI's) to nodes labelled topology.kubernetes.io/region of that region, and use an in-region storageClass; with an external database, choose one in that region. On Hetzner, the server's location is the region (Terraform checks it).
  • Backups — the bucket in the same region: leave backup.s3.endpoint empty to take the region's default, or name an in-region endpoint. A bucket in another region is a transfer of personal data across regions; declare it with MINCTRL_BACKUP_S3_ENDPOINT so /health shows it.
  • Model providers and connectors are calls out of the region: the data region covers what Minctrl stores, not what a step sends to a provider you configured. Use DRY_RUN and shadowed connectors until each destination is approved.
  • Moving regions is a restore into a new installation in the new region, verified by its restore test, then a switch of DNS — never an in-place change of the setting.

On this page