Déployer sur Docker Swarm

Vaks PM · Déploiement à partir de zéro · Docker Swarm · Juin 2026

Vue d'ensemble

L'installation Swarm est pilotée par un installeur guidé lancé depuis un poste de pilotage, la machine depuis laquelle l'administrateur travaille, qui ne fait pas partie du cluster. L'installeur se connecte aux hôtes cibles en SSH (Secure Shell, protocole d'administration à distance chiffré) et fait tout à distance. Aucun Docker n'est requis sur le poste de pilotage, car les images de conteneurs sont construites sur un hôte cible plutôt qu'en local.

Un unique manifeste déclaratif (infra/cluster.json) décrit la cible : son mode, ses hôtes, ses rôles et ses tenants. Un générateur (infra/cluster/generate.mjs) transforme ce manifeste en artefacts de déploiement prêts à l'emploi. À partir de là :

• Hôte unique exécute tout sur une seule machine dans un Swarm mono-nœud. PostgreSQL tourne comme conteneur, le même script orchestrateur (out/deploy-ssh.sh) réalise la mise en route en SSH, et le résultat convient bien à l'évaluation et aux petits sites.
• Haute disponibilité (HA) répartit sur plusieurs hôtes avec une base de données répliquée et aucun point de défaillance unique. Un seul script orchestrateur (out/deploy-ssh.sh) réalise toute la mise en route en SSH.

