Traefik Role¶

Overview¶

This role deploys Traefik, a modern HTTP reverse proxy and load balancer, as a rootless Podman container. It features automatic service discovery, Let's Encrypt integration for SSL certificates, dynamic configuration, and a built-in dashboard for monitoring.

Requirements¶

Podman 4.x or later
Systemd
A user with sudo access

Installation / Quick Start¶

Orchestrator¶

# Prepare
./manage-svc.sh traefik prepare

# Deploy
./manage-svc.sh traefik deploy

# Verify
./svc-exec.sh traefik verify

Role Variables / Configuration¶

Key Variables¶

Name	Description	Default
`traefik_state`	`present` to install, `absent` to remove.	`present`
`traefik_data_dir`	The directory to store Traefik data (e.g., ACME certificates).	`"~/traefik-data"`
`traefik_http_port`	The HTTP port Traefik listens on.	`8080`
`traefik_https_port`	The HTTPS port Traefik listens on.	`8443`
`traefik_dashboard_port`	The port for the Traefik dashboard.	`9999`
`traefik_dashboard_enabled`	Enable the Traefik dashboard.	`true`
`traefik_enable_ssl`	Enable SSL/TLS for ingress traffic.	`true`
`traefik_acme_email`	Email address for Let's Encrypt registrations.	`your@email.com`

Usage¶

Dashboard Access¶

Open your web browser to http://localhost:9999/dashboard/ to access the Traefik dashboard.

Configuration¶

Traefik automatically discovers services by watching for Podman container labels. Here's an example of labels for a service:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.myapp.rule=Host(`myapp.example.com`)"
  - "traefik.http.services.myapp.loadbalancer.server.port=8080"

Dynamic Routing¶

Traefik can route requests based on various criteria, including host headers, path prefixes, request headers, and query parameters.

Service Management¶

# Check status
systemctl --user status traefik-pod

# View logs
podman logs traefik-svc

# Restart service
systemctl --user restart traefik-pod

Troubleshooting¶

Certificate Issues¶

Check ACME logs: podman logs traefik-svc | grep acme
Verify ACME storage: ls -l ~/traefik-data/acme.json

Routing Not Working¶

Check router configuration: curl http://localhost:9999/api/http/routers | jq .
Verify service is discovered and container labels are correct.
Review Traefik logs for errors.

Port Binding Issues¶

For ports less than 1024, you may need to:

sudo setcap 'cap_net_bind_service=+ep' /usr/bin/podman

Alternatively, use high ports (e.g., 8080, 8443) and forward them via iptables.

Role-Specific Sections¶

Let's Encrypt Integration¶

When traefik_enable_ssl is true, Traefik automatically requests, renews, and handles ACME challenges for certificates from Let's Encrypt.

Removal¶

# Remove but keep data (certificates)
./manage-svc.sh traefik remove

# Delete all (including certificates and data)
./manage-svc.sh traefik remove -e traefik_delete_data=true