# Authentik deployment This repository owns the production deployment of [Authentik](https://goauthentik.io/) for `sso.s1q.dev`, including its Compose configuration, encrypted secrets, and Komodo Stack declaration. ## Deployment architecture The `authentik-prod` Stack follows the protected `main` branch. Its direct webhook is disabled. A Forgejo webhook calls the central `authentik-deploy` Procedure, which first runs the child Resource Sync and then runs `DeployStackIfChanged`. The central `docker-compose/komodo-bootstrap` repository owns that child Sync and Procedure. Komodo passes `docker-compose.yml` first and `docker-compose.override.yml` second. The upstream-derived base and deployment-specific override remain separate by design. A regular deployment therefore follows this path: 1. merge a reviewed change into `main`; 2. Forgejo calls the `authentik-deploy` Procedure webhook; 3. the Procedure syncs `komodo.toml`; and 4. Komodo deploys `authentik-prod` if a tracked file changed. For a first deployment or a manual retry, run `authentik-deploy` in Komodo instead of deploying the Stack directly. This keeps resource synchronization and deployment in the intended order. ## Prerequisites Before the first deployment, ensure that: - NixOS has provisioned the `sbx0docker01` Komodo Server, Periphery's container permissions, the `with-age-env` wrapper, and its `age-identity` credential; - the external `dokploy-network` exists on the deployment host; - the root `bootstrap` Resource Sync has registered the `authentik` child Sync and the `authentik-deploy` Procedure; and - the Forgejo repository webhook uses the Procedure's `__ANY__` webhook URL. Host provisioning, Tailscale, CrowdSec, and registry setup belong to NixOS or their respective infrastructure repositories and are intentionally not duplicated here. ## Layout and ownership ```text . ├── .age-docker.toml # Secret recipients and policy ├── docker-compose.yml # Upstream-derived Compose base ├── docker-compose.override.yml # Production networks, routing, and images ├── env/ │ └── common.env # Tracked non-secret configuration and versions ├── komodo.toml # authentik-prod Stack declaration ├── secrets/ │ └── prod.env.age # Encrypted production secrets └── data/authentik/custom-templates/ ``` NixOS owns Komodo, Periphery, host credentials, Podman permissions, and the external `dokploy-network`. This repository owns the application definition. Persistent database, Redis, media, certificate, and GeoIP data live in named container volumes on the deployment host and are not stored in Git. `env/common.env` is the authoritative source for tracked runtime settings and explicit image versions. The old local `.env`/template and init-script workflow is no longer part of deployment. ## Secrets The encrypted production bundle contains: ```text PG_PASS AUTHENTIK_SECRET_KEY AUTHENTIK_EMAIL__PASSWORD GEOIPUPDATE_LICENSE_KEY ``` Local secret management uses only `age-docker`. Recipient keys, groups, and the rule for the encrypted bundle live in `.age-docker.toml`. The bundle is currently encrypted for the personal `phg` age key and the `sbx0docker01` SSH host key. Edit the bundle with: ```bash age-docker edit secrets/prod.env.age ``` When a configured recipient changes, re-encrypt the bundle and validate the complete policy: ```bash age-docker rekey secrets/prod.env.age age-docker check ``` `age-docker` creates mode-`0600` temporary plaintext, removes it after the editor exits or a handled signal occurs, produces armored ciphertext, and verifies the new ciphertext with the personal identity before atomically replacing the tracked file. It does not add implicit recipients: every key with access is declared in `.age-docker.toml`. Never add a plaintext secret file to Git. The Stack tracks the encrypted bundle so that secret rotation counts as a deployment change, but it does not track the temporary `.komodo/prod.env` file. The decrypted values are Compose secret sources rather than service environment values. Containers receive only their declared files under `/run/secrets`; Authentik reads them through `file://` configuration values, while PostgreSQL and GeoIP Update use their `_FILE` variables. Consequently, `docker compose config` renders secret source names and file paths without persisting the values in Komodo's merged configuration. ## Komodo Compose wrapper Komodo wraps `config`, `pull`, `up`, and `run` with the NixOS-provided `with-age-env` command. The wrapper: - obtains an exclusive per-bundle lock; - removes stale plaintext and temporary files; - decrypts through the NixOS-provided systemd `age-identity` credential; - creates plaintext with mode `0600`; and - removes plaintext on success, failure, or a handled signal. The plaintext target and matching `.lock` and `.tmp.*` paths are exclusively owned by the wrapper. A `SIGKILL` or power loss can leave plaintext behind; the next invocation removes it before decrypting again. Workload containers do not receive the age identity, but commands launched by Periphery can access it. Revisit that trust boundary if deployment authority is ever granted to another operator. ## Upgrade There is currently no long-lived test environment. Prepare and review every upgrade on a branch before merging it into production. If a test Stack is added later, perform the upgrade there first. 1. Confirm that the host backups are current and restorable. 2. Read the target version's [Authentik release notes](https://docs.goauthentik.io/releases/) and upgrading section. Note all manual migrations, breaking configuration changes, and outpost compatibility requirements before changing files. 3. Create an upgrade branch. 4. Download the target version's upstream Compose file alongside the tracked file. Replace the example version with the intended target: ```bash authentik_version="2025.8" curl -fsSL \ "https://goauthentik.io/version/${authentik_version}/lifecycle/container/compose.yml" \ -o docker-compose.yml ``` 5. Compare `docker-compose.yml` with the previously tracked version. 6. Review `docker-compose.override.yml` against the new base structure. Keep the production networks, Traefik routing, volumes, and explicit image declarations working with the new release. 7. Update `AUTHENTIK_TAG` in `env/common.env`. Review the supported PostgreSQL and Redis versions and update `POSTGRES_TAG`, `REDIS_TAG`, and `GEOIPUPDATE_TAG` only after checking their respective release and migration notes. Plan to update all Authentik outposts to the same Authentik version. 8. Remove the downloaded comparison file and validate the resulting policy and Compose model. Dummy values satisfy Compose's secret-source checks without decrypting production secrets: ```bash rm docker-compose.upstream.yml age-docker check PG_PASS=dummy \ AUTHENTIK_SECRET_KEY=dummy \ AUTHENTIK_EMAIL__PASSWORD=dummy \ GEOIPUPDATE_LICENSE_KEY=dummy \ docker compose \ --env-file env/common.env \ --file docker-compose.yml \ --file docker-compose.override.yml \ config --quiet ``` 9. Review the complete diff, commit it, push the branch, and merge it through a merge request. Do not run `docker compose pull`, `down`, or `up` manually on the host; the merge triggers the ordered Komodo deployment flow. 10. Follow the `authentik-deploy` Procedure and `authentik-prod` Stack logs in Komodo. Verify that all services become healthy, `https://sso.s1q.dev` is reachable, and an SSO login succeeds. Update outposts to the matching version and verify their connectivity. Record any repository-specific manual migration steps in this README before the rollout. None are currently documented. ### Rollback For a configuration or image regression, revert the merge on `main`; the webhook will run the same ordered deployment flow with the previous tracked configuration. Do not assume that an application or database migration can be downgraded. Follow the target release's rollback guidance and restore a tested backup when a migration is not reversible. ## Backup and disaster recovery This Compose project does not define a backup or `restore-cli` service. The old container-based restore commands therefore no longer apply. Backups and volume recovery must be provided and documented by the host infrastructure. Before relying on the deployment in production, ensure that the PostgreSQL data and all named volumes required by Authentik are covered by a tested backup and recovery runbook. Keep the runbook with the infrastructure that owns those backups and link it here once it exists. ## Optional test environment Do not create a test Stack or dummy bundle until there is a real long-lived `test` branch. When it is needed: 1. add `secrets/test.env.age`, encrypted to the test host and personal keys; 2. keep both Stack declarations in `komodo.toml` on `main`; 3. point `authentik-test` at branch `test` and its own encrypted/decrypted paths; and 4. add `authentik-test` to the Procedure's deployment stage in the central bootstrap repository. The repository webhook should use the Procedure's `__ANY__` endpoint so pushes to either protected environment branch enter the same ordered flow.