Install Traefik

Traefik is an ingress application proxy and router for all of your web services (HTTP / TCP / UDP). Traefik facilitates automatic TLS certificate management via Let’s Encrypt, and handles transport security for all of your applications. Traefik is configured to support several authentication and sentry authorization mechanisms, including: HTTP Basic Auth, OAuth2, mutual TLS, and IP address filtering.

sequenceDiagram
    participant Browser as Web Browser
    participant Traefik as Traefik Proxy
    participant Whoami as Container: whoami

Browser->>Traefik: HTTP Request
Traefik->>Whoami: Forward Request
Whoami->>Traefik: Response
Traefik->>Browser: HTTP Response

Basic Traefik config

Run this on the Raspberry Pi

pi make traefik config

This presents the interactive configuration menu for Traefik:

(stdout)

############################################################
###                          pi                          ###
############################################################

? Traefik:
> Config
  Install (make install)
  Admin
  Exit (ESC)
[↑↓ to move, enter to select, type to filter, ESC to cancel]

You can use the up and down arrow keys to choose the selection, and you may type any substring to narrow the list. Select the Config entry and press the Enter key.

Traefik Config

Don’t wander off

The Traefik configuration is extensive. This section will only show you how to configure Traefik for a basic install. Many of the menu options will be skipped for the time being. Follow these instructions exactly, and don’t go wandering through the other menus just yet.

(stdout)

During first time setup, you must complete the following tasks:

- Create Traefik user.
- Configure TLS certificates and ACME (optional).
- Install traefik.

Traefik must be re-installed to apply any changes.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

? Traefik Configuration:
> Traefik user
  Entrypoints (including dashboard)
  TLS certificates and authorities
  Middleware (including sentry auth)
  Advanced Routing (Layer 7 / Layer 4 / WireGuard)
  Error page template
v Logging level
[↑↓ to move, enter to select, type to filter, ESC to cancel]

Traefik user

(stdout)

? Traefik Configuration:
> Traefik user
  Entrypoints (including dashboard)
  TLS certificates and authorities
  Middleware (including sentry auth)
  Advanced Routing (Layer 7 / Layer 4 / Wireguard)
  Error page template
v Logging level

Select the Traefik user option to create the traefik user on the host.

Entrypoints (including dashboard)

(stdout)

? Traefik Configuration:
  Traefik user
> Entrypoints (including dashboard)
  TLS certificates and authorities
  Middleware (including sentry auth)
  Advanced Routing (Layer 7 / Layer 4 / Wireguard)
  Error page template
v Logging level

The following entrypoints are defined by default:

(stdout)

Entrypoint  Listen_address  Listen_port  Protocol  Upstream_proxy
----------  --------------  -----------  --------  --------------
web         0.0.0.0         80           tcp
websecure   0.0.0.0         443          tcp

You will need to reconfigure the websecure entrypoint, to enable the Proxy Protocol:

(stdout)

? Traefik entrypoint config
  Show enabled entrypoints
> Configure stock entrypoints
  Configure custom entrypoints

? Select entrypoint to configure:
  dashboard : Traefik dashboard (only accessible from 127.0.0.1:8080 and requires HTTP basic auth)
  web : HTTP (unencrypted; used to redirect requests to use HTTPS)
> websecure : HTTPS (TLS encrypted HTTP)
  web_plain : HTTP (unencrypted; specifically NOT redirected to websecure; must use different port than web)
  mqtt : MQTT (mosquitto) pub-sub service
  ssh : SSH (forgejo) git (ssh) entrypoint
v xmpp_c2s : XMPP (ejabberd) client-to-server entrypoint

> Do you want to enable the websecure entrypoint? Yes
Set TRAEFIK_WEBSECURE_ENTRYPOINT_ENABLED=true
TRAEFIK_WEBSECURE_ENTRYPOINT_HOST: Enter the host ip address to listen on (0.0.0.0 to listen on all interfaces) (e.g., 0.0.0.0)

: 0.0.0.0

TRAEFIK_WEBSECURE_ENTRYPOINT_PORT: Enter the host port to listen on (e.g., 443)

: 443

? Is this entrypoint downstream from another trusted proxy?
  No, clients dial directly to this server. (Turn off Proxy Protocol)
> Yes, clients are proxied through a trusted server. (Turn on Proxy Protocol)

TRAEFIK_WEBSECURE_ENTRYPOINT_PROXY_PROTOCOL_TRUSTED_IPS: Enter the comma separated list of trusted upstream proxy servers (CIDR)

: 10.13.16.1/32

10.13.16.1/32 is the correct (default) IP address of the sentry WireGuard peer.

