authelia/docs/content/en/integration/deployment/docker.md

title	description	lead	date	draft	images	menu	weight	toc
Docker	A guide on installing Authelia in Docker.	This is one of the primary ways we deliver Authelia to users and the recommended path.	2022-06-15T17:51:47+10:00	false		integration parent deployment	230	true

The Docker container is deployed with the following image names:

• authelia/authelia
• docker.io/authelia/authelia
• ghcr.io/authelia/authelia

Get Started

It's strongly recommended that users setting up Authelia for the first time take a look at our Get Started guide. This takes you through various steps which are essential to bootstrapping Authelia.

Container

Environment Variables

Several environment variables apply specifically to the official container. This table documents them. It is important to note these environment variables are specific to the container and have no effect on the Authelia daemon itself and this section is not meant to document the daemon environment variables.

Name	Default	Usage
PUID	0	If the container is running as UID 0, it will drop privileges to this UID via the entrypoint
PGID	0	If the container is running as UID 0, it will drop privileges to this GID via the entrypoint
UMASK	N/A	If set the container will run with the provided UMASK by running the umask ${UMASK} command

Permission Context

By default the container runs as the configured Docker daemon user. Users can control this behaviour in several ways.

The first and recommended way is instructing the Docker daemon to run the Authelia container as another user. See the docker run or Docker Compose file reference documentation for more information. The best part of this method is the process will never have privileged access, and the only negative is the user must manually configure the filesystem permissions correctly.

The second method is by using the environment variables listed above. The downside to this method is that the entrypoint itself will run as UID 0 (root). The advantage is the container will automatically set owner and permissions on the filesystem correctly.

The last method which is beyond our documentation or support is using the user namespace facility Docker provides.

Docker Compose

We provide two main Docker Compose examples which can be utilized to help test Authelia or can be adapted into your existing Docker Compose.

• Unbundled Example
• Bundle: lite
• Bundle: local

Standalone Example

The following examples are Docker Compose deployments with just Authelia and no bundled applications or proxies.

It expects the following:

• The file data/authelia/config/configuration.yml is present and the configuration file.
• The directory data/authelia/secrets/ exists and contain the relevant secret files:
  • A file named JWT_SECRET for the jwt_secret
  • A file named SESSION_SECRET for the session secret
  • A file named STORAGE_PASSWORD for the PostgreSQL password secret
  • A file named STORAGE_ENCRYPTION_KEY for the storage encryption_key secret
• You're using PostgreSQL.
• You have an external network named net which is in bridge mode.

Using Secrets

Use this Standalone Example if you want to use docker secrets.

{{< details "docker-compose.yml" >}}

---
version: "3.8"
secrets:
  JWT_SECRET:
    file: ${PWD}/data/authelia/secrets/JWT_SECRET
  SESSION_SECRET:
    file: ${PWD}/data/authelia/secrets/SESSION_SECRET
  STORAGE_PASSWORD:
    file: ${PWD}/data/authelia/secrets/STORAGE_PASSWORD
  STORAGE_ENCRYPTION_KEY:
    file: ${PWD}/data/authelia/secrets/STORAGE_ENCRYPTION_KEY
services:
  authelia:
    container_name: authelia
    image: docker.io/authelia/authelia:latest
    restart: unless-stopped
    networks:
      net:
        aliases: []
    expose:
      - 9091
    secrets: [JWT_SECRET, SESSION_SECRET, STORAGE_PASSWORD, STORAGE_ENCRYPTION_KEY]
    environment:
      AUTHELIA_JWT_SECRET_FILE: /run/secrets/JWT_SECRET
      AUTHELIA_SESSION_SECRET_FILE: /run/secrets/SESSION_SECRET
      AUTHELIA_STORAGE_POSTGRES_PASSWORD_FILE: /run/secrets/STORAGE_PASSWORD
      AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE: /run/secrets/STORAGE_ENCRYPTION_KEY
    volumes:
      - ${PWD}/data/authelia/config:/config
networks:
  net:
    external: true
    name: net
...

{{< /details >}}

Using a Secrets Volume

Use this Standalone Example if you want to use a standard docker volume or bind mount for your secrets.

{{< details "docker-compose.yml" >}}

---
version: "3.8"
services:
  authelia:
    container_name: authelia
    image: docker.io/authelia/authelia:latest
    restart: unless-stopped
    networks:
      net:
        aliases: []
    expose:
      - 9091
    environment:
      AUTHELIA_JWT_SECRET_FILE: /secrets/JWT_SECRET
      AUTHELIA_SESSION_SECRET_FILE: /secrets/SESSION_SECRET
      AUTHELIA_STORAGE_POSTGRES_PASSWORD_FILE: /secrets/STORAGE_PASSWORD
      AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE: /secrets/STORAGE_ENCRYPTION_KEY
    volumes:
      - ${PWD}/data/authelia/config:/config
      - ${PWD}/data/authelia/secrets:/secrets
networks:
  net:
    external: true
    name: net

... {{< /details >}}

Bundles

To use the bundles we recommend first cloning the git repository and checking out the latest release on a Linux Desktop:

git clone https://github.com/authelia/authelia.git
cd authelia
git checkout $(git describe --tags `git rev-list --tags --max-count=1`)

lite

The lite bundle can be used by following this process:

1. Perform the commands in the bundles section.
2. Run the cd examples/compose/lite command.
3. Edit users_database.yml and either change the username of the authelia user, or generate a new password, or both. The default password is authelia.
4. Edit the configuration.yml and docker-compose.yml with your respective domains and secrets.
5. Run docker compose up -d or docker-compose up -d.

local

The local bundle can be setup after cloning the repository as per the bundles section then running the following commands on a Linux Desktop:

cd examples/compose/local
./setup.sh

The bundle setup modifies the /etc/hosts file which is performed with sudo. Once it is successfully setup you can visit the following URL's to see Authelia in action (example.com will be replaced by the domain you specified):

• https://public.example.com - Bypasses Authelia
• https://traefik.example.com - Secured with Authelia one-factor authentication
• https://secure.example.com - Secured with Authelia two-factor authentication (see note below)

You will need to authorize the self-signed certificate upon visiting each domain. To visit https://secure.example.com you will need to register a device for second factor authentication and confirm by clicking on a link sent by email. Since this is a demo with a fake email address, the content of the email will be stored in ./authelia/notification.txt. Upon registering, you can grab this link easily by running the following command:

grep -Eo '"https://.*" ' ./authelia/notification.txt.

FAQ

Running the Proxy on the Host Instead of in a Container

If you wish to run the proxy as a systemd service or other daemon, you will need to adjust the configuration. While this configuration is not specific to Authelia and is mostly a Docker concept we explain this here to help alleviate the users asking how to accomplish this. It should be noted that we can't provide documentation or support for every architectural choice our users make and you should expect to do your own research to figure this out where possible.

The example below includes the additional ports option which must be added in order to allow communication to Authelia from daemons on the Docker host. The other values are used to show context within the Standalone Example above. The example allows Authelia to be communicated with over the localhost IP address 127.0.0.1 on port 9091. You need to adjust this to your specific needs.

{{< details "docker-compose.yml" >}}

---
services:
  authelia:
    container_name: authelia
    image: docker.io/authelia/authelia:latest
    restart: unless-stopped
    networks:
      net:
        aliases: []
    expose:
      - 9091
    ports:
      - "127.0.0.1:9091:9091"
...

{{< /details >}}