Authdog runs as a managed service on the edge by default. For regulated workloads, air-gapped environments, or data-residency requirements, Enterprise customers can run Authdog on-premises inside their own Kubernetes cluster via the official **Authdog Helm chart**. The chart packages the same control plane, identity endpoints, console, and worker runtime that power the hosted platform, so feature parity is preserved between cloud and self-hosted.

> Self-hosting is available on the Enterprise plan. Contact your CSM or [support](/docs/console/support) to get access to the chart repository and an image pull secret.

## What the chart installs

The Helm chart deploys the Authdog platform as a small set of services on your cluster:

- **API** — the control plane and public identity endpoints (sign-in, sign-up, sessions, SSO, webhooks, actions).
- **Console** — the admin console UI and account portal, served from your cluster.
- **Worker runtime** — the edge-style runtime that executes auth flows, actions, and session validation close to traffic.
- **Data services** — a relational store for tenants, projects, environments, and users, plus object storage for branding assets and a secrets backend for the [Vault](/docs/vault).
- **Migrations job** — a pre-install/pre-upgrade hook that applies D1-style schema migrations to the data store.

Each component is a separately scalable Deployment, fronted by a single Ingress, so you can tune resources and replicas per workload.

## Prerequisites

Before you install, make sure your cluster meets the chart requirements:

- Kubernetes **1.27** or newer.
- Helm **3.12** or newer.
- A supported container registry reachable from the cluster with the image pull secret Authdog provides.
- A PostgreSQL **15+** cluster (managed or in-cluster) for the relational store. The chart does not bundle PostgreSQL by default; bring your own for production.
- An S3-compatible object store (S3, R2, MinIO, GCS via S3 API) for branding assets and large payloads.
- An Ingress controller (nginx, Traefik, or a service mesh like Istio) with TLS termination.
- A DNS record pointing at the Ingress hostname you want Authdog to answer on.

For evaluation only, the chart can spin up in-cluster PostgreSQL and MinIO with `--set postgresql.enabled=true,minio.enabled=true`. Do not use these bundled stores in production.

## Add the chart repository

```bash
helm repo add authdog https://charts.authdog.com
helm repo update
```

Pull the chart and inspect its values before deploying:

```bash
helm pull authdog/authdog --untar --version <chart-version>
```

Your CSM will confirm the `<chart-version>` and provide the image pull secret. Create the secret in the target namespace before installing:

```bash
kubectl create namespace authdog
kubectl -n authdog create secret docker-registry authdog-pull-secret \
  --docker-server=registry.authdog.com \
  --docker-username=<provided-username> \
  --docker-password=<provided-token> \
  --docker-email=<you@company.com>
```

## Configure values

Copy `values.yaml` from the chart and edit it for your environment. The minimum you must set:

```yaml
image:
  pullSecrets:
    - name: authdog-pull-secret

ingress:
  enabled: true
  className: nginx
  hostname: authdog.example.com
  tls:
    - secretName: authdog-tls
      hosts:
        - authdog.example.com

api:
  replicaCount: 2
  resources:
    requests: { cpu: 250m, memory: 512Mi }
    limits:   { cpu: 1,    memory: 1Gi }

console:
  replicaCount: 2

data:
  postgres:
    # Point at your managed Postgres for production.
    host: pg.example.internal
    port: 5432
    database: authdog
    existingSecret: authdog-pg
    secretKey: password

  objectStore:
    type: s3
    endpoint: https://s3.example.com
    bucket: authdog-assets
    region: us-east-1
    existingSecret: authdog-s3
    accessKeySecretKey: accessKeyId
    secretKeySecretKey: secretAccessKey

vault:
  kms:
    # Per-environment KMS keys are required, same as on the hosted platform.
    # Bring your own key material or let the chart generate it on first install.
    existingSecret: authdog-kms
```

Secrets (Postgres password, S3 credentials, KMS key material) are referenced by `existingSecret` and never written into `values.yaml`. See [Vault](/docs/vault) for how KMS keys are used per environment.

## Install

