Authentik Proxy outpost
Find a file
2026-11-08 18:38:49 +00:00
docs Record verified sbx0monitoring00 migration and recovery 2026-11-08 19:37:46 +01:00
examples/sbx0postbote00 Configure Komodo proxy outpost on sbx0postbote00 2026-11-05 15:48:24 +01:00
secrets Enroll sbx0monitoring00 proxy outpost for Komodo migration 2026-11-08 19:19:25 +01:00
targets Enroll sbx0monitoring00 proxy outpost for Komodo migration 2026-11-08 19:19:25 +01:00
.age-docker.toml Enroll sbx0monitoring00 proxy outpost for Komodo migration 2026-11-08 19:19:25 +01:00
.age-docker.toml.example Configure Komodo proxy outpost on sbx0postbote00 2026-11-05 15:48:24 +01:00
.gitignore Configure Komodo proxy outpost on sbx0postbote00 2026-11-05 15:48:24 +01:00
AGENTS.md Document verified outpost deployment workflow 2026-11-05 17:27:12 +01:00
docker-compose.yml Configure Komodo proxy outpost on sbx0postbote00 2026-11-05 15:48:24 +01:00
GLOSSARY.md Configure Komodo proxy outpost on sbx0postbote00 2026-11-05 15:48:24 +01:00
komodo.toml Enroll sbx0monitoring00 proxy outpost for Komodo migration 2026-11-08 19:19:25 +01:00
komodo.toml.example Configure Komodo proxy outpost on sbx0postbote00 2026-11-05 15:48:24 +01:00
README.md Record verified sbx0monitoring00 migration and recovery 2026-11-08 19:37:46 +01:00
template.env Configure Komodo proxy outpost on sbx0postbote00 2026-11-05 15:48:24 +01:00

Local authentik proxy outposts

This repository defines a reusable Komodo-managed proxy outpost for each deployment target. Each local outpost has its own identity and token in its selected authentik instance. The instance URL and image version are configured per target; https://sso.s1q.dev is the example instance.

Target Stack declarations live in komodo.toml, with settings in targets/<target>.env and a separate encrypted token bundle for each target. The first enrolled target is sbx0postbote00. Its authentik identity is sbx0postbote00-proxy, assigned the existing Prowlarr, Sonarr, Radarr, Lidarr, Transmission, and NZBGet proxy providers. The configured image version is 2026.8.5, matching the instance at enrollment.

The shel1svc00 declaration replaces that host's NixOS-managed outpost, reusing its dedicated shel1svc00-proxy identity for status.s1q.dev, n8n.s1q.dev, and docs.nerd-kino.de. Its target-only Compose override maps sso.s1q.dev to the host gateway because the authentik instance runs on the same host. Keep this override scoped to this target and retain verified TLS. The confirmed migration design defines the port handoff, rollback, operator login checks, and NixOS retirement gates.

Additional targets use the .example files. The examples are not imported by the Resource Sync. Ingress remains host-owned: changing a Stack declaration does not by itself switch a reverse proxy or retire an old outpost.

The sbx0monitoring00 declaration replaces that host's NixOS-managed outpost for prometheus.int.r3w.de, reusing its dedicated sbx0monitoring00-proxy identity. Nginx keeps its existing loopback HTTP endpoint; Grafana retains its separate authentik OAuth flow. The confirmed migration design defines preparation, port handoff, operator acceptance, and NixOS retirement. The deployment record records the completed handoff, verification, and recovery materials.

Runtime and ownership

The host's reverse proxy calls the outpost at http://127.0.0.1:42080/outpost.goauthentik.io. Compose maps this loopback-only port to the container's HTTP listener on port 9000. It publishes no HTTPS port and requires no Dokploy network or Traefik labels. The host reverse proxy owns client-facing TLS and forward-auth routing.

The outpost connects to its authentik instance with TLS verification enabled by default. AUTHENTIK_HOST_BROWSER can specify a different public URL when AUTHENTIK_HOST is an internal address; empty or unset uses AUTHENTIK_HOST. The container must be able to resolve and reach the instance, including its websocket endpoint. In full proxy mode it must also reach the upstream applications; loopback addresses inside the container refer to the container.

NixOS owns the target host, Komodo Periphery, container permissions, reverse proxy, with-age-env, and Periphery's age-identity credential. This repository owns Compose, per-target settings, token bundles, and enrolled Stack declarations. The central docker-compose/komodo-bootstrap repository owns the child Resource Sync and ordered deployment Procedure.

Authentik owns outpost identities and application/provider assignments. Select manual deployment (no Docker or Kubernetes integration) for these outpost identities: Komodo owns the container lifecycle.

