| docs | ||
| examples/sbx0postbote00 | ||
| secrets | ||
| targets | ||
| .age-docker.toml | ||
| .age-docker.toml.example | ||
| .gitignore | ||
| AGENTS.md | ||
| docker-compose.yml | ||
| GLOSSARY.md | ||
| komodo.toml | ||
| komodo.toml.example | ||
| README.md | ||
| template.env | ||
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 examplesbx0postbote00-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:
- Review the root
bootstrappending diff. Scope its initial execution to the target Server andauthentik-outpost-proxychild Sync; leave the Procedure for the final pass. The scoped API request supports this even when its declaration is already in Git. - Run the child
authentik-outpost-proxySync. Review its pending diff first: it should create or update the intended Stack withdeploy = false. An existing automatic push may have completed this step already. - Confirm the Stack exists and references the recorded Server ID.
- Review the remaining root diff and apply the
authentik-outpost-proxy-deployProcedure 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:42080to container port9000. AUTHENTIK_TOKENisfile:///run/secrets/authentik_tokenin 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.