```bash
helm install authdog authdog/authdog \
  --namespace authdog \
  --create-namespace \
  --version <chart-version> \
  --values values.yaml
```

The migrations job runs before the API and console come up. Watch rollout:

```bash
kubectl -n authdog rollout status deploy/authdog-api
kubectl -n authdog rollout status deploy/authdog-console
```

When both are ready, open `https://authdog.example.com` and complete first-run setup: create the first tenant, project, and environment. From that point, the on-prem console behaves identically to the hosted console. See [Console overview](/docs/console/overview).

## Environments and keys on-prem

The on-prem install preserves the [multi-tenancy](/docs/concepts/multi-tenancy) model: tenants contain projects, projects contain dev/staging/production environments, and each environment has its own signing keys, public key, connections, and user store. Promoting configuration between environments works the same way as on the hosted platform. See [Deployments](/docs/deployments).

The environment public keys (`pk_...`) your applications validate sessions against are issued by your on-prem install, not by `authdog.com`. Point your SDKs and backend validators at your on-prem hostname.

## Custom domains and ingress

On-prem, "custom domains" means additional Ingress hosts or routes you configure for the same install. Each environment can answer on its own hostname (for example `auth.tenant.example.com`) by adding an Ingress rule and pointing the relevant DNS record at the cluster. The chart supports multiple Ingress hosts; see `ingress.hosts` in the chart README. See [Custom domains](/docs/custom-domains) for the conceptual model.

## Upgrading

Run `helm upgrade` with the new chart version. The migrations job re-runs as a pre-upgrade hook and is idempotent. Treat schema migrations as forward-only; the chart does not support automatic rollback of the data store.

```bash
helm repo update
helm upgrade authdog authdog/authdog \
  --namespace authdog \
  --version <new-chart-version> \
  --values values.yaml
```

Always back up the Postgres database before upgrading. For a managed Postgres, use your provider's snapshot mechanism.

## Backups and disaster recovery

- **Postgres**: take regular snapshots and ship WAL to your standby region. The chart does not manage backups for you.
- **Object store**: enable bucket versioning on the assets bucket.
- **KMS keys**: back up the encrypted key material secret. If `environment_kms_keys` or `encrypted_key_material` is missing after a restore, environments cannot decrypt their vault entries — recover with the `0084_ensure_environment_kms_keys` migration, same as the hosted platform.

## Air-gapped clusters

For clusters with no outbound internet access:

1. Pull the chart and all images from `registry.authdog.com` on a connected workstation.
2. Push them into your internal registry.
3. Set `image.registry` in `values.yaml` to your internal registry and `image.pullSecrets` to the corresponding pull secret.
4. Run `helm install` from the local chart tarball (`helm install authdog ./authdog-<version>.tgz`).

The install does not phone home. Telemetry is opt-in and disabled by default.

## What is different from the hosted platform

- **Edge runtime location**: validation runs in your cluster, not on the global Cloudflare edge. Latency depends on where you place the cluster and your users.
- **No Cloudflare-native bindings**: KV, D1, R2, and Workers AI bindings used by some hosted features are replaced by in-cluster equivalents (Postgres, S3, optional local inference). Feature parity is tracked per release; check the chart changelog for any feature flagged as "hosted-only".
- **Updates**: you control the upgrade cadence. Security patches ship in chart releases; apply them on your schedule.
- **Support**: Enterprise on-prem includes a dedicated CSM and the same SLA commitments as Enterprise cloud. See [Support Center](/docs/console/support).

## Limits and current scope

- The Helm chart is GA for the core identity, console, sessions, SSO, provisioning, vault, and audit workloads.
- Lidar threat detection runs on the same event stream on-prem, but the managed detector feed updates ship with chart releases rather than continuously.
- Cloudflare-specific add-ons (Turnstile, Workers AI) are not available on-prem; configure an equivalent reCAPTCHA challenge under [Bot protection](/docs/bot-protection).

For the full list of supported values and advanced configuration (HPA, PodDisruptionBudgets, service mesh, external secrets, OpenTelemetry export), see the chart README shipped with `helm pull`.