Installer authentik avec Docker Compose

Cette leçon déploie authentik 2026.8.4 avec Docker Compose, crée le compte administrateur par l'assistant initial et vérifie qu'un utilisateur ordinaire peut se connecter. Vous repartirez avec un environnement fonctionnel en une quinzaine de minutes, une compréhension des trois conteneurs et la capacité de modifier leur configuration. Prérequis : Docker et Docker Compose installés. Chaque sortie de la page a été observée le 15 octobre 2026 sur cette version, dans un navigateur Chromium.

Avant de commencer

Si les concepts d'authentik (applications, providers, flows, stages, policies) ne vous sont pas familiers, lisez d'abord la leçon Comprendre authentik qui explique l'architecture et la logique modulaire. Ce lab met en pratique ces notions. Ce module est facultatif : le fournisseur d'identité de référence de la formation reste Keycloak.

Ce que vous allez apprendre

• Déployer un serveur authentik (interface web + API), un worker (tâches de fond : emails, synchronisations) et une base PostgreSQL avec Docker Compose
• Créer le compte administrateur par l'assistant initial, et savoir pourquoi il faut passer par la racine du site
• Vérifier la version, la santé des composants et les journaux
• Comprendre les fichiers de configuration (variables, volumes, ports) et savoir les modifier
• Créer un premier utilisateur et vérifier sa connexion

L'ensemble tourne en local sur votre machine. Aucun serveur distant n'est nécessaire.

Prérequis

Le tableau liste ce que la machine doit offrir, avec la commande qui le vérifie.

Prérequis	Version minimale	Vérification
Docker	20+	docker --version
Docker Compose	v2+	docker compose version
Navigateur web	Récent	Sans objet
RAM disponible	2 Go (et 2 cœurs CPU)	free -h
Espace disque	2 Go	Pour les images Docker

Glissez pour voir

Pourquoi 2 Go de RAM ?

authentik fait tourner PostgreSQL, un serveur web et un worker, et le premier démarrage (les migrations) est le moment le plus gourmand. La documentation officielle d'authentik demande un hôte avec au moins 2 cœurs CPU et 2 Go de RAM : c'est le minimum. En dessous, PostgreSQL ou le worker risquent d'être tués par l'OOM killer, le mécanisme du noyau Linux qui arrête un processus quand la mémoire est épuisée.

Architecture du lab

Le lab déploie 3 conteneurs sur un réseau Docker interne :

Source · SVG

Échap pour fermer, + et − pour zoomer, défilement pour se déplacer. 100 % − Ajuster + Fermer

Le serveur gère l'interface web, l'API et les flows d'authentification. Le worker exécute les tâches asynchrones : envoi d'emails, synchronisation LDAP, provisioning SCIM. Les deux partagent la même base PostgreSQL.

Redis a été retiré

Depuis la version 2025.10, authentik n'a plus besoin de Redis. Le cache, les sessions, les verrous et la communication inter-processus utilisent désormais PostgreSQL. Cela simplifie le déploiement et réduit le nombre de composants à maintenir.

Préparer le projet

Trois fichiers suffisent : un .env qui porte les secrets, un docker-compose.yaml qui décrit les conteneurs, et le répertoire qui les contient, dont le nom devient le préfixe des conteneurs.

1. Créez le répertoire du lab

   mkdir -p ~/Projets/authentik-lab && cd ~/Projets/authentik-lab