Le système en fonctionnement est le même dans les deux cas : des services applicatifs sans état (web, api, worker, et une porte d'entrée partagée controlplane) adossés à trois stockages durables : PostgreSQL, Redis, et un stockage objet S3 (Simple Storage Service) on-premise. Un reverse proxy Traefik termine le TLS et n'expose que les ports 80 et 443.

Glossaire

Acronymes utilisés tout au long de ce guide, définis ici une fois pour toutes.

Prérequis & état initial

Les listes ci-dessous décrivent le point de départ attendu avant l'exécution de toute commande.

Poste de pilotage

La machine depuis laquelle l'administrateur conduit l'installation. Elle ne rejoint pas le cluster.

• Windows, Linux ou macOS avec un client SSH (OpenSSH) et Node.js installé (Node est requis par le générateur).
• Pas de Docker local. Les images de conteneurs sont construites sur un hôte cible.
• Une copie du dépôt du projet, via le bouton « Download ZIP » de la forge ou git clone. Le téléchargement ne contient aucun secret : .env.local et le dossier keys/ sont volontairement exclus et doivent être fournis à la main (ci-dessous) ; node_modules/ et dist/ sont également absents (la construction se fait sur un hôte).

Hôtes cibles

• Debian 13 (ou compatible), accessible en SSH par clé, avec sudo disponible.
• Mono 1 hôte. HA 3 hôtes est la référence ; un nombre impair satisfait le quorum etcd dont la couche de coordination de la base de données a besoin.
• La clé SSH publique de l'administrateur déjà présente dans ~/.ssh/authorized_keys de l'utilisateur d'installation sur chaque hôte. Sans elle, l'installeur ne peut pas se connecter.
• Les noms d'hôtes système connus, par exemple host1, host2, host3, ou des noms réels comme srv-prod-01. Le nom doit correspondre à la valeur renvoyée par uname -n, car il sert à poser les labels de nœud Swarm et à identifier les membres Patroni/etcd.

Réseau, DNS & TLS

• Entrant : seuls les ports 80 et 443 doivent être joignables par les clients. Traefik redirige 80 vers 443 et termine le TLS ; tout autre port de service reste sur le réseau interne/overlay.
• DNS : le nom d'hôte de chaque organisation (<slug>.<baseDomain>) doit résoudre vers le point d'entrée, c'est-à-dire l'adresse de l'hôte manager ou la VIP partagée en HA. Un seul nom d'hôte suffit pour une installation à organisation unique. Pour un test rapide avant que le DNS soit prêt, la requête peut être forcée vers une adresse avec curl --resolve.
• TLS : un certificat auto-signé est généré automatiquement pendant l'installation (suffisant pour un test ou un LAN, même si les navigateurs affichent un avertissement). En production, le remplacer par un vrai certificat, ou activer l'émission Let's Encrypt sur Traefik.

Le fichier de configuration .env.local

Un fichier à la racine du dépôt sur le poste de pilotage, jamais commité dans le gestionnaire de sources. Il porte les accès SSH et les adresses des hôtes. Le bloc infra est requis pour les deux modes :

VM_USER=ops                 # SSH and sudo user on the hosts
VM_PASS=********            # real sudo password of VM_USER (dev/test convenience)
VM_HOST1=10.0.0.1
VM_HOST2=10.0.0.2          # HA only
VM_HOST3=10.0.0.3          # HA only
SSH_KEY=keys/id_ed25519    # path to the OpenSSH private key

Copier la clé OpenSSH privée de l'utilisateur d'installation dans le dépôt (par convention keys/id_ed25519, ignoré par git) et fixer ses permissions :

cp .env.example .env.local       # then edit it
mkdir -p keys && cp /path/to/my_key keys/id_ed25519 && chmod 600 keys/id_ed25519

Manifeste & générateur

Un assistant guidé (setup.sh) demande le mode, les hôtes et leurs rôles, le domaine racine et les tenants, puis écrit le manifeste (infra/cluster.json, ignoré par git) et appelle le générateur. Le lancer depuis la racine du dépôt. Il existe trois invocations :

bash setup.sh                                          # interactive wizard, generate only
bash setup.sh --manifest infra/cluster.json            # non-interactive, generate only (replays a saved manifest)
bash setup.sh --manifest infra/cluster.json --deploy   # generate, then deploy

Par défaut, setup.sh ne fait que générer. Il écrit le manifeste, rend les artefacts out/ listés ci-dessous, et s'arrête. Rien n'est installé sur aucun hôte, ce qui laisse la sortie examinable avant toute exécution. La forme non interactive fait de même à partir d'un manifeste qui existe déjà, ce qui permet de rejouer une configuration éprouvée sans répondre de nouveau aux questions.

--deploy ajoute une seule action après la génération : il lance bash out/deploy-ssh.sh, l'orchestrateur qui réalise toute la mise en route en SSH. En HA, cela couvre les étapes ordonnées détaillées dans Déploiement en haute disponibilité : le tier base de données, l'initialisation et la jonction du Swarm, les labels de nœud et les secrets, la construction des images, le déploiement de la stack, l'initialisation de Garage et le provisionnement des tenants. En mono, il couvre la même séquence moins le tier base de données natif — PostgreSQL tourne comme conteneur dans la stack (voir Déploiement sur hôte unique). Omettre --deploy ne saute pas le déploiement, il le sépare seulement : le même orchestrateur est alors lancé à la main comme prochaine étape explicite.

bash out/deploy-ssh.sh   # run the orchestrator when ready

Le générateur (infra/cluster/generate.mjs) rend les artefacts suivants sous out/ :

Déploiement sur hôte unique 1 machine

En mode single, tout tourne sur une seule machine dans un Swarm mono-nœud (le même mécanisme de secrets qu'en production, évolutif vers la HA plus tard). PostgreSQL tourne dans un conteneur, il n'y a donc pas de tier natif Patroni/etcd/HAProxy. Comme en HA, la mise en route est orchestrée en SSH depuis le poste de pilotage par le out/deploy-ssh.sh généré :

bash setup.sh                  # choose "single", enter the IP, the domain, the database name
bash out/deploy-ssh.sh         # orchestrates the ENTIRE bring-up
# or in one go:
bash setup.sh --manifest infra/cluster.json --deploy

Seuls VM_USER et SSH_KEY (plus VM_PASS quand le sudo demande un mot de passe) sont requis dans .env.local. Chaque mot de passe et clé dont la stack a besoin est généré automatiquement s'il n'est pas fourni : le mot de passe Postgres est persisté dans .pg-creds et la paire de clés S3 dans .s3-creds (tous deux ignorés par git), ce qui rend le script idempotent — le relancer réutilise les mêmes valeurs et saute ce qui existe déjà.

L'orchestrateur exécute ces étapes ordonnées en SSH, toutes automatiques :

Mise en route manuelle (secours)

La même séquence, étape par étape, lancée directement sur la machine cible — pour le cas où aucun poste de pilotage avec accès SSH n'est disponible, ou pour comprendre exactement ce que fait l'orchestrateur. Générer out/ n'importe où, le transférer vers l'hôte ou cloner le dépôt là-bas, puis dérouler les étapes sur cette machine.

Étape manuelle 1 : installer Docker sur la machine

Le mode mono n'a pas de tier base de données natif, mais Docker Engine est requis pour le Swarm mono-nœud. Le générateur produit un script prêt à l'emploi nommé d'après l'hôte. Le lancer sur la machine cible :

sudo bash out/host-node1.sh     # installs Docker Engine + enables it
docker --version                # check

Étape manuelle 2 : construire les images et préparer le déploiement

La stack tourne sur trois images applicatives construites sur la machine, plus quelques fichiers qu'elle attend : les deux configs générées et un certificat TLS auto-signé.

# 1) Build the 3 application images (from the repository root)
docker build -t vaks-pm/api:latest    -f api/Dockerfile .
docker build -t vaks-pm/web:latest    -f web/Dockerfile .
docker build -t vaks-pm/worker:latest -f worker/Dockerfile .

# 2) Files the stack expects (the ./infra paths resolve relative to the compose file)
mkdir -p out/infra/certs
cp out/traefik-dynamic.gen.yml out/garage.gen.toml out/infra/
openssl req -x509 -newkey rsa:2048 -nodes -days 365 -subj "/CN=*.local" \
  -keyout out/infra/certs/wildcard.key -out out/infra/certs/wildcard.crt

Étape manuelle 3 : Swarm + secrets

Initialiser le Swarm, puis créer les secrets. Copier-coller le bloc tel quel, en ne changeant que les deux mots de passe en clair (Postgres et S3) :

docker swarm init

# 1) Random secrets: nothing to choose
openssl rand -base64 48 | docker secret create jwt_access_secret -
openssl rand -base64 48 | docker secret create jwt_refresh_secret -
openssl rand -base64 32 | docker secret create mfa_encryption_key -
openssl rand -hex 32   | docker secret create garage_rpc_secret -
openssl rand -hex 32   | docker secret create garage_admin_token -

# 2) Postgres password: choose ONCE, reused in database_url
PGPASS='ChangeMe-strong-Postgres-password'
printf '%s' "$PGPASS" | docker secret create postgres_password -
printf 'postgresql://vakspm:%s@postgres:5432/vakspm?schema=public' "$PGPASS" | docker secret create database_url -

# 3) S3 (Garage) key, formats imposed by Garage: access = "GK"+24 hex, secret = 64 hex
S3_ACCESS=GK$(openssl rand -hex 12)
S3_SECRET=$(openssl rand -hex 32)
echo "S3 access=$S3_ACCESS"; echo "S3 secret=$S3_SECRET"   # NOTE these two values
printf '%s' "$S3_SECRET" | docker secret create s3_secret_key -

# 4) SMTP password (leave a dummy value if no email / anonymous relay)
printf 'ChangeMe-or-x' | docker secret create smtp_password -

# 5) Internal secrets — REQUIRED by the stack even when the feature is unused
#    (they are declared external: the deploy fails if any is missing)
openssl rand -hex 32 | docker secret create worker_api_token -
openssl rand -hex 16 | docker secret create sso_oidc_secret -
printf 'none' | docker secret create syslog_client_key -

docker secret ls   # check: 12 secrets created

Étape manuelle 4 : déployer la stack

Reporter la clé d'accès S3 de l'étape manuelle 3 (même shell) dans la stack, puis déployer :

sed -i -E "s|S3_ACCESS_KEY:.*|S3_ACCESS_KEY: $S3_ACCESS|g" out/docker-stack.gen.yml
docker stack deploy -c out/docker-stack.gen.yml vaks-pm
docker service ls   # garage/postgres/redis/api/controlplane at 1/1

Étape manuelle 5 : initialiser le stockage Garage (S3)

Garage démarre vierge. Lui assigner une disposition de stockage, puis enregistrer la clé S3 notée à l'étape manuelle 3. L'API crée ensuite ses buckets au redémarrage :

CID=$(docker ps -q -f name=vaks-pm_garage | head -1)
g(){ docker exec "$CID" /garage "$@"; }

# 1) Layout: read the node id, assign a zone + capacity, apply
g status                                  # note the <node_id>
g layout assign -z dc1 -c 100G <node_id>
g layout apply --version 1

# 2) Register the S3 key (same values as manual step 3) + bucket-creation right
g key import --yes -n vakspm-app "$S3_ACCESS" "$S3_SECRET"
g key allow --create-bucket "$S3_ACCESS"

# 3) Restart the API → it creates the buckets on startup
docker service update --force vaks-pm_api
g bucket list   # → charter-blobs, document-templates, vaks-pm-attachments, vaks-pm-branding

Étape manuelle 6 : créer la première organisation et l'administrateur

En mode dedicated, le manifeste ne crée aucune organisation, il faut donc en amorcer une après la mise en route de la stack :

# 1) Prepare the config from the template, then edit it (slug, name, admin email)
cp infra/org-bootstrap.example.json infra/org-bootstrap.json
#    admin.password = null → generated randomly, shown ONCE in the output.

# 2) Inject it into the api container and run the bootstrap
CID=$(docker ps -q -f name=vaks-pm_api | head -1)
docker cp infra/org-bootstrap.json "$CID":/app/api/org-bootstrap.json
docker exec "$CID" sh -c 'export DATABASE_URL=$(cat /run/secrets/database_url) \
  && cd /app/api && node prisma/bootstrap-org.js'

Haute disponibilité N hôtes

La topologie HA supprime tout point de défaillance unique : un cluster PostgreSQL répliqué, un control plane redondant, et un stockage S3 réparti sur les hôtes. Toute la mise en route est orchestrée en SSH depuis le poste de pilotage par une seule commande, sans aucune étape manuelle sur les hôtes.

Rôles des hôtes

L'assistant demande quels rôles porte chaque hôte. Plusieurs rôles peuvent être combinés sur un même hôte.

Topologie HA

• Control plane : Traefik + controlplane répliqués sur les hôtes cp. Un point d'entrée unique est fourni par une VIP keepalived sur ces hôtes (le champ de manifeste controlPlane.vip) ou par DNS round-robin.
• Data plane : le pool api est réparti sur les hôtes app. Le JWT du control plane est requis, et le tenant qu'il embarque doit correspondre à l'hôte demandé.
• PostgreSQL HA : Patroni + etcd (quorum impair ≥ 3) ; un HAProxy local route les écritures vers le leader sur le port 5000 et les lectures vers les réplicas sur 5001. Le backend atteint la base via HAProxy, jamais directement.

Ce qui va dans .env.local pour la HA

En plus des variables infra, l'orchestrateur HA lit les valeurs de base de données et JWT. Générer chacune une fois dans le shell et coller le résultat littéral. Ne pas écrire $(openssl …) dans le fichier : il est sourcé à chaque exécution et régénérerait une valeur différente à chaque fois.

# DB / Patroni
POSTGRES_USER=vakspm
POSTGRES_PASSWORD=<value>
POSTGRES_DB=vakspm
PATRONI_REPLICATION_PASSWORD=<value>
PATRONI_SUPERUSER_PASSWORD=<value>
# Auth (JWT signing keys, high entropy required)
JWT_ACCESS_SECRET=<value>
JWT_REFRESH_SECRET=<value>

# Generate the values once, then paste each result above:
openssl rand -hex 24     # DB passwords (hex: no @ : / ? # & % which would break the DSN)
openssl rand -base64 48  # JWT keys (read as Docker secrets, not embedded in a URL)

Lancer l'orchestrateur

bash setup.sh                  # choose "ha", N hosts, roles, tenants
bash out/deploy-ssh.sh         # orchestrates the ENTIRE bring-up
# or in one go:
bash setup.sh --manifest infra/cluster.json --deploy

L'orchestrateur exécute ces étapes ordonnées en SSH, toutes automatiques :

Provisionner des tenants

En mode pooled, chaque tenant (organisation cliente) a sa propre base de données <dbName>_<slug> à l'intérieur du cluster PostgreSQL partagé, et tous les tenants partagent le pool api, résolu par nom d'hôte. Un slug est un identifiant court et compatible URL ([a-z0-9-]+ : minuscules, chiffres et tirets uniquement ; pas de point, espace, majuscule ni accent). Les tenants peuvent être déclarés dans le manifeste ou provisionnés plus tard sans y toucher :

# In an api container (on an "app" host):
docker exec <api-cid> sh -c \
  'export DATABASE_URL=$(cat /run/secrets/database_url) && \
   cd /app/api && node prisma/provision-tenant.js acme admin@acme.com'

Le provisionnement crée la base de données du tenant, applique le schéma et amorce son administrateur. La connexion se fait alors à acme.<baseDomain> via le control plane. Un tenant dedicated obtient en plus sa propre cellule api-<slug> / worker-<slug> avec des ressources isolées, routée par son nom d'hôte.

Couches de chiffrement

Une installation Swarm possède plusieurs couches de chiffrement indépendantes. Le TLS interne, le chiffrement de volume au repos (sur une installation en haute disponibilité) et la clé maîtresse de repli du trousseau applicatif sont actifs d'emblée. Le durcissement restant, une autorité de certification personnalisée, la vérification stricte de la base de données, le trousseau versionné et le chiffrement des sauvegardes, s'active par une modification du fichier de stack ou par une action d'administration. Les couches sont documentées ensemble dans cette section, mais elles ne sont pas toutes appliquées au même moment ; la dernière colonne indique quand chacune intervient.

TLS interne

Une installation neuve provisionne le TLS interne automatiquement avec des certificats auto-signés : le trafic interne est chiffré, mais l'identité des pairs n'est pas vérifiée. Trois flux sont couverts :

• Base de données : TLS PostgreSQL pour les connexions applicatives et pour la réplication entre nœuds (20-patroni.sh).
• Magasin de coordination : TLS mutuel (mTLS) peer et client d'etcd, où chaque nœud est à la fois serveur et client (10-etcd.sh). etcd démarre en HTTPS dès le premier boot, et un rétrofit du TLS etcd sur un cluster en fonctionnement est risqué et délibérément évité.
• Réseau overlay : l'overlay Swarm utilise le chiffrement à clé symétrique IPsec géré par Docker (aucun certificat impliqué).

Le bootstrap place un certificat partagé unique à /etc/vaks/server.{crt,key} (les mêmes octets sur chaque hôte, ce qui permet au mTLS peer etcd auto-ancré de fonctionner : chaque nœud fait confiance au certificat que ses pairs présentent en utilisant ce même certificat comme propre ancre de confiance). Des copies par service pour postgres et etcd sont créées une fois les utilisateurs système présents.

Fournir une autorité de certification personnalisée (optionnel)

Pour ajouter la vérification de l'identité (protection contre un attaquant actif de type man-in-the-middle), remplacer les certificats auto-signés par des certificats émis par la CA (Certificate Authority, autorité de certification) interne de l'organisation. L'exigence décisive : émettre un certificat dont l'Extended Key Usage porte à la fois serverAuth et clientAuth (le mTLS etcd a besoin des deux, et un certificat serveur seul est rejeté côté client), et dont le Subject Alternative Name (SAN) liste chaque IP d'hôte plus 127.0.0.1 et localhost. Produire trois fichiers PEM : le certificat feuille (server.crt, plus toute chaîne intermédiaire), la clé privée non chiffrée correspondante (server.key, mode 600, possédée par l'utilisateur de service), et le certificat de la CA (ca.crt). Les installer sur chaque hôte un à la fois (les réplicas d'abord), pointer les ancres de confiance vers ca.crt (*_TRUSTED_CA_FILE d'etcd, etcd3.cacert de Patroni), puis redémarrer les services et confirmer la santé du cluster avant de passer au nœud suivant.

Par défaut, l'application ouvre une connexion TLS vers PostgreSQL mais ne vérifie pas le certificat du serveur. La vérification stricte (protection contre un attaquant actif de type man-in-the-middle sur le saut app-vers-base) est contrôlée par trois variables d'environnement lues par les services api et controlplane, les deux seuls qui ouvrent des connexions à la base de données :

Le certificat de la CA n'est pas secret, il est donc fourni comme config Docker, le même mécanisme que la stack utilise déjà pour le certificat de Traefik. La procédure édite le fichier de stack : docker-stack.yml sur un hôte unique, ou out/docker-stack.gen.yml sur un cluster en haute disponibilité (régénéré par le générateur de manifeste, donc réappliquer la modification après toute régénération). Lancer les étapes sur un manager Swarm.

1. Placer la CA sur le manager et la déclarer comme config. Copier le certificat de la CA émettrice vers infra/certs/pg-ca.crt à côté du fichier de stack, puis ajouter une entrée sous le bloc configs: de premier niveau :

configs:
  pg_ca_v1:
    file: ./infra/certs/pg-ca.crt

2. Monter la config et définir les variables sur les deux services. Ajouter les quatre mêmes lignes au service api et au service controlplane (tous deux se connectent à la base de données ; le worker ne le fait pas et reste inchangé) :

    environment:
      # ...existing variables...
      PG_TLS: "1"
      PG_TLS_CA: /etc/vaks/pg-ca/ca.crt
      PG_TLS_MODE: verify-ca
    configs:
      - source: pg_ca_v1
        target: /etc/vaks/pg-ca/ca.crt

3. Redéployer et confirmer. Les configs sont immuables une fois créées, donc une modification ultérieure de la CA nécessite un nouveau nom (pg_ca_v2) référencé aux deux endroits.

docker stack deploy --with-registry-auth -c <stack-file> vaks-pm
# the api/controlplane tasks restart; a bad CA path or chain shows up as a
# database-connection error in the logs:
docker service logs --since 3m vaks-pm_api
docker service logs --since 3m vaks-pm_controlplane

Chiffrement disque (LUKS2 + Tang)

La couche de chiffrement disque au repos protège les volumes de données (les données PostgreSQL et le stockage objet Garage) avec LUKS2 (aes-xts-plain64, 512 bits). Elle ne chiffre que ces volumes, pas l'OS de l'hôte, et est déverrouillée par libération de clé liée au réseau : un disque volé seul ne peut pas être déchiffré. Deux étapes de bootstrap la mettent en place. Sur une installation en haute disponibilité, le script par hôte généré les exécute automatiquement, avant le tier base de données, de sorte que les volumes sont montés vides avant l'initialisation de PostgreSQL. Les paramètres ci-dessous sont renseignés par le générateur et sont documentés ici pour expliquer ce qui s'exécute, non comme une étape manuelle. Pour sauter cette couche, par exemple lorsque le chiffrement de disque complet est déjà assuré au niveau de l'infrastructure, l'assistant accepte une réponse non, enregistrée comme encryption.diskLuks: false dans le manifeste.

Serveur Tang (15-tang.sh)

Tang est un petit serveur de clés réseau sans état (il ne détient aucun secret par client). Le bootstrap l'installe aux côtés de Clevis (le client qui lie un volume LUKS à un ou plusieurs serveurs Tang) et écoute sur le port 7500. Dans une installation multi-hôtes, chaque hôte exécute un serveur Tang, et les hôtes se lient aux serveurs Tang les uns des autres, jamais au leur.

Volumes LUKS & liaison Clevis (18-luks-data.sh)

Cette étape crée des conteneurs LUKS2 sur fichier pour les données PostgreSQL et Garage, puis les lie aux serveurs Tang pairs avec une politique Clevis SSS (Shamir Secret Sharing, partage de secret de Shamir) de seuil t=1 : le volume se déverrouille automatiquement tant qu'au moins un serveur Tang pair est joignable. Un assistant au démarrage retente le déverrouillage et monte le volume. Le script d'hôte généré passe automatiquement les adresses des serveurs Tang pairs (les IP des autres hôtes de base de données) :

PEER_TANG_IPS="ip1,ip2"   # IPs of the PEER Tang hosts (never the host's own)
SETUP_PG=1                # prepare the pgdata volume   (default)
SETUP_GARAGE=1            # prepare the garage volume   (default)

Trousseau de clés local (KEK/DEK)

L'application chiffre certains champs sensibles (mot de passe SMTP, secrets client SSO (single sign-on, authentification unique), graines MFA (multi-factor authentication, authentification multifacteur), secrets de connecteur de ticketing) avec le chiffrement par enveloppe : une DEK (Data Encryption Key, AES-256-GCM) par tenant chiffre les champs, et une KEK (Key Encryption Key) enveloppe la DEK. La KEK ne touche jamais aux données ; elle ne fait que verrouiller et déverrouiller les DEK. Faire tourner la KEK ré-enveloppe une poignée de petites DEK et ne re-chiffre aucune donnée de champ, c'est donc rapide et sans interruption.

État par défaut : pas de trousseau

D'emblée, aucun fichier de clé versionné n'est monté. L'application lit une unique clé maîtresse de 32 octets depuis le secret Docker mfa_encryption_key (créé pendant l'installation) et l'enregistre comme référence KEK env. Le chiffrement et le déchiffrement fonctionnent immédiatement ; il n'y a simplement encore rien à faire tourner. En production, au moins une KEK doit être chargeable, soit un fichier kek_v* soit la clé maîtresse mfa_encryption_key, sinon les services api/controlplane refusent de démarrer.