Layout

docker-compose.yml                        Shared outpost definition
template.env                              Non-secret configuration template
komodo.toml.example                       Reusable Stack template
.age-docker.toml.example                   Recipient policy template
examples/sbx0postbote00/
  target.env                              Example non-secret settings
  komodo.toml.example                     Example Stack
  bootstrap.toml.example                  Future central bootstrap handoff

Enrolled targets use these files:

komodo.toml                               Enrolled Stack declarations only
.age-docker.toml                           Explicit per-target recipients
targets/<target>.env                      Tracked non-secret settings/version
targets/shel1svc00.compose.yml            Host-specific SSO gateway mapping
secrets/<target>.env.age                   Tracked encrypted outpost token
.komodo/<target>.env                       Temporary plaintext; ignored

Deploy an outpost

This runbook follows the sbx0postbote00 deployment verified with Komodo 2.2.0 and authentik 2026.8.5. Read the running instance's version for each new target. A human can use the administration UIs; an agent or CLI operator can use the API reference for the same operations. Perform each step's completion check before continuing. For an interrupted enrollment, inspect the existing resources and resume at the first incomplete step.

1. Select the target and establish access

Run local commands from this repository. Set the exact Komodo Server name; NEW_HOST below is a placeholder, not an additional deployed system:

outpost_target=NEW_HOST

Collect these inputs before changing anything:

Input Source Destination
Server name and ID Existing Komodo Server Stack and bootstrap declarations
Verified SSH host public key Trusted Nix inventory or authenticated host access .age-docker.toml
Instance URL, public browser URL, current server/worker version Selected authentik instance targets/<target>.env
Intended applications and proxy provider IDs Applications hosted on this target and their authentik registrations Dedicated outpost identity

Use an authenticated Forgejo Git account for both repositories, fj for Forgejo operations, and age-docker with the maintainer's personal identity. Administrative access to Komodo must allow resource writes and execution; authentik access must allow outpost creation, provider lookup, and retrieval of the generated token. API operators also need the Komodo API key/secret. Agents obtain missing credentials through private secret input, such as T3's request_secret with file delivery, and keep temporary credentials outside Git.

Inventory this repository's push hooks before publishing. The shared Komodo Procedure already serves this repository. Reuse it for additional targets; retire legacy deployment hooks only when handing their automation to Komodo. Merges can deploy changed existing targets, so keep enrollment changes scoped to the new target's files and Stack entry.

Complete when: target, instance, application assignments, trusted host key, and authorized access are known. Deployment authorization is distinct from repository preparation; ingress cutover is also a separate operation.

2. Verify the host prerequisites

Provision Periphery through NixOS first. In Komodo, find the existing Server by name, enable it if needed for this deployment, and confirm it reports Ok. Record its ID; reuse this resource rather than creating another Server with the same name. Server API calls provide the equivalent checks.

Periphery needs container-engine access, Docker Compose with environment-sourced secrets, with-age-env, and the systemd age-identity credential. The credential must contain the private key matching the host recipient. On the deployed NixOS hosts its path is /run/credentials/komodo-periphery.service/age-identity; the host supplies AGE_IDENTITY_FILE when its tooling requires that selection.

If SSH is available, use the inventory's full hostname, for example ${outpost_target}.int.s1q.dev, to inspect Periphery, tools, and listeners. Confirm loopback port 42080 is available. If another outpost owns the port, plan its handoff before deployment. Check that containers can reach the selected authentik instance over verified HTTPS and websockets. SSH timeout alone does not establish that Periphery is offline: the previous deployment used the Komodo API after SSH timed out.

Complete when: the correct existing Server is online and enabled, its runtime and age credential are ready, and the required port and network path are available. Host provisioning belongs to NixOS, not this Compose repository.

3. Register the dedicated authentik outpost

In authentik's Admin interface, open Applications > Outposts > Create:

  • Name: <target>-proxy, for example sbx0postbote00-proxy.
  • Type: Proxy.
  • Integration: ---- (manual deployment); Komodo manages the container.
  • Applications: select only those intended for this deployment target.

If the identity already exists, verify its type, manual integration, and assignments before reusing it. Keep existing outposts and their assignments while their ingress still depends on them. The six acquisition applications on sbx0postbote00 are an example, not defaults for other hosts.

Obtain the generated AUTHENTIK_TOKEN through the outpost's deployment information. An API operator can create the identity and retrieve its token. The operator's administrative API token and this generated workload token are different credentials.

