Traefik

Purpose

Traefik is the central HTTPS reverse proxy for the Bytek homelab.

Traefik receives HTTPS requests, selects the correct application according to the requested hostname, and forwards the request to the appropriate private backend.

Traefik provides:

Service Information

Dashboard:

Open the Traefik Dashboard

Architecture Role

Traefik is the common application-routing layer for both external and internal clients.

External Request Path

Internal Request Path

The same application hostname is used internally and externally.

Application Routing Reference

The BookStack private address must be confirmed and added to this page.

Configuration Locations

The exact certificate and log paths should be confirmed against the current Compose file before relying on them during recovery.

Dynamic Configuration

Each application normally has its own dynamic configuration file.

Known files include:

Separating services into individual files makes configuration changes easier to review and reverse.

Before editing a working file:

Static Configuration

The static Traefik configuration defines platform-level settings such as:

Static configuration changes normally require a Traefik container restart or recreation.

Dynamic routing changes are usually detected automatically by the file provider when file watching is enabled.

Docker DNS

The Traefik container explicitly uses Pi-hole at 192.168.2.65.

This configuration was added after Docker’s embedded resolver failed to resolve the Let’s Encrypt ACME API following a power interruption.

The observed error reported that the Docker resolver at 127.0.0.11 was misbehaving.

Explicit Pi-hole DNS allows Traefik to resolve:

Verify the configured Docker DNS using:

sudo docker inspect --format='DNS={{json .HostConfig.Dns}}' traefik

Expected result:

The container’s internal resolver file may still show Docker’s embedded resolver at 127.0.0.11.

That is normal when Docker forwards requests to the explicitly configured upstream DNS server.

Container Management

Move to the deployment directory before running Compose commands:

cd /opt/traefik

Check the stack:

sudo docker compose ps

View recent logs:

sudo docker compose logs --tail 100 traefik

Follow logs live:

sudo docker compose logs -f traefik

Validate the Compose file:

sudo docker compose config --quiet

Apply normal Compose changes:

sudo docker compose up -d

Recreate Traefik after changing container-level settings such as DNS:

sudo docker compose up -d --force-recreate traefik

Restart Traefik after a static configuration change:

sudo docker compose restart traefik

A normal restart does not apply changes to Docker-level settings such as container DNS, network mode, volume mounts, or environment variables. Those changes require container recreation.

Naming and Routing Standard

Every Traefik application should have:

A route should not contain Authentik ForwardAuth if the application already uses native OIDC and requires direct API or client access.

Applications That Must Not Use ForwardAuth

Do not attach Authentik ForwardAuth to:

Nextcloud

Nextcloud mobile clients, desktop clients, WebDAV, CalDAV, CardDAV, and application authentication must reach Nextcloud directly.

Nextcloud uses native OIDC.

Vikunja

Vikunja uses native Authentik OIDC.

BookStack

BookStack uses native Authentik OIDC.

Authentik

Authentik must never depend on its own ForwardAuth middleware.

Proxmox VE

Proxmox uses native OIDC and remains outside Traefik.

Plex

Plex clients use Plex authentication and Plex-specific APIs.

Applications That Use Authentik Proxy Integration

Traefik Dashboard

The Traefik dashboard uses single-application ForwardAuth.

The dashboard request is validated by the Authentik embedded outpost before access is granted.

Uptime Kuma

Uptime Kuma uses an Authentik Proxy Provider because Uptime Kuma does not provide the same native OIDC integration as the other applications.

Selected status-page and monitoring endpoints may bypass authentication when public access is intentionally required.

Traefik Dashboard Authentication

The dashboard is available at:

Open the Traefik Dashboard

Access is restricted by:

During the initial ForwardAuth validation, Traefik Basic Auth remains enabled as a second authentication layer.

The expected initial flow is:

Basic Auth may be removed only after ForwardAuth and recovery procedures are fully tested.

Authentik ForwardAuth Middleware

The ForwardAuth middleware sends authentication requests to the Authentik embedded outpost.

The outpost backend is hosted by Authentik at 192.168.2.162 on TCP port 9000.