Ajouter et activer une KEK versionnée

Monter un trousseau versionné est ce qui active la rotation. Chaque version de KEK est un secret Docker nommé kek_v<N> contenant du texte base64 qui décode en exactement 32 octets. Lancer sur un manager Swarm :

# 1) Create the secret directly from generated material (never written to disk)
openssl rand -base64 32 | docker secret create kek_v1 -

Déclarer le secret external: true dans le fichier de stack et le monter sur les deux services api et controlplane (les seuls services qui déchiffrent, puisque le worker ne le fait pas), en définissant la version active :

environment:
  CRYPTO_KEYS_DIR: /run/secrets   # directory scanned for kek_v* files
  CRYPTO_ACTIVE_KEK: v1           # new wraps use this version
secrets:
  - kek_v1

docker stack deploy --with-registry-auth -c <stack-file> vaks-pm
docker service logs --since 3m vaks-pm_api | grep Keyring
# expected: Keyring loaded: v1, env (active=v1)

Faire tourner

Pour faire tourner la KEK : ajouter un nouveau secret kek_v<N+1> en gardant le précédent monté, définir CRYPTO_ACTIVE_KEK sur la nouvelle version, redéployer, puis déclencher la ré-enveloppe depuis Admin → Sécurité & Conformité → Clés de chiffrement → Faire tourner la KEK. La DEK de chaque tenant est déballée avec son ancienne KEK et ré-enveloppée sous la nouvelle ; aucune donnée de champ n'est re-chiffrée. Ne retirer l'ancienne KEK qu'une fois que chaque DEK référence la nouvelle et qu'aucune sauvegarde conservée ne peut encore référencer l'ancienne KEK.