Complete when: one dedicated identity exists in the chosen instance, its assignments match the target, and its generated token is available privately.

4. Prepare per-target settings and encrypted secrets

mkdir -p targets secrets
if [ ! -e "targets/${outpost_target}.env" ]; then
  cp template.env "targets/${outpost_target}.env"
fi

Edit the copied settings. Set AUTHENTIK_TAG to the running instance's server and worker tag, AUTHENTIK_HOST to its reachable URL, and keep TLS verification enabled. Set AUTHENTIK_HOST_BROWSER only if users need a different public URL. Keep the token out of this file.

Extend the existing .age-docker.toml. Add the target's verified public key under [keys], and its exact bundle path under [secrets]. These are fragments to insert into the existing tables, replacing NEW_HOST and the key:

# Under the existing [keys] table:
NEW_HOST = "ssh-ed25519 REPLACE_WITH_VERIFIED_HOST_PUBLIC_KEY"

# Under the existing [secrets] table:
"secrets/NEW_HOST.env.age" = ["users", "NEW_HOST"]

Preserve other targets' rules. Each bundle is readable by the maintainer and only its assigned host. Then create the bundle:

age-docker edit "secrets/${outpost_target}.env.age"
age-docker check

The editor contents are one AUTHENTIK_TOKEN=<generated outpost token> assignment. For API-driven enrollment, capture the returned token directly into a mode-0600 temporary env file outside Git, use age-docker encrypt with the configured bundle path, and remove the plaintext in a cleanup handler. Encrypted age bundles are committed to this public repository; publish only the ciphertext and recipient policy. The wrapper contract explains how the host receives the token file without rendering its value.

Complete when: settings match the selected instance, the bundle exists, age-docker check passes, and its only recipients are the maintainer and target.

5. Add, validate, and publish the Stack declaration

Render the reusable Stack template:

sed "s/TARGET/${outpost_target}/g" komodo.toml.example

Append that rendered block to root komodo.toml exactly once. If the Stack already exists, edit its entry instead. Check that Server, project name, targets/<target>.env, secrets/<target>.env.age, and .komodo/<target>.env all refer to this target. Preserve deploy = false, disabled direct Stack webhooks and image auto-updates, and the wrapper's config/pull/up/run coverage. Ensure the selected deploy-komodo Git account can read this repository from both Core and the target Periphery.

AUTHENTIK_TOKEN=validation-only \
  docker compose --env-file "targets/${outpost_target}.env" config --quiet
age-docker check
git diff --check

Parse the changed TOML and inspect the diff. Commit only the intended Stack, settings, recipient policy, and encrypted bundle through the repository's reviewed branch/merge workflow. Merge the application changes to main before synchronizing resources; Core and Periphery read published Git, not this local working tree. An existing push hook may already sync the new Stack, but it will not deploy it until the Procedure includes it.

Complete when: validation passes and main contains the target's settings, Stack entry, recipient rule, and encrypted bundle. No plaintext, real token values, or temporary credential files are staged.

6. Prepare central bootstrap ownership and deployment ordering

In docker-compose/komodo-bootstrap, add the target to servers.toml if absent. Mirror the existing Server's enabled, address, and auto-prune settings, and add sync:bootstrap, role:application, and the appropriate environment tag. Merge these same tags with the live Server's existing tags in Komodo; the metadata API can do this. Without the matching sync:bootstrap tag, the root Sync can propose creating a same-name Server instead of adopting the existing enrolled identity.

For an additional target, extend the existing deployment stage in stacks/authentik-outpost-proxy.toml with one execution:

{ execution.type = "DeployStackIfChanged", execution.params.stack = "authentik-outpost-NEW_HOST", enabled = true },

Keep every existing execution. For a first installation of this shared flow, start from the bootstrap template and replace its example target. Its child Sync reads only root komodo.toml and matches sync:authentik-outpost-proxy; examples stay outside the sync. Merge the reviewed bootstrap changes, but apply them in the next step's order.

Complete when: bootstrap Git contains the target and intended Procedure execution, and the live Server retains its original ID and existing tags.

7. Sync prerequisites before the Procedure

Komodo 2.2.0 validates a Procedure's Stack references during synchronization. Use this order for both a first installation and additional targets:

  1. Review the root bootstrap pending diff. Scope its initial execution to the target Server and authentik-outpost-proxy child Sync; leave the Procedure for the final pass. The scoped API request supports this even when its declaration is already in Git.
  2. Run the child authentik-outpost-proxy Sync. Review its pending diff first: it should create or update the intended Stack with deploy = false. An existing automatic push may have completed this step already.
  3. Confirm the Stack exists and references the recorded Server ID.
  4. Review the remaining root diff and apply the authentik-outpost-proxy-deploy Procedure update.