The middleware should trust the forwarded request headers and return Authentik identity headers to the protected application.

Typical identity headers include:

Do not log full authentication headers in a location accessible to untrusted users.

Authentik Outpost Callback Route

The path under /outpost.goauthentik.io/ must remain reachable without the ForwardAuth middleware.

If the callback path is protected by the same middleware, an authentication loop can occur.

The callback router should:

Test the outpost with:

curl -k -I https://proxy.bytek.ca/outpost.goauthentik.io/ping

Expected result:

A normal browser link is not useful for this endpoint because an HTTP 204 response intentionally contains no page content.

Certificate Management

Traefik obtains HTTPS certificates from Let’s Encrypt.

The current design uses:

Each public router should reference the correct certificate resolver.

A router without the certificate resolver may use the Traefik default certificate instead of requesting the intended hostname certificate.

ACME DNS-01 Flow

Certificate issuance follows this sequence:

Traefik must have working DNS before this process can succeed.

Certificate Storage

Certificate state is stored in:

/opt/traefik/data/acme.json

The file must:

Deleting acme.json can remove all stored certificates and account state.

That may trigger unnecessary reissuance and certificate-rate-limit risk.

Certificate Validation

Inspect a certificate served by Traefik using:

openssl s_client -connect 127.0.0.1:443 -servername projects.bytek.ca </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates -ext subjectAltName

Verify:

Repeat with the relevant hostname when validating another service.

Certificate Troubleshooting

Certificate Missing From the Dashboard

Check:

ACME DNS Failure

A previously observed error reported:

The correction was to configure the Traefik container to use Pi-hole explicitly and recreate the container.

Wrong Certificate Served

Possible causes include:

Application Onboarding

When adding a new public application:

Backend Validation

Before troubleshooting an application through Traefik, test the direct backend from the Traefik VM.

Examples:

Nextcloud

nc -zv -w 5 192.168.2.100 11000

Vikunja

curl -i http://192.168.2.121:3456/health

Authentik

curl -I http://192.168.2.162:9000/-/health/ready/

BookStack

Use the confirmed BookStack IP on TCP port 6875.

A direct backend failure must be resolved before changing the Traefik router.

Local Router Validation

Traefik can be tested locally without relying on public DNS.

Example for Vikunja:

curl -k --resolve projects.bytek.ca:443:127.0.0.1 https://projects.bytek.ca/health

This forces the requested hostname to the local Traefik listener.

A successful response confirms:

Logging

Review the main Traefik log using:

sudo tail -n 100 /opt/traefik/logs/traefik.log

Filter common issues using:

sudo grep -iE 'error|acme|certificate|middleware|service|router|dns' /opt/traefik/logs/traefik.log | tail -n 100

Look for:

If access logging is enabled, use it to distinguish:

Do not copy session cookies, bearer tokens, or authorization headers into BookStack.

YAML Validation

YAML indentation must use spaces, not tabs.

Check dynamic configuration files using:

sudo grep -RnP '\t' /opt/traefik/dynamic/

Expected result:

Review a specific file using:

sudo cat /opt/traefik/dynamic/<filename>.yml

Common YAML problems include:

IP Address Changes

If an application IP changes:

A stale backend address causes gateway errors even when the application itself is healthy.

Firewall Requirements

The Traefik VM must accept:

Application VM firewalls must permit Traefik to reach their backend ports.

Known requirements include:

Do not allow public clients to connect directly to these backend ports.

Monitoring

Recommended Uptime Kuma monitors include:

Monitoring should distinguish between:

Power-Failure Recovery

After a power interruption:

If Traefik started before Pi-hole and DNS remains broken, recreate the Traefik container after Pi-hole is healthy.

Backup

The Traefik VM is included in the Proxmox scheduled backup job.

Protect the following paths:

Secrets must remain in a password manager or encrypted backup.

BookStack should document the secret location, not the secret itself.

Recovery Procedure

If Traefik configuration is broken:

If the VM must be restored:

Security Checklist

Validation Checklist

Document Control