Checklist de chiffrement

Confirmer que chaque couche est active après l'installation :

Secrets Swarm

Les valeurs sensibles ne sont jamais intégrées aux images ni commitées. Elles vivent comme secrets Swarm, chiffrées dans le journal Raft sur les managers et montées en lecture seule dans les conteneurs sous /run/secrets/. Dans les deux modes, l'orchestrateur les crée/génère tous automatiquement ; la séquence manuelle de secours (mono) les crée à la main à l'étape manuelle 3.

Vérifications post-installation

Confirmer que l'instance est saine avant de la remettre :

# cluster state
docker stack ps vaks-pm                  # all tasks Running
patronictl -c /etc/patroni.yml list      # 1 leader + N replicas (HA)

# control plane: sign-in on a tenant (401 on bad creds = the chain works)
curl -sk --resolve acme.vaks-pm.com:443:<manager-ip> \
  -X POST https://acme.vaks-pm.com/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@acme.com","password":"..."}'

# data plane: api liveness/readiness
curl -sk --resolve acme.vaks-pm.com:443:<manager-ip> https://acme.vaks-pm.com/api/v1/health/live    # 200
curl -sk --resolve acme.vaks-pm.com:443:<manager-ip> https://acme.vaks-pm.com/api/v1/health/ready   # 200

• Liveness / readiness : l'api expose /health/live et /health/ready (tous deux utilisés par les health checks propres à Swarm).
• Connexion : le compte administrateur amorcé peut se connecter et atteindre l'espace d'administration. /api/v1/auth/* est servi par le controlplane ; tout le reste par l'api. Un JWT émis pour un autre tenant est rejeté.
• Stockage objet : l'envoi d'une pièce jointe de tâche réussit (cela exerce le chemin S3 de bout en bout).
• Email (si configuré) : l'action Envoyer un email de test de l'espace d'administration délivre un message.

Pannes & reprise

Les données métier vivent dans PostgreSQL (HA via Patroni) ; les autres services portent un état souple qui peut être reconstruit. Quand un hôte tombe, Swarm réagit selon le type de placement de chaque service.

Mises à jour & montée de version

Une montée de version remplace les images de conteneurs par une version plus récente ; le client ne construit ni ne modifie jamais de code. Comme api/web/worker sont sans état et tournent en plusieurs réplicas, Swarm procède par rolling update — il remplace les réplicas un par un et les réplicas survivants absorbent le trafic, donc l'opération est sans interruption. Le schéma de base de données évolue avec l'image (voir Schéma de base de données plus bas), il n'y a donc pas de pack de migrations SQL à jouer séparément dans le cas courant.

1 · Obtenir les nouvelles images

Trois façons d'amener la nouvelle version sur les hôtes, selon la manière dont l'instance a été livrée :

2 · Rolling update des services

Swarm ne re-tire pas un tag inchangé sans --force. Déployer service par service. L'ordre recommandé met l'api (et son jumeau controlplane) en premier, car c'est elle qui aligne le schéma au démarrage :

TAG=1.4.0   # the version being rolled out

docker service update --force --with-registry-auth --image vaks-pm/api:$TAG    vaks-pm_api
docker service update --force --with-registry-auth --image vaks-pm/api:$TAG    vaks-pm_controlplane
docker service update --force --with-registry-auth --image vaks-pm/worker:$TAG vaks-pm_worker
docker service update --force --with-registry-auth --image vaks-pm/web:$TAG    vaks-pm_web

docker service ls          # every service back to its replica count, image = the new tag

Chaque commande attend la convergence des réplicas avant de rendre la main ; le déploiement s'arrête tout seul si les nouvelles tâches ne deviennent pas saines (health check /health/ready), laissant les anciennes tâches servir. En mode pooled, les cellules dédiées par tenant (vaks-pm_api-<slug> / vaks-pm_worker-<slug>) se mettent à jour de la même façon, une par une.

3 · Schéma de base de données

Le schéma voyage dans l'image : au démarrage, le conteneur api lit le schema.prisma de la nouvelle image et aligne la base automatiquement (prisma db push). Pour une montée de version de routine, il n'y a donc aucune étape de migration manuelle — le simple rolling update de l'api à l'étape 2 applique le schéma.

# from an api image, pointed at the target database with a DDL-capable role
docker run --rm -e DATABASE_URL='postgresql://<owner>:…@<host>:5432/<db>' \
  vaks-pm/api:$TAG sh -c 'cd /app/api && npx prisma db push --accept-data-loss'

4 · Changements de configuration ou de stack

• Fichier de stack / routage Traefik. Si docker-stack.gen.yml ou traefik-dynamic.gen.yml évoluent, régénérer (bash setup.sh --manifest infra/cluster.json) puis docker stack deploy --with-registry-auth -c out/docker-stack.gen.yml vaks-pm. La config dynamique de Traefik est une config Swarm immuable : incrémenter son suffixe de version (traefik_dynamic_v2 → v3) dans le fichier de stack avant de redéployer, sinon la nouvelle config est ignorée.
• Secrets. Les secrets Swarm sont immuables : pour faire tourner une valeur, créer un nouveau secret (nom versionné), le référencer dans le fichier de stack, puis docker stack deploy. Ne jamais supprimer une KEK qui enveloppe encore une DEK vivante (voir Trousseau de clés local).

5 · Vérifier après la montée de version

Confirmer que la nouvelle version est saine avant de considérer l'opération terminée :

docker stack ps vaks-pm                 # all tasks Running on the new image
docker service logs --since 5m vaks-pm_api | grep -Ei 'schema|prisma|error'   # schema applied cleanly

# liveness / readiness on a tenant hostname
curl -sk --resolve acme.vaks-pm.com:443:<manager-ip> https://acme.vaks-pm.com/api/v1/health/ready   # 200

• Toutes les tâches sont Running sur le nouveau tag ; aucune boucle de redémarrage sur l'api (le signe typique d'un push de schéma en échec).
• La connexion sur un tenant fonctionne et une page d'administration s'ouvre ; un envoi de pièce jointe réussit (exerce le chemin S3).

Voir aussi : Aperçu du produit · Architecture · Déployer sur Kubernetes · Sécurité · Exploitation · Session de démonstration