2. Générez la clé secrète

   authentik a besoin d'une clé secrète (AUTHENTIK_SECRET_KEY) pour signer les tokens et chiffrer les données sensibles. Cette clé doit rester stable entre les redémarrages, sinon toutes les sessions sont invalidées. Le fichier .env est créé lisible par vous seul (umask 077 dans un sous-shell).

   ( umask 077; echo "AUTHENTIK_SECRET_KEY=$(openssl rand -base64 60 | tr -d '\n')" > .env )

   Vérifiez la présence de la clé sans l'afficher :

   grep -c '^AUTHENTIK_SECRET_KEY=' .env && ls -l .env

   La commande doit afficher 1, puis un fichier en -rw-------.

   Ne partagez jamais cette clé

   La AUTHENTIK_SECRET_KEY est l'équivalent d'une clé de chiffrement maître. Si elle fuite, un attaquant peut forger des tokens d'administration. Ne la commitez pas dans un dépôt git. En production, utilisez un gestionnaire de secrets.

3. Ajoutez le mot de passe PostgreSQL

   echo "PG_PASS=$(openssl rand -base64 36 | tr -d '\n')" >> .env

4. Créez le fichier Docker Compose

   docker-compose.yaml

   services:
     postgresql:
       image: docker.io/library/postgres:16-alpine@sha256:721873c34ceb9f8d8fc265984940dc982404c105f19ad51be9fdc5970a6080ea
       restart: unless-stopped
       healthcheck:
         test: ["CMD-SHELL", "pg_isready -d $${POSTGRES_DB} -U $${POSTGRES_USER}"]
         start_period: 20s
         interval: 30s
         retries: 5
         timeout: 5s
       env_file:
         - .env
       environment:
         POSTGRES_DB: ${PG_DB:-authentik}
         POSTGRES_PASSWORD: ${PG_PASS:?database password required}
         POSTGRES_USER: ${PG_USER:-authentik}
       volumes:
         - database:/var/lib/postgresql/data
   
     server:
       image: ${AUTHENTIK_IMAGE:-ghcr.io/goauthentik/server}:${AUTHENTIK_TAG:-2026.8.4@sha256:e7226ae116dac5aa0a5643803e735b010038f492c401e08e16b3bf1ac54c090c}
       restart: unless-stopped
       command: server
       env_file:
         - .env
       environment:
         AUTHENTIK_POSTGRESQL__HOST: postgresql
         AUTHENTIK_POSTGRESQL__USER: ${PG_USER:-authentik}
         AUTHENTIK_POSTGRESQL__NAME: ${PG_DB:-authentik}
         AUTHENTIK_POSTGRESQL__PASSWORD: ${PG_PASS}
         AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY:?secret key required}
       volumes:
         - ./data:/data
         - ./custom-templates:/templates
       ports:
         - "${COMPOSE_PORT_HTTP:-9000}:9000"
         - "${COMPOSE_PORT_HTTPS:-9443}:9443"
       shm_size: 512mb
       depends_on:
         postgresql:
           condition: service_healthy
   
     worker:
       image: ${AUTHENTIK_IMAGE:-ghcr.io/goauthentik/server}:${AUTHENTIK_TAG:-2026.8.4@sha256:e7226ae116dac5aa0a5643803e735b010038f492c401e08e16b3bf1ac54c090c}
       restart: unless-stopped
       command: worker
       user: root
       env_file:
         - .env
       environment:
         AUTHENTIK_POSTGRESQL__HOST: postgresql
         AUTHENTIK_POSTGRESQL__USER: ${PG_USER:-authentik}
         AUTHENTIK_POSTGRESQL__NAME: ${PG_DB:-authentik}
         AUTHENTIK_POSTGRESQL__PASSWORD: ${PG_PASS}
         AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY:?secret key required}
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock
         - ./data:/data
         - ./certs:/certs
         - ./custom-templates:/templates
       shm_size: 512mb
       depends_on:
         postgresql:
           condition: service_healthy
   
   volumes:
     database:
       driver: local

   Pourquoi le Docker socket sur le worker ?

   Le worker monte /var/run/docker.sock pour déployer et gérer automatiquement les outposts (proxy, LDAP, RADIUS). Si vous n'utilisez pas cette fonctionnalité ou préférez limiter l'accès, vous pouvez retirer ce montage et déployer les outposts manuellement. La documentation d'authentik prévient que monter le socket Docker comporte des risques de sécurité inhérents : quiconque contrôle le conteneur qui le monte contrôle le démon Docker de l'hôte. Elle propose un proxy de socket Docker comme couche de protection supplémentaire. Acceptable en lab ; en production, préférez ce proxy ou le déploiement manuel des outposts.

   Pourquoi deux conteneurs authentik ? Le server et le worker utilisent la même image Docker mais avec une commande différente. Le serveur gère les requêtes HTTP (interface, API, flows). Le worker exécute les tâches en arrière-plan (emails, synchro LDAP, SCIM). Cette séparation évite qu'une tâche lourde bloque l'interface.

   Version et digests. Les images sont épinglées par digest (@sha256:...), relevé sur le registre : le tag seul peut être déplacé, le digest désigne un contenu précis. Cette leçon est jouée sur 2026.8.4, la dernière version publiée au 15 octobre 2026. Pour passer à une version suivante, relevez son digest avec docker buildx imagetools inspect ghcr.io/goauthentik/server:<tag> et rejouez la leçon avant de la substituer.

