Skip to content

One-step (secure) configuration for Traefik edge router.

Notifications You must be signed in to change notification settings

jamescurtin/traefik-proxy

Repository files navigation

Traefik-Proxy

Linting T

One-step (secure) configuration for Traefik edge router using Authelia for authentication.

Features

Keeping in mind security first, this project ensures:

  • The Docker daemon socket is never mounted to traefik or any container with external networking (See the risks of exposing the Docker daemon)
  • HTTPS redirection is automatically configured for all routers
  • TLS is always enabled, even locally (can confidently test new services locally without needing a dev config that differs significantly from prod)
  • The Traefik dashboard is never launched in insecure mode

Other features include:

  • Self-hosted SSO authentication (Authelia), including support for security keys and one-time password generators
  • User-friendly 4XX & 5XX status pages
  • Pre-configured file provider (for shared routers and middleware) and Docker provider (for everything else)
  • Centralized configuration via environment variables and Docker secrets

Getting Started

Quickstart

$ git clone https://github.com/jamescurtin/traefik-proxy.git
$ cd traefik-proxy
$ make

Running make creates an .env file and the authelia/secrets directory. The .env file should be updated to include hostnames for additional hosts that are configured. The authelia/secrets directory contains secrets for configuring all services. If you follow the quickstart and run make, random passwords are generated by default. Otherwise, you must replace the values in authelia/secrets before deploying.

There are additional configuration files that need to be customized before you can deploy in a production environment. All places where customization is necessary are marked with CHANGEME comments.

The command will also create the external docker network traefik. Other docker services that you plan to expose via Traefik should be added to this network.

See the Exploring section for more information.

Users

This is configured to use two-factor auth. When running the project out of the box (i.e. without having configured the SMTP notifier), you will have to check the file authelia/notification.txt to get the registration link for configuring 2FA.

Authelia users are defined in authelia/users.yml.

By default, this ships with two users (both have the password insecure). One is a member of a group called admin, and the other has no group memberships. See the Exploring section to see how group membership can be used for access control.

Creating a user

You will need to create a new user and add them to authelia/users.yml. As a convenience, you can run the command

$ bin/create-new-user
Enter username:
...

which will prompt for the user's information, and add an entry to the user file (with a hashed password).

Make sure to remove the default users before deploying!

Exploring

Note: When run locally (e.g. on localhost), Traefik uses a self-signed SSL certificate. Therefore, web-browser security warnings are expected and can be safely bypassed. When deployed on any other domain, it will use Let's Encrypt certificates.

To explore, navigate to:

  • https://traefik.docker.localhost (Traefik configuration dashboard)
    • Requires login: see the Users section for more information.
  • https://whoami.docker.localhost ("Hello world" example)
  • https://secure.docker.localhost ("Hello world" example demonstrating ACLs and 2FA)
    • See the Users section for more information about the default users.
    • See the access_control section of authelia/configuration.yml to understand how access is configured.
    • First, attempt to log in with the user user-changeme. Access should be denied, because the user isn't a member of the required group
    • Next, go to auth.docker.localhost and log out.
    • Then, go back to secure.docker.localhost to log in with user admin-changeme. Access should be granted, based on user group.
      • See the Users section for information on how 2FA is configured by default.
  • https://auth.docker.localhost (SSO Auth service)
  • https://traefik.docker.localhost/nonexistent (This page doesn't exist, and is therefore re-routed to a custom error page)

Testing

Run the test suite locally via

.github/scripts/test.sh