Press ESC two times to get back to the traefik config menu.

Configure ACME

(stdout)

? Traefik Configuration:
  Traefik user
  Entrypoints (including dashboard)
> TLS certificates and authorities
  Middleware (including sentry auth)
  Advanced Routing (Layer 7 / Layer 4 / Wireguard)
  Error page template
v Logging level

? Traefik TLS config:
  Configure certificate authorities (CA)
> Configure ACME (Let's Encrypt or Step-CA)
  Configure TLS certificates (make certs)

? Which ACME provider do you want to use?
> Let's Encrypt (ACME)
  Step-CA (ACME)
  Disable ACME
  Cancel / Go back

? Which LE environment do you want to use?
> Production (recommended!)
  Staging (untrusted / testing)

Which type of ACME challenge should be used?
  TLS-ALPN-01 (default for public servers, easy, but no wildcard certs)
> DNS-01 (requires API key, but good behind firewalls, and allows wildcard certs)

TRAEFIK_ACME_CA_EMAIL: Enter your email address (not required; blank to skip)

:

TRAEFIK_ACME_DNS_PROVIDER: Enter the LEGO code for your DNS Provider (eg. digitalocean)

: digitalocean

TRAEFIK_ACME_DNS_VARNAME_1: Enter the 1st DNS provider variable name (eg. DO_AUTH_TOKEN)

: DO_AUTH_TOKEN

TRAEFIK_ACME_DNS_VARNAME_2: Enter the 2nd DNS provider variable name (or leave blank)

:

Now to enter the values for the custom DNS API variables:
DO_AUTH_TOKEN: Enter the value for DO_AUTH_TOKEN (e.g., your-actual-digitalocean-token-here)

: dop_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Request TLS certificates

(stdout)

? Traefik TLS config:
  Configure certificate authorities (CA)
  Configure ACME (Let's Encrypt or Step-CA)
> Configure TLS certificates (make certs)

? Configure Traefik TLS certificates
  Manage all certificates.
> Create a new certificate.
  Done / Go back

Next enter the domain names you want listed on this certificate:

pi.example.com (this is your main domain name CN record for the server.)
*.pi.example.com (this is your various app sub-domains wildcard SANS record, matching e.g., whoami.pi.example.com)
Any other domains you want listed on the same certificate.

(stdout)

Enter the main domain (CN) for this certificate (e.g., `d.rymcg.tech` or `*.d.rymcg.tech`)

: pi.example.com

Now enter additional domains (SANS), one per line:
Enter a secondary domain (enter blank to skip)

: *.pi.example.com

Enter a secondary domain (enter blank to skip)

:

It will continue asking you to enter additional SANS domains until you enter a blank response to signify you are done.

Certificate summary

(stdout)

Main domain:
 pi.example.com
Secondary (SANS) domains:
 *.pi.example.com

Finally a summary of the certificate request is printed.

Press the ESC key three times to go back to the main menu.

Error page template

You can customize the Traefik error page template by selecing a custom theme:

(stdout)

? Traefik Configuration:
^ Entrypoints (including dashboard)
  TLS certificates and authorities
  Middleware (including sentry auth)
  Advanced Routing (Layer 7 / Layer 4 / WireGuard)
> Error page template
  Logging level
  Access logs

? Select an error page theme (https://github.com/tarampampam/error-pages#-templates)
^ hacker-terminal
  cats
  lost-in-space
  app-down
  connection
> matrix
  orient

Since this theme is only used for the 404s and other errors coming from Traefik directly (and not for any errors coming from the apps themselves), the choice here is not purely aesthetic: as long as you choose unique error page template themes for each Traefik server instance (e.g., pi, sentry), you will gain extra debugging knowledge of knowing which Traefik instance is returning a particular error.

Install Traefik

(stdout)

############################################################
###                          pi                          ###
############################################################

? Traefik:
  Config
> Install (make install)
  Admin
  Exit (ESC)
[↑↓ to move, enter to select, type to filter, ESC to cancel]

On the main menu, select Install (make install).

Wait for the Traefik service to be installed, and then you will be returned to the main menu.

Press the Esc key to quit the Traefik configuration.

Verify Traefik status

You can check to see that Traefik has started:

Run this on the Raspberry Pi

pi make traefik status

You should see two services running: traefik and traefik-error-pages, both in state running:

(stdout)

NAME                   ENV              IMAGE                           STATE
traefik-error-pages-1  .env_pi_default  tarampampam/error-pages:2.25.0  running
traefik-traefik-1      .env_pi_default  traefik-traefik                 running