For each execution, wait for its Update to report Complete and success = true. An HTTP 200 or InProgress response is not completion. These syncs create definitions without deploying the new outpost. Changes outside the intended resources, especially deletions, need separate review. The Server diff must update the existing resource rather than create a duplicate.

Complete when: both syncs have no errors or unintended pending changes, and the Procedure has two ordered stages: RunSync, then the deployment stage containing DeployStackIfChanged for each enrolled target.

8. Deploy through the shared Procedure

Run authentik-outpost-proxy-deploy in Komodo, or use RunProcedure. It syncs application resources, then deploys changed enrolled Stacks. Other changed enrolled targets can also deploy during this run; inspect pending changes first. Use the Procedure for retries so resource synchronization stays ahead of deployment.

Complete when: the Procedure and its deployment execution finish successfully, and the Stack records a deployed Git revision with no missing files.

9. Verify the local outpost

Use Komodo's service list, container inspection, and logs together with authentik's outpost status, or the verification API calls. Check all of the following:

  • The expected image/tag is running on the intended Server without restarts.
  • The only published port is HTTP 127.0.0.1:42080 to container port 9000.
  • AUTHENTIK_TOKEN is file:///run/secrets/authentik_token in the container environment, and the secret file is present and nonempty.
  • Authentik reports a recent heartbeat, the expected outpost identity, and a matching version. Logs show the websocket connection and intended applications loading without authentication or configuration-refresh errors.
  • Wrapped commands have removed .komodo/<target>.env; retain the wrapper-owned lock path. Both resource syncs converge without errors or unexpected changes.

A container may have no Docker Health object; process state alone is not an authentik connectivity check. Keep secret values out of diagnostic output.

Complete when: runtime, binding, secret handling, current instance connection, and assigned applications are verified. A redirect through the old ingress route does not establish that the new local outpost is serving that route.

10. Verify automation and record the handoff

Additional targets share the existing repository push hook and Procedure; check them rather than adding one hook per host. For a first installation, create a Gitea webhook in Forgejo repository Settings > Webhooks with:

Setting Value
URL Procedure's https://<komodo-host>/listener/github/procedure/<procedure-id>/__ANY__ URL
Content type application/json
Secret Existing KOMODO_WEBHOOK_SECRET used by Core
Event Push

The Gitea hook type uses Komodo's github signature validation. Obtain the signing secret privately; it is distinct from the API key/secret and the outpost token, and Core's API does not expose it. Store it in webhook settings, not Git. Keep direct Sync/Stack hooks disabled. On an automation migration, disable obsolete deployment hooks while retaining their configuration for recovery.

Send a test delivery and confirm a new, successful Procedure Update appears; saving a hook or queuing a test is not end-to-end verification. The webhook API reference covers API setup and verification. No tracked-file changes should mean no unnecessary redeployment. Record the target, outpost identity, image version, source revisions, successful Update IDs, verification results, and ingress status in the deployment record. Remove temporary credential and plaintext files when finished.

If ingress cutover is also authorized, change the host's NixOS reverse proxy to http://127.0.0.1:42080/outpost.goauthentik.io, using the provider's generated forward-auth and callback configuration. Test a protected application's unauthenticated request, login, callback, and logout before retiring its old route. Preserve the old outpost while any other host still depends on it.

Complete when: the new outpost is deployed and verified, the signed push hook runs the ordered Procedure successfully, and the handoff explicitly states whether ingress was switched or remains on the previous outpost.

Troubleshooting an interrupted enrollment

Symptom Action
Short-name DNS failure or SSH timeout Use the trusted full inventory hostname; check Server Ok and use authenticated Komodo APIs if SSH remains unavailable.
Git push fails with Permission denied (publickey) Use the configured authenticated HTTPS Git path or repair SSH access; keep tokens in a credential manager or private helper.
Root proposes Create Server for an enrolled host Add the bootstrap match tag to the existing Server, preserve its ID/tags, and refresh the pending diff.
procedure sync loop exited after max iterations Create the child Sync and Stack first, then retry the Procedure registration. A failed root run may already have created some prerequisites.
Missing files or repository clone failure Confirm application files are merged, the branch/path names agree, and deploy-komodo can read the repo.
Decryption fails Check the exact bundle path, per-target recipient, matching host identity credential, and wrapper selection; never print decrypted contents.
Authentik API returns Token invalid/expired Renew the operator's temporary administrative credential. Check the deployed outpost separately; its generated workload token is independent.
Hook saves but no Procedure runs Check delivery response/signature, Gitea-to-github URL, signing secret, push event, and Procedure ID; inspect new Updates.

