traefik-agent¶

traefik-agent is a VM's own Traefik, the reverse proxy that sends each hostname to the right container, with the publisher that offers chosen routes to the rest of the fleet. It runs on every VM that serves a web interface, once the fleet has left bootstrap mode.

The Traefik on the VM terminates TLS and asks Authentik for a sign-in itself, so a request for one of the VM's services does not pass through the hub on tf01.

tf01 and bh01 do not list it. Their stacks, traefik-server and traefik-dmz, include it.

What it runs¶

traefik
error-pages
socket-proxy
logrotate
socket-proxy-rw
traefik-kop

The first five are traefik-basic, included whole. See traefik-basic for what each does and the ports Traefik publishes.

Service	Does
`traefik-kop`	Copies the routes of labelled containers into the Redis on tf01, where the hub's Traefik reads them

traefik-kop publishes a route only for a container that carries labels starting kop-public.traefik.. A container with the ordinary traefik. labels alone stays local to its VM, so reaching the hub is a choice made for each service.

Each published route points back at the service's own name on its VM, such as ntfy.ci01.home.myah-mitchell.com. The container sets that with its kop.bind.ip label. A container without the label is published at the VM's name, such as id01.home.myah-mitchell.com. traefik-kop reads the Docker socket directly, since it cannot use the socket proxy, and it looks for changes every ten seconds.

The Stack in Komodo carries the host's name, such as traefik-agent-id01. The containers are named after the project, traefik, as in every Traefik stack.

In bootstrap mode¶

The run leaves traefik-agent out on a host in bootstrap mode, because traefik-kop needs the Redis on tf01. traefik-bootstrap is deployed in its place. See traefik-bootstrap and Bootstrap mode.

The two never run on one VM together. Both bind ports 80, 443, and 8443. The swap from one to the other is part of Leaving bootstrap mode.

Values it reads¶

Key	Reads	Kind	Described under
`CF_API_EMAIL`	`CF_API_EMAIL`	Secret	Traefik
`CF_DNS_API_TOKEN`	`CF_DNS_API_TOKEN`	Secret	Traefik
`LE_EMAIL`	`LE_EMAIL`	Secret	Traefik
`CROWDSEC_LAPI_HOST`	`GLOBAL_CROWDSEC_LAPI_HOST`	Variable	Traefik
`AUTHENTIK_HOST`	`GLOBAL_AUTHENTIK_HOST`	Variable	Traefik
`REDIS_PASSWORD`	`TRAEFIK_KOP_REDIS_PASSWORD`	Secret	Traefik
`REDIS_SERVER`	`TRAEFIK_KOP_REDIS_SERVER`	Secret	Traefik

It also reads the 19 operational defaults, as every stack does.

All seven are created before the first host is built. See the Traefik values.

What	Depends on
The certificate	`CF_API_EMAIL`, `CF_DNS_API_TOKEN`, and `LE_EMAIL`. See Certificates from Let's Encrypt
The sign-in	`AUTHENTIK_HOST`, and Authentik running on id01
Published routes	`REDIS_SERVER` and `REDIS_PASSWORD`, and the Redis running on tf01

TRAEFIK_AUTH_CHAIN is blank in this stack's komodo.env, which takes chain-authentik@file.

What the host needs¶

The project is traefik, so the stack's folders sit under /opt/docker/volumes/traefik and /opt/docker/logs/traefik. Both are mode 0750, owned by the admin account with group 101000.

Folder	Owner	Mode
`/opt/docker/logs/traefik/traefik`	`101000:101000`	`0755`
`/opt/docker/volumes/traefik/traefik-certs`	`101000:101000`	Default
`/opt/docker/volumes/traefik/traefik-plugins`	`101000:101000`	Default

Port	Allowed from	Comment
`80/tcp`	Anywhere	Traefik HTTP
`443/tcp`	Anywhere	Traefik HTTPS
`8443/tcp`	Anywhere	Traefik HTTPS (alt)

The host's NixOS configuration creates the folders and opens the ports when the host is deployed. It reads them from the host's file in the private repo, nixos/hosts/<host>.json, which nixos-sync.yml writes from the stack's setup.yaml. See Host layout.

traefik-kop needs no folder and no port of its own. It connects outward to port 6379 on tf01.

Hostnames¶

The dashboard answers on port 8443, under the same two names as in every Traefik stack. See traefik-basic.

Verify¶

In Komodo, the traefik-agent-<host> Stack shows as running with six services.

On the host, list the Stack's containers. Komodo names the Compose project after the Stack, not after PROJECT_NAME:

docker compose -p traefik-agent-<host> ps

Every container shows healthy in the STATUS column.

Open the dashboard in a browser, with your host in place of id01:

https://traefik.id01.home.myah-mitchell.com:8443

The browser shows no certificate warning, and Authentik asks for a sign-in before the dashboard loads.

A warning means Traefik is still serving its self-signed certificate. Look for the resolver's error in Traefik's log:

docker logs traefik-traefik 2>&1 | grep -i acme

Data worth keeping¶

Folder under `/opt/docker/volumes/traefik`	Holds
`traefik-certs`	`acme.json`, with the Let's Encrypt account and every certificate issued to it

The published routes are not data to keep. traefik-kop builds them from the containers' labels.

Not yet confirmed¶

The stack has not been deployed on any host.
traefik-kop's health check asks the program for its version. A traefik-kop that cannot reach Redis still shows as healthy, so check its log when a published route is missing on tf01.