RPJosh
/
authelia
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
authelia/docs/content/en/integration/deployment/docker.md

9.8 KiB
Raw Blame History

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:

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.

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:
  • 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):

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.

Frequently Asked Questions

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 >}}