Secrets and the Compose wrapper

Each Stack tracks targets/<target>.env and secrets/<target>.env.age so that configuration changes and token rotations trigger DeployStackIfChanged. Shared Compose changes affect all enrolled targets; per-target settings and bundle changes affect their respective Stacks. Enroll only one local outpost per host for this fixed loopback port.

Komodo wraps config, pull, up, and run with:

with-age-env secrets/<target>.env.age .komodo/<target>.env -- [[COMPOSE_COMMAND]]

with-age-env locks the bundle, decrypts using Periphery's host credential, creates plaintext with mode 0600, and removes it when the command exits or receives a handled signal. It does not export the file's values. Komodo must therefore list that path in additional_env_files with track = false so Compose can load the token. The plaintext file, its lock, and temporary files are wrapper-owned and ignored by Git. As in the sibling setup, abrupt process termination can leave plaintext until the next wrapped command cleans it up.

Compose supplies AUTHENTIK_TOKEN as the source of the authentik_token secret. The container receives the file at /run/secrets/authentik_token and sets AUTHENTIK_TOKEN=file:///run/secrets/authentik_token. The rendered service environment contains only this URI. Do not add the decrypted file as a service env_file; that would put its token into the container environment.

Compose injects an environment-sourced secret into the container as a file; it need not appear in Docker's Mounts metadata. Verify the actual file with an authorized container exec, for example test -s /run/secrets/authentik_token, without printing its contents. See the Compose file-injection implementation.

To rotate a token later, update its target's bundle with age-docker edit and merge it through the normal deployment flow. When recipients change, run age-docker rekey secrets/<target>.env.age and age-docker check. Test that the target can decrypt its bundle before revoking the old token or host key.

Local validation without deployment

Use dummy input to validate either configuration template without decrypting secrets or contacting a container runtime:

AUTHENTIK_TOKEN=validation-only \
  docker compose --env-file template.env config --quiet

AUTHENTIK_TOKEN=validation-only \
  docker compose --env-file examples/sbx0postbote00/target.env config --quiet

For an enrolled target, substitute targets/<target>.env. Run age-docker check once a real recipient policy and encrypted bundles exist; the example policy intentionally contains a host-key placeholder. The checked-in policy and encrypted bundle for sbx0postbote00 can be checked with age-docker check.

Upgrade and rollback

Keep each target's AUTHENTIK_TAG aligned with its chosen authentik instance. Review that version's release notes and coordinate the instance and outpost upgrades before changing the tracked per-target version. After enrollment, merges use the ordered Procedure; do not run compose up manually on hosts. Check the Procedure logs and an assigned application's login after rollout.

For a configuration regression, revert the affected target settings or shared Compose change through a reviewed merge. An encrypted token revert works only if the old token is still valid. Match the outpost version to its instance; this repository does not roll back the authentik instance or its database.

Deployment record

On 2026-11-05, authentik-outpost-proxy-deploy successfully deployed authentik-outpost-sbx0postbote00 from application revision 176179d after bootstrap revision 747a68a registered its resources. The host's existing Periphery identity was adopted into bootstrap ownership without changing its enabled, address, or auto-prune settings.

Komodo reported the proxy container running with only HTTP port 127.0.0.1:42080 published. Its environment contains the token file URI, and authentik reported a current heartbeat with matching version 2026.8.5. Both resource syncs converged with no pending configuration changes or errors. The host's nginx route remains on its existing source outpost; a login through that route does not verify this newly deployed local outpost. All six existing application entry points still returned HTTP 302 after the deployment. The repository's legacy Dokploy push hook was disabled so it cannot redeploy the source platform when this repository changes. The signed Forgejo hook was configured and tested through the shared Procedure. The successful deployment Update was 6aec99a83a8b3e36203e2bc3; the successful webhook-triggered Update was 6aec9c043a8b3e36203e2c8e.

On 2026-11-06, shel1svc00 moved from its NixOS-managed outpost to authentik-outpost-shel1svc00, deployed from application revision 2009bee with matching version 2026.8.5. The dedicated identity, token, Traefik routes, and public exceptions were preserved. Automated readiness passed in 27.11 seconds, followed by operator-confirmed login, callback, access, and logout for all three applications. The NixOS outpost definition was then retired and the retirement system activated. Signed webhook execution and unchanged-target behavior were verified; the previous active generation and recovery materials remain pinned. See the full deployment record.

References and decisions