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

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

The [Docker] container is deployed with the following image names:

* [authelia/authelia](https://hub.docker.com/r/authelia/authelia)
* [docker.io/authelia/authelia](https://hub.docker.com/r/authelia/authelia)
* [ghcr.io/authelia/authelia](https://github.com/authelia/authelia/pkgs/container/authelia)

## Get Started

It's __*strongly recommended*__ that users setting up *Authelia* for the first time take a look at our
[Get Started](../prologue/get-started.md) 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](https://docs.docker.com/compose/compose-file/05-services/#user)
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](https://docs.docker.com/engine/security/userns-remap/) facility [Docker] provides.

[docker run]: https://docs.docker.com/engine/reference/commandline/run/

## 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](#standalone-example)
* [Bundle: lite](#lite)
* [Bundle: local](#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](../../configuration/methods/secrets.md) files:
  * A file named `JWT_SECRET` for the [jwt_secret](../../configuration/miscellaneous/introduction.md#jwtsecret)
  * A file named `SESSION_SECRET` for the [session secret](../../configuration/session/introduction.md#secret)
  * A file named `STORAGE_PASSWORD` for the [PostgreSQL password secret](../../configuration/storage/postgres.md#password)
  * A file named `STORAGE_ENCRYPTION_KEY` for the [storage encryption_key secret](../../configuration/storage/introduction.md#encryptionkey)
* You're using PostgreSQL.
* You have an external network named `net` which is in bridge mode.

#### Using Secrets

Use this [Standalone Example](#standalone-example) if you want to use
[docker secrets](https://docs.docker.com/engine/swarm/secrets/).

{{< details "docker-compose.yml" >}}
```yaml
---
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](#standalone-example) if you want to use a standard
[docker volume](https://docs.docker.com/storage/volumes/) or bind mount for your secrets.

{{< details "docker-compose.yml" >}}
```yaml
---
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:

```bash
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](https://github.com/authelia/authelia/tree/master/examples/compose/lite) can be used by following this
process:

1. Perform the commands in [the bundles section](#bundles).
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](../../reference/guides/passwords.md#passwords), 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](https://github.com/authelia/authelia/tree/master/examples/compose/local) can be setup after cloning
the repository as per the [bundles](#bundles) section then running the following commands on a Linux Desktop:

```bash
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](https://public.example.com) - Bypasses Authelia
* [https://traefik.example.com](https://traefik.example.com) - Secured with Authelia one-factor authentication
* [https://secure.example.com](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](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:

```bash
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](#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" >}}
```yaml
---
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 >}}

[Docker]: https://docker.com
[Docker Compose]: https://docs.docker.com/compose/