Comprendre la configuration

Avant de démarrer, détaillons les éléments clés : les variables qui portent les secrets et la connexion à la base, les volumes qui gardent les données, et les ports publiés sur votre machine.

Les variables d'environnement

Variable	Rôle
AUTHENTIK_SECRET_KEY	Clé de chiffrement et de signature (tokens, sessions)
PG_PASS	Mot de passe de la base PostgreSQL
AUTHENTIK_POSTGRESQL__HOST	Hôte PostgreSQL (nom du service Docker)
AUTHENTIK_POSTGRESQL__USER	Utilisateur PostgreSQL
AUTHENTIK_POSTGRESQL__NAME	Nom de la base de données
AUTHENTIK_POSTGRESQL__PASSWORD	Mot de passe PostgreSQL
COMPOSE_PORT_HTTP, COMPOSE_PORT_HTTPS	Ports publiés sur votre machine (9000 et 9443 par défaut)

Glissez pour voir

authentik utilise le préfixe AUTHENTIK_ pour toutes ses variables. Les doubles underscores (__) séparent les niveaux de configuration : AUTHENTIK_POSTGRESQL__HOST correspond à postgresql.host dans la configuration interne.

Les volumes

Un volume nommé garde la base, et trois dossiers du répertoire du lab sont montés dans les conteneurs : ce sont eux qui survivent à un docker compose down.

Volume / Mount	Rôle
database	Données PostgreSQL persistées entre redémarrages
./data	Fichiers uploadés (logos, icônes d'applications, rapports CSV)
./custom-templates	Templates personnalisés pour les pages de connexion
./certs	Certificats TLS (worker uniquement, si vous en fournissez)

Glissez pour voir

Les ports

Port	Protocole	Usage
9000	HTTP	Interface web et API
9443	HTTPS	Interface web et API (TLS auto-signé)

Glissez pour voir

En lab, le port 9000 (HTTP) suffit. En production derrière un reverse proxy (Traefik, Nginx), celui-ci gère la terminaison TLS.

Déployer l'environnement

Le déploiement tient en deux commandes, puis en trois vérifications : les conteneurs, la santé et les journaux. Le premier démarrage prend environ une minute, le temps des migrations de la base.

1. Téléchargez les images Docker

   docker compose pull

   Chaque image se termine par une ligne Pulled, avec son tag et son digest.

2. Démarrez les services

   docker compose up -d

   Compose attend que PostgreSQL soit sain avant de lancer les deux autres conteneurs. Les dernières lignes sont :

   Container authentik-lab-postgresql-1 Healthy
   Container authentik-lab-server-1 Started
   Container authentik-lab-worker-1 Started

3. Vérifiez que tous les conteneurs tournent

   docker compose ps --format 'table {{.Name}}\t{{.Status}}'

   Les trois conteneurs ont un healthcheck. Pendant la première minute, le serveur et le worker affichent (health: starting) ; attendez que les trois soient (healthy) avant d'ouvrir le navigateur :

   NAME                         STATUS
   authentik-lab-postgresql-1   Up About a minute (healthy)
   authentik-lab-server-1       Up About a minute (healthy)
   authentik-lab-worker-1       Up About a minute (healthy)

4. Vérifiez la version dans les journaux

   Les journaux d'authentik sont en JSON, une ligne par événement. La ligne de démarrage porte la version :

   docker compose logs server | grep -m1 '"event":"authentik is starting"'

   Elle contient "event":"authentik is starting","version":"2026.8.4". Le même filtre sur worker donne la même ligne pour le worker. Au premier démarrage, le serveur enchaîne ensuite des lignes Migration needs to be applied et Migration finished applying : c'est la création de la base.

Première connexion

Le compte administrateur se crée par l'assistant initial, et cet assistant ne s'ouvre qu'en passant par la racine du site. C'est le piège le plus courant de cette version : la racine redirige vers /setup, qui prépare la session, puis vers le flux initial-setup.

1. Ouvrez la racine du site

   Rendez-vous sur http://localhost:9000/. Le navigateur est redirigé vers /setup, puis vers http://localhost:9000/if/flow/initial-setup/, où s'affiche le formulaire « Welcome to authentik! ».

   Passez par la racine, pas par l'URL du flux

   Ouvrir directement /if/flow/initial-setup/ dans un navigateur neuf affiche Access the authentik setup by navigating to http://localhost:9000/ : le flux refuse une session qui n'est pas passée par /setup. Revenez à la racine. Une fois le compte créé, la racine mène à la page de connexion.

2. Créez le compte administrateur

   Le formulaire demande quatre champs :

   • Email : votre adresse
   • Password et Password (repeat) : un mot de passe fort, deux fois
   • Base URL : l'adresse publique d'authentik, déjà remplie avec http://localhost:9000 ; gardez-la en lab

   Validez. authentik enregistre l'adresse et le mot de passe sur le compte akadmin, qui a tous les droits d'administration, et vous connecte aussitôt : vous arrivez sur le portail utilisateur, /if/user/.

3. Ouvrez l'interface d'administration

   L'adresse http://localhost:9000/if/admin/ mène au tableau de bord de l'administration. L'interface suit la langue du navigateur : avec un navigateur en français, ce tableau s'appelle Vue d'ensemble, sous le menu Tableaux de bord (Dashboards en anglais). Il affiche notamment :

   • Statut du système : OK
   • Version : 2026.8.4, avec la mention « À jour ! »
   • Workers : 1
   • les événements récents : connexion, mot de passe défini, utilisateur écrit

4. Notez comment vous reconnecter

   L'écran de connexion demande d'abord un identifiant, puis le mot de passe sur un second écran. L'identifiant accepte l'email saisi à l'étape 2 ou le nom d'utilisateur akadmin : les deux ont été vérifiés.

Accéder au lab

Les adresses ci-dessous supposent le port par défaut. Si vous travaillez à distance, il faut d'abord faire venir le port sur votre machine.

En local

Si Docker tourne directement sur votre machine :

Interface	URL
Assistant initial (par la racine)	http://localhost:9000/
Administration	http://localhost:9000/if/admin/
Portail utilisateur	http://localhost:9000/if/user/
API	http://localhost:9000/api/v3/

Glissez pour voir

VS Code SSH Remote

Si vous travaillez en SSH Remote (Docker tourne sur un serveur distant) :

1. Ouvrez le panneau Ports dans VS Code (onglet à côté du Terminal)
2. Cliquez Forward a Port et entrez 9000
3. VS Code crée un tunnel SSH : localhost:9000 sur votre machine locale → port 9000 du serveur distant

Ouvrez ensuite les URLs dans votre navigateur local :

Interface	URL
Assistant initial (par la racine)	http://localhost:9000/
Administration	http://localhost:9000/if/admin/
Portail utilisateur	http://localhost:9000/if/user/

Glissez pour voir

Vérifier que la plateforme fonctionne

Trois vérifications en ligne de commande complètent le tableau de bord : la sonde de santé, l'API publique et l'absence d'erreurs dans les journaux.

Santé et API

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:9000/-/health/ready/
curl -s http://localhost:9000/api/v3/root/config/ | jq -c '.capabilities'

La sonde répond 200 quand le serveur est prêt. L'API publique renvoie la configuration du serveur, dont la liste capabilities (can_save_media, can_impersonate, etc.) : une réponse JSON prouve que le serveur répond. Les autres points de l'API exigent une session ou un jeton, et répondent 403 sans.

Journaux sans erreurs

Les journaux étant en JSON, cherchez le niveau error, pas le mot :

docker compose logs server --since 5m | grep -cE '"level": ?"error"'

En fonctionnement normal, le compte vaut 0. Un simple grep -i error remonte au contraire plus d'une centaine de lignes saines, comme installing error formatting ou la migration alter_validators_add_error_messages.

Créer un premier utilisateur de test

Pour valider le flux d'authentification complet, créez un utilisateur non administrateur, puis connectez-vous avec lui dans une fenêtre séparée.

1. Ouvrez la liste des utilisateurs

   Dans l'interface d'administration, menu Directory → Users (Répertoire → Utilisateurs en français), puis le bouton New User.

2. Choisissez le type de compte

   L'assistant Create New User propose Internal User (employé), External User (consultant ou client) et Service Account (automate). Choisissez Internal User : l'assistant passe aux détails.

3. Remplissez les détails

   • Username : testuser
   • Name : Utilisateur Test
   • Email : test@exemple.fr
   • Is active : laissé coché

   Cliquez Create.

4. Définissez un mot de passe

   Ouvrez la fiche de testuser dans la liste, puis le bouton Set password, qui demande un seul champ. Enregistrez.

5. Testez la connexion

   Ouvrez une fenêtre de navigation privée et allez sur http://localhost:9000/if/user/. Connectez-vous avec testuser et son mot de passe : vous arrivez sur le portail utilisateur, vide tant qu'aucune application n'est configurée. Si ce compte demande /if/admin/, il est renvoyé au portail : il n'a pas les droits d'administration.

Modifier la configuration

Toute la configuration passe par le fichier .env et les variables du fichier Compose : on modifie, puis on recrée les conteneurs.

Changer le port d'écoute

Si le port 9000 est déjà utilisé sur votre machine, ne touchez pas au fichier Compose : ses lignes ports lisent deux variables. Ajoutez-les au fichier .env (ce lab a été rejoué ainsi sur 9010 et 9453) :

echo "COMPOSE_PORT_HTTP=9010" >> .env
echo "COMPOSE_PORT_HTTPS=9453" >> .env
docker compose up -d

Compose recrée le serveur avec les nouveaux ports. Pensez à changer l'adresse dans le navigateur, et la Base URL si l'assistant initial n'a pas encore été joué.

Activer l'envoi d'emails

Pour les flows de récupération de mot de passe et les invitations, authentik a besoin d'un serveur SMTP. La documentation d'authentik décrit les variables AUTHENTIK_EMAIL__* à ajouter dans .env. Cette configuration n'a pas été rejouée dans ce lab :

.env

AUTHENTIK_EMAIL__HOST=smtp.exemple.fr
AUTHENTIK_EMAIL__PORT=587
AUTHENTIK_EMAIL__USERNAME=authentik@exemple.fr
AUTHENTIK_EMAIL__PASSWORD=votre-mot-de-passe-smtp
AUTHENTIK_EMAIL__USE_TLS=true
AUTHENTIK_EMAIL__FROM=authentik@exemple.fr

Puis recréez les conteneurs pour appliquer :

docker compose up -d

Email optionnel en lab

L'envoi d'emails n'est pas nécessaire pour ce lab. Les flows de connexion et de création d'utilisateurs fonctionnent sans. Vous en aurez besoin uniquement pour l'enrôlement par invitation et la récupération de mot de passe.

Ajouter des variables de configuration

Toutes les options d'authentik sont configurables via des variables d'environnement préfixées AUTHENTIK_. Les doubles underscores correspondent aux niveaux de la configuration YAML :

Variable d'environnement	Équivalent YAML
AUTHENTIK_LOG_LEVEL	log_level
AUTHENTIK_COOKIE_DOMAIN	cookie_domain
AUTHENTIK_DISABLE_UPDATE_CHECK	disable_update_check

Glissez pour voir

Dépannage

Chaque ligne du tableau correspond à un comportement observé sur authentik 2026.8.4 pendant le rejeu de cette leçon. Lisez le message exact avant de changer un réglage.

Symptôme	Cause probable	Solution
required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required au docker compose up	la clé manque dans .env	regénérer la clé (étape 2 de la préparation), puis relancer
/if/flow/initial-setup/ en 404 juste après le démarrage	le premier démarrage n'est pas terminé : la sonde /-/health/ready/ répond déjà 200 alors que le flux n'existe pas encore	attendre que les trois conteneurs soient (healthy), puis passer par la racine
Access the authentik setup by navigating to http://localhost:9000/	l'URL du flux a été ouverte directement	ouvrir la racine http://localhost:9000/
connection refused sur :9000	serveur pas encore démarré	docker compose ps, attendre (healthy)
Page de connexion sans compte créé	l'assistant initial n'a pas été joué	ouvrir la racine dans un navigateur neuf
ERR_CONNECTION_REFUSED en SSH Remote	port non transféré	transférer le port 9000 dans VS Code

Glissez pour voir

Lire les logs en détail

Pour diagnostiquer un problème, les journaux sont le premier réflexe. Chaque ligne est un objet JSON : le champ event dit ce qui s'est passé, level sa gravité.

# Journaux du serveur (interface + API)
docker compose logs server --since 10m

# Journaux du worker (tâches de fond)
docker compose logs worker --since 10m

# Tous les journaux en temps réel
docker compose logs -f

Réinitialiser complètement

Si l'environnement est dans un état incohérent et que vous voulez repartir de zéro :

docker compose down -v
docker compose up -d

Perte de données

L'option -v supprime les volumes Docker, donc toutes les données : utilisateurs, applications, configuration. Ne l'utilisez qu'en lab.

Nettoyage

Pour arrêter et supprimer l'environnement de lab, puis le fichier qui porte les secrets :

# Arrêter les conteneurs (données conservées)
docker compose down

# Supprimer aussi les volumes (données perdues) et les secrets
docker compose down -v
rm -f .env

À retenir

• authentik se déploie en 3 conteneurs : serveur, worker et PostgreSQL, tous trois avec un healthcheck
• La AUTHENTIK_SECRET_KEY est la clé maître : stable, secrète, dans un .env en 600
• L'assistant initial s'ouvre par la racine du site ; l'URL directe du flux est refusée
• Il crée le compte akadmin avec l'email saisi et vous connecte aussitôt
• Le serveur et le worker utilisent la même image avec des commandes différentes
• Les journaux sont en JSON : on filtre sur "level", pas sur le mot « error »
• Le port 9000 (HTTP) suffit en lab, en production, utilisez un reverse proxy avec TLS
• Toute la configuration passe par des variables d'environnement préfixées AUTHENTIK_

Contrôle de connaissances

Six questions tirées parmi huit vérifient que vous savez déployer authentik et le prendre en main : rôle du worker, clé secrète, assistant initial, configuration et nettoyage.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

×

📖 Voir la documentation →