Deployment

Environment variables, Docker Compose, and Kubernetes health probe configuration for Permix.

Permix is a single Go binary with a PostgreSQL dependency. It ships as a Docker image and supports selfhost and saas operating modes.

Environment variables#

Variable	Default	Required	Description
`PORT`	`8080`	—	HTTP server port
`MODE`	`selfhost`	—	`selfhost` or `saas`
`POSTGRES_HOST`	`localhost`	✅	PostgreSQL host
`POSTGRES_PORT`	`5432`	—	PostgreSQL port
`POSTGRES_USER`	`postgres`	✅	PostgreSQL user
`POSTGRES_PASSWORD`	`postgres`	✅	PostgreSQL password
`POSTGRES_DB`	`postgres`	✅	Database name
`OIDC_ENABLED`	`true`	—	Enable JWT validation
`AUTH_SERVER_URL`	—	selfhost	OIDC issuer URL
`JWKS_URI`	—	selfhost	JWKS endpoint URL
`ROLES_CLAIM`	`realm_access.roles`	—	JWT claim for roles
`DOMAIN_CLAIM`	`dom`	—	JWT claim for domain/tenant
`ADMIN_DOMAIN_CLAIM`	`adm`	—	JWT claim for admin domain
`EXCLUDED_ROLES`	`offline_access,uma_authorization`	—	Comma-separated roles to ignore
`CASBIN_MODEL_PATH`	`configs/casbin/model.conf`	—	Path to Casbin model file
`ADMIN_API_KEY`	—	saas	Admin API key for `/admin/*` routes

Docker Compose (self-hosted)#

yaml

version: "3.9"
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: authz
      POSTGRES_PASSWORD: changeme
      POSTGRES_DB: authz
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U authz"]
      interval: 5s
      retries: 5

  authorization-service:
    image: ghcr.io/lhtuwrk/authorization-service:latest
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "8080:8080"
    environment:
      MODE: selfhost
      POSTGRES_HOST: postgres
      POSTGRES_USER: authz
      POSTGRES_PASSWORD: changeme
      POSTGRES_DB: authz
      OIDC_ENABLED: "true"
      AUTH_SERVER_URL: https://keycloak.example.com/realms/myrealm
      JWKS_URI: https://keycloak.example.com/realms/myrealm/protocol/openid-connect/certs

volumes:
  pgdata:

Docker Compose (SaaS mode)#

yaml

environment:
  MODE: saas
  POSTGRES_HOST: postgres
  POSTGRES_USER: authz
  POSTGRES_PASSWORD: changeme
  POSTGRES_DB: authz
  OIDC_ENABLED: "true"
  ADMIN_API_KEY: "your-secret-admin-key"

Kubernetes health probes#

The service exposes standard Kubernetes probes at /healthz/live (liveness) and /healthz/ready (readiness). Both endpoints require no authentication.

yaml

livenessProbe:
  httpGet:
    path: /healthz/live
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 10
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /healthz/ready
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 5
  failureThreshold: 3

The readiness probe checks both PostgreSQL connectivity (PingContext) and Casbin enforcer availability. It returns 503 with a checks payload if either dependency is unavailable:

json

{
  "status": "degraded",
  "checks": {
    "database": "unavailable",
    "casbin": "ok"
  }
}

ℹ

Startup order

Use initialDelaySeconds: 10 or a depends_on healthcheck to ensure PostgreSQL is ready before the service starts. The service runs all DB migrations on startup and will crash if the database is unreachable.

Database migrations#

Migrations run automatically at startup from internal/db/migrations/. The service uses a simple file-based migration runner — no external tool required. ABAC tables (abac_policy) and SaaS tables (tenants, tenant_identity_providers, service_api_keys) are all managed here.

Casbin model#

The default Casbin RBAC model is loaded from configs/casbin/model.conf. Mount a custom model via the CASBIN_MODEL_PATH env var if you need to adjust policy semantics (e.g. add domain hierarchy).