Skip to content

Traefik Standards and Migration Guide

Status: Living documentation — migration complete
Updated: October 2026
Companion: Traefik Infrastructure

Objectives and final state

The migration replaced Nginx Proxy Manager (NPM) with Traefik while retaining GUI administration, file-based configuration, Portainer management, centralized authentication, automatic TLS, and the option of future high availability.

The migration is complete. NPM was shut down and deleted. Its old forwarding configuration and rollback plan are retained below only as history.

Production conventions

Area Standard
Reverse proxy traefik-1.barnesbears.xyz / 192.168.10.110
Administration Portainer and Traefik Manager
Router naming <service>-router
Backend naming <service>-service
TLS Let's Encrypt certificate resolver
Identity Keycloak and oauth2-proxy where needed
DNS Service aliases in BarnesBears DNS
Config Versioned or backed-up static/dynamic files and persistent volumes
Monitoring Zabbix, Traefik metrics and logs
Security CrowdSec, middleware, appropriate LAN/public access policy

Do not expose an internal-only service simply because it has an internal DNS record. Apply appropriate firewall and/or Traefik source-IP restrictions.

Adding a new service

  1. Deploy the application and verify it directly on its backend IP/port.
  2. Create or verify the service DNS record pointing to Traefik (192.168.10.110), not to the backend.
  3. In Traefik Manager, define the backend service URL (for example http://192.168.10.95:80 for the documentation LXC).
  4. Create a router with Host(\service.barnesbears.xyz`)and the correct entrypoint (websecure` for HTTPS).
  5. Enable TLS and select the existing working Let's Encrypt resolver; do not assume the resolver's name.
  6. Apply suitable middleware: authentication, headers, compression, redirects, and/or source-IP allowlist.
  7. Save, confirm that Traefik loaded the router/service/middleware, and test the site by hostname.
  8. Verify the certificate, application login/callbacks, and any required external or LAN access.
  9. Check Traefik access/error logs and Zabbix after rollout.
  10. Document the hostname, backend, access policy, exceptions and recovery steps in MkDocs.

Documentation LXC

The MkDocs backend is docs at 192.168.10.95:80. Its intended hostname is docs.barnesbears.xyz, LAN-only. Confirm the actual router and allowlist before marking it deployed.

Example routing pattern

Illustrative only; match the names of your existing resolver and middleware:

http:
  routers:
    docs-router:
      rule: "Host(`docs.barnesbears.xyz`)"
      entryPoints:
        - websecure
      service: docs-service
      middlewares:
        - lan-only
      tls:
        certResolver: REPLACE_WITH_CONFIGURED_RESOLVER
  services:
    docs-service:
      loadBalancer:
        servers:
          - url: "http://192.168.10.95:80"

The lan-only middleware must be defined and enforced before using the example. Do not paste this into production unchanged.

Application-specific migration lessons

Nextcloud

Traefik replaced NPM as a trusted proxy. The migration initially documented both NPM (192.168.10.81) and Traefik (192.168.10.110) in Nextcloud's trusted proxy list. Remove the old NPM address if it remains; validate current settings with Nextcloud OCC.

Immich

Long-running requests used Traefik readTimeout and idleTimeout settings of 600 seconds. No buffering middleware was needed.

OAuth and Keycloak

Keycloak realm BarnesBears and oauth2-proxy provide centralized login for suitable applications. Some services have their own authentication and require exceptions; avoid indiscriminately applying ForwardAuth to API/webhook paths.

CrowdSec

Persist plugin storage across container recreations. Validate custom parsers and scenarios before restarting CrowdSec; preserve the local Immich-thumbnail false-positive exception rather than broadly disabling security.

Zabbix

Certificate expiry metrics are available from Traefik; stale certificate series may persist until a Traefik restart. Zabbix also monitors Traefik health and uses a guarded recovery script.

Migration history (not active procedures)

During the phased migration, traffic flowed:

Internet -> Firewall -> NPM -> Traefik -> Application

The temporary upstream used Traefik HTTPS with migration-specific NPM directives including proxy_ssl_verify off. Temporary self-signed certificates allowed service-by-service cutover.

The final state became:

Internet -> Firewall (TCP 80/443) -> Traefik -> Application

After the final cutover, the firewall forwarded TCP 80 and 443 directly to 192.168.10.110, Let's Encrypt was used, and NPM was decommissioned and deleted. Old NPM configuration, proxy trust, and temporary certificate guidance should not be reintroduced.

Routine change / upgrade checklist

  1. Record current image tags and export/backup Portainer stack configuration.
  2. Back up /opt/traefik configuration, acme.json, manager data, CrowdSec local config, and relevant persistent volumes.
  3. Validate configuration and check existing errors/alerts.
  4. Update Traefik Manager or Traefik individually, not both simultaneously; preserve volumes and plugin storage.
  5. Check docker ps, logs, routers, TLS certificates, OAuth flows, CrowdSec middleware, and Zabbix.
  6. Test a representative set of applications (including authenticated, public, and internal routes).
  7. Document versions, unexpected behavior, and recovery actions.

Recovery without NPM

  1. Confirm whether the failure is DNS, firewall, Traefik, authentication, CrowdSec, or the backend.
  2. Review Traefik logs and container health; check recent Portainer stack changes.
  3. Restore a known-good Traefik configuration/stack or container image version with persistent data.
  4. Preserve/restore ACME data and OAuth secrets securely.
  5. Verify port 80/443 routing, certificate issuance, authentication, and backend access.
  6. Verify monitoring and document the incident.

Obsolete rollback

The original npm-1 restart and NAT switch-back procedure no longer works because NPM was deleted.

Future improvements

  • Shared middleware conventions and explicit public/internal access policies
  • Regular tested configuration backups and disaster-recovery drills
  • Additional Git-backed review of Traefik Manager configuration
  • Optional HA architecture
  • Periodic validation of Zabbix and CrowdSec alerting