Aller au contenu principal

Lancer avec Docker Compose

Vous pouvez aussi construire et démarrer l'ensemble de la pile avec Docker Compose (compose.yml) :

echo SYSTEM_DEFAULT_LLM_API_KEY=your_google_api_key_here > .env
docker compose up --build

Ouvrez http://localhost:3000. Les données de la base sont conservées dans le volume pgdata d'un redémarrage à l'autre.

Définissez APP_PORT dans .env pour publier l'application sur un autre port de l'hôte ; l'URL de base de l'application le suit automatiquement. Pour que l'application s'ouvre à une autre adresse — un nom d'hôte, par exemple —, définissez plutôt APP_BASE_URL dans .env avec cette adresse, comme http://a2flow.internal:3000. L'application reste publiée sur APP_PORT : si cette adresse comporte un port, alignez APP_PORT dessus.

Ce qui démarre​

ConteneurRôle
dbPostgreSQL 17. Tout ce qu'A2Flow enregistre se trouve ici
backendL'agent et l'API
workerEnvoie les e-mails de notification mis en file d'attente par le backend
mcp-proxyExécute les serveurs MCP que vous enregistrez — voir pourquoi il est séparé
ingressLe point d'entrée auquel s'adresse votre navigateur. Il transmet les requêtes des écrans au frontend et les requêtes d'API directement au backend
frontendLes écrans que vous utilisez
caddyUniquement avec compose.https.yml — voir Servir en HTTPS
openbaoUniquement avec --profile openbao — voir Essayer les secrets Vault avec OpenBao
keycloakUniquement avec --profile keycloak — voir Essayer l'authentification unique avec Keycloak

Seul l'ingress — ou Caddy à sa place, avec compose.https.yml — (et, avec leurs profils, l'interface d'OpenBao et Keycloak) est accessible depuis l'extérieur ; les autres conteneurs communiquent entre eux sur le réseau interne de Docker.

Le premier démarrage prend plus de temps que les suivants : les images sont construites, le schéma de la base de données est créé et le proxy MCP attend que le backend lui remette le certificat dont il a besoin avant d'accepter quoi que ce soit.

Servir en HTTPS​

Ajouter compose.https.yml place Caddy devant l'ingress. Il devient le seul point d'entrée, sur les ports 80 et 443, obtient un certificat pour l'adresse de APP_BASE_URL et redirige le HTTP en clair vers HTTPS. Une adresse https:// rend aussi les cookies de connexion sécurisés, et l'authentification unique en dérive son URI de redirection.

echo APP_BASE_URL=https://a2flow.example.com >> .env
docker compose -f compose.yml -f compose.https.yml up --build

Ouvrez l'adresse que vous avez définie. Elle ne doit comporter aucun port : seuls 80 et 443 sont publiés, et Caddy refuse de démarrer sur une adresse qui en comporte un. La suite dépend du nom d'hôte :

APP_BASE_URLCertificatAvant de commencer
Un nom d'hôte public, comme https://a2flow.example.comObtenu auprès de Let's Encrypt et renouvelé automatiquementFaites pointer le DNS du nom vers cet hôte et rendez les ports 80 et 443 accessibles depuis Internet
Non défini (https://localhost)Émis par une autorité de certification que Caddy crée pour lui-mêmeRien, mais le navigateur affiche un avertissement de certificat tant que vous ne faites pas confiance à cette autorité (ci-dessous)

Pour que le navigateur fasse confiance à https://localhost, copiez le certificat racine de l'autorité et ajoutez-le aux certificats racines de confiance de votre système d'exploitation ou de votre navigateur :

docker compose -f compose.yml -f compose.https.yml cp caddy:/data/caddy/pki/authorities/local/root.crt .

Les certificats et l'autorité locale sont conservés dans le volume caddy-data. Gardez-le : le supprimer fait émettre de nouveaux certificats, et un certificat racine auquel vous faisiez déjà confiance ne correspond plus.

Essayer les secrets Vault avec OpenBao​

OpenBao est un fork open source de Vault auquel A2Flow se connecte exactement comme à HashiCorp Vault. La pile peut en démarrer une instance à côté d'A2Flow, ce qui permet d'essayer les secrets de type Vault sans disposer de votre propre Vault.

docker compose --profile openbao up --build

OpenBao conserve ses données dans le même PostgreSQL qu'A2Flow, elles survivent donc aux redémarrages, et il se descelle tout seul à chaque démarrage. La clé qui sert au descellement se trouve dans le volume openbao-unseal : sauvegardez-la avec pgdata, car les données sont illisibles sans elle. Cette configuration sert à essayer l'intégration, pas à la production.

1. Initialiser OpenBao (premier démarrage uniquement)​

docker compose exec openbao bao operator init -recovery-shares=1 -recovery-threshold=1

Notez le Initial Root Token affiché : il n'apparaît qu'une seule fois.

2. Créer un AppRole pour A2Flow​

L'interface ne permet pas de créer un rôle AppRole : cette étape se fait donc en ligne de commande. Remplacez <root-token> par le jeton obtenu à l'étape 1 :

docker compose exec -e BAO_TOKEN=<root-token> openbao sh -c '
bao secrets enable -path=secret kv-v2
bao auth enable approle
printf "path \"secret/data/a2flow/*\" { capabilities = [\"read\"] }" | bao policy write a2flow -
bao write auth/approle/role/a2flow token_policies=a2flow token_ttl=1h
bao read -field=role_id auth/approle/role/a2flow/role-id; echo
bao write -f -field=secret_id auth/approle/role/a2flow/secret-id; echo'

Les deux dernières lignes affichent le role id et le secret id. La stratégie n'autorise A2Flow à lire que les chemins situés sous a2flow/.

3. Créer un secret dans l'interface d'OpenBao​

  1. Ouvrez http://localhost:8200/ui et connectez-vous avec la méthode Token et le jeton racine. OpenBao ne conserve pas une connexion par jeton racine au rechargement de la page : déplacez-vous donc en cliquant plutôt qu'en saisissant des URL.
  2. Ouvrez le moteur secret/ et choisissez Create secret.
  3. Saisissez a2flow/demo comme chemin, ajoutez les entrées username et password, puis enregistrez.

4. Connecter A2Flow​

  1. Connectez-vous à A2Flow en tant que root. Dans Paramètres système, définissez Adresse du Vault global sur http://openbao:8200 et enregistrez.
  2. Ouvrez Tenants, puis Default. Cochez Connexion au Vault global, choisissez AppRole comme Méthode d'authentification Vault, saisissez le role id et le secret id obtenus à l'étape 2, puis enregistrez.
  3. Connectez-vous en tant qu'admin. Dans Secrets, créez un secret de type HashiCorp Vault avec secret pour Point de montage Vault et a2flow/demo pour Chemin Vault.

Référencez-le comme n'importe quel autre secret, par exemple sous la forme ${secret:<name>/password} dans une variable d'environnement d'un serveur MCP. Partout où vous sélectionnez le secret, ses clés username et password sont listées : elles sont lues dans OpenBao à ce moment-là, ce qui montre que la connexion fonctionne.

Définissez OPENBAO_PORT dans .env pour publier l'interface d'OpenBao sur un port de l'hôte autre que 8200. A2Flow lui-même y accède toujours à l'adresse http://openbao:8200 sur le réseau interne.

Essayer l'authentification unique avec Keycloak​

Keycloak est un fournisseur d'identité open source. La pile peut en démarrer un à côté d'A2Flow, déjà configuré pour lui, ce qui permet d'essayer l'authentification unique sans votre propre IdP.

docker compose --profile keycloak up --build

Keycloak est publié à l'adresse http://keycloak.localhost:8180, et sa console d'administration s'ouvre avec admin / admin (définissez KEYCLOAK_ADMIN_PASSWORD dans .env pour changer le mot de passe). Chrome, Edge et Firefox trouvent keycloak.localhost d'eux-mêmes ; dans un autre navigateur, ajoutez d'abord la ligne 127.0.0.1 keycloak.localhost à votre fichier hosts. Keycloak ne conserve rien quand le conteneur est recréé : il repart de la configuration ci-dessous, et les modifications faites dans sa console sont perdues.

Il démarre avec ceci déjà en place :

ÉlémentValeur
Realma2flow
URL de l'émetteurhttp://keycloak.localhost:8180/realms/a2flow
ID clienta2flow
Secret clienta2flow-dev-secret
URI de redirectionhttp://localhost:3000 (ou votre APP_BASE_URL) et https://localhost, chacune suivie du chemin de retour d'A2Flow
Claim de groupesgroups
Utilisateursalice dans le groupe a2flow-admins, bob dans le groupe a2flow-users. Tous deux ont le mot de passe password

1. Connecter A2Flow​

  1. Connectez-vous à A2Flow en tant que admin et ouvrez Paramètres administrateur dans la barre latérale d'administration.
  2. Dans la section Authentification unique, renseignez URL de l'émetteur, ID client et Secret client avec les valeurs du tableau ci-dessus, cochez Activer l'authentification unique et enregistrez.
  3. Ouvrez Groupes d'utilisateurs, ouvrez un groupe — ou créez-en un — qui porte les rôles voulus, saisissez a2flow-admins dans Groupe IdP et enregistrez.

2. Se connecter​

  1. Déconnectez-vous. Sur l'écran de connexion, saisissez default dans Tenant et appuyez sur Se connecter avec SSO.
  2. Sur la page de connexion de Keycloak, connectez-vous en tant que alice / password. Vous revenez dans A2Flow, connecté en tant qu'Alice, membre du groupe de l'étape 1.
  3. Essayez aussi bob : son seul groupe, a2flow-users, n'est associé à aucun groupe d'utilisateurs, donc la connexion est refusée — jusqu'à ce que vous l'associiez à l'un d'eux.

Keycloak parle aussi SAML, mais A2Flow se connecte uniquement via OpenID Connect.