Docker Compose

Le fichier docker-compose.yml, à la racine du dépôt, décrit toute l'infrastructure de BlockLucky : les dépendances (PostgreSQL, Redis, Mailpit, nœud Hardhat) et, derrière le profil app, l'application complète (migrations, API, worker, frontend web, site de l'Office de Tourisme). Le projet Compose s'appelle blocklucky (clé name), ce qui préfixe les volumes et le réseau.

Cette page décrit le fichier tel qu'il est. Pour lancer la stack pas à pas, voir Stack complète en conteneurs ; pour le contenu des images, voir Images Docker.

#Services

#Profils

Compose ne démarre un service doté d'une clé profiles que si ce profil est demandé. Deux modes d'utilisation en découlent.

--wait fait attendre la commande jusqu'à ce que chaque service soit sain (ou terminé pour migrate). Le service blockchain n'a pas de profil : il démarre aussi en mode développement, car le backend fonctionne par défaut en BLOCKCHAIN_MODE=onchain (voir Mode onchain ou simulé).

#Ordre de démarrage

Les dépendances sont déclarées par depends_on avec une condition. Compose n'ouvre un service que lorsque la condition de chacune de ses dépendances est remplie.

flowchart LR
    PG["postgres (healthy)"] --> MIG["migrate (completed)"]
    MIG --> API["backend (healthy)"]
    MIG --> WK["worker"]
    RD["redis (healthy)"] --> API
    RD --> WK
    BC["blockchain (healthy)"] --> API
    BC --> WK
    API --> WEB["web"]
    TOU["tourisme"]
    MP["mailpit"]

• migrate attend que PostgreSQL réponde à pg_isready, applique les migrations et s'arrête (restart: "no"). Un échec de migration bloque donc le démarrage de l'API et du worker : c'est voulu, l'application ne doit jamais tourner sur un schéma incomplet.
• backend et worker attendent la fin réussie de migrate, un Redis sain et une blockchain saine. La blockchain n'est saine qu'une fois les contrats déployés (fichier témoin /tmp/blockchain-ready), ce qui peut prendre jusqu'à une minute au premier démarrage.
• web attend que l'API soit saine. Sa sonde utilise HEALTHCHECK du Dockerfile backend (/health/live).
• tourisme et mailpit n'ont aucune dépendance.

depends_on ne joue qu'au démarrage. Si Redis redémarre plus tard, l'API et le worker ne sont pas relancés automatiquement : voir Runbooks.

#Sondes de santé

La colonne Sonde du tableau précise si la sonde est écrite dans le fichier Compose ou héritée de l'instruction HEALTHCHECK du Dockerfile. La sonde du worker porte sur le petit serveur HTTP ouvert par backend/src/worker.ts sur PORT + 1, qui répond 503 pendant l'arrêt.

#Durcissement

L'ancre YAML x-hardening regroupe les options de sécurité appliquées par fusion (<<: *hardening) à migrate, backend, worker, web et tourisme :

x-hardening: &hardening
  read_only: true
  cap_drop: [ALL]
  security_opt: [no-new-privileges:true]
  tmpfs:
    - /tmp:size=64m

Le service web redéfinit tmpfs pour ajouter /app/.next/cache (128 Mo, propriétaire uid et gid 1000, c'est-à-dire l'utilisateur node) : le serveur Next.js y écrit le cache d'optimisation des images. Comme la clé tmpfs remplace celle de l'ancre au lieu de la compléter, /tmp y est répété.

Le service blockchain n'utilise pas l'ancre complète : il garde cap_drop et no-new-privileges, mais pas read_only, car Hardhat écrit dans /app (cache de compilation, deployments/localhost.json) et dans /tmp. Les services d'images tierces (postgres, redis, mailpit) ne sont pas durcis par Compose. Tous les conteneurs applicatifs tournent en outre sous un utilisateur non root défini dans leur image.

#Réseau

Un seul réseau, default, est déclaré avec un sous-réseau fixe :

networks:
  default:
    ipam:
      driver: default
      config:
        - subnet: 172.40.0.0/16

Les services se joignent par leur nom (postgres:5432, redis:6379, blockchain:8545, mailpit:1025). Le sous-réseau est fixé pour éviter qu'il chevauche un réseau local ou d'entreprise attribué automatiquement par Docker.

#Ports publiés sur l'hôte

Les ports de PostgreSQL et Redis sont décalés (5434, 6380) pour ne pas entrer en conflit avec une instance installée sur le poste. Les ports applicatifs sont ouverts sur toutes les interfaces pour qu'un téléphone du réseau local atteigne l'API pendant le développement.

#Volumes

Le script d'initialisation ne s'exécute qu'à la création du volume pgdata. Sur un volume plus ancien, l'extension se crée à la main (voir Runbooks).

La blockchain n'a pas de volume. docker compose down suivi de up repart d'une chaîne neuve, alors que PostgreSQL garde les tickets et le curseur d'indexation de l'ancienne. Pour repartir de zéro, supprimer aussi les volumes avec docker compose down -v. Le cas d'un redémarrage involontaire est traité dans Runbooks blockchain.

#Configuration de PostgreSQL et Redis

PostgreSQL est lancé avec ces paramètres, passés en ligne de commande :

Redis est lancé avec --appendonly yes --appendfsync everysec (au plus une seconde d'écritures perdues en cas de crash), --maxmemory 256mb --maxmemory-policy noeviction (Redis refuse les écritures plutôt que d'évincer une clé, donc un job BullMQ n'est jamais supprimé en silence) et --slowlog-log-slower-than 10000 (commandes de plus de 10 ms dans le slowlog).

#Variables passées au backend

L'ancre x-backend-env est partagée par backend et worker. Les valeurs sans ${...} sont écrites en dur dans le fichier ; les autres viennent de l'environnement du shell ou d'un fichier .env placé à la racine du dépôt, à côté de docker-compose.yml.

Le backend reçoit en plus RUN_WORKERS: "false". Toutes les autres variables prennent la valeur par défaut du schéma (voir Variables d'environnement) : notamment TRUST_PROXY=false, PORT=2053, AWS_S3_ENDPOINT=http://localhost:9000 (aucun service S3 n'est fourni, les envois échouent et sont journalisés en avertissement) et FALLBACK_RPC_URL vers un RPC public Sepolia.

#Secrets obligatoires

Avec NODE_ENV=production, le schéma de configuration refuse de démarrer si une valeur est absente ou égale à sa valeur de développement :

• JWT_SECRET : 16 caractères au moins ;
• ENCRYPTION_KEY : exactement 64 caractères hexadécimaux ;
• RELAYER_PRIVATE_KEY : clé privée 0x suivie de 64 caractères hexadécimaux, différente de la clé du compte Hardhat n° 0 ;
• WEBHOOK_SECRET : 8 caractères au moins ;
• METRICS_TOKEN : obligatoire tant que METRICS_ENABLED vaut true (valeur par défaut).

La substitution ${NOM:-} transmet une chaîne vide quand la variable manque. Une chaîne vide n'est pas « absente » pour Zod : la valeur par défaut ne s'applique pas et la validation échoue. Le conteneur s'arrête alors avec le message Configuration invalide, démarrage interrompu suivi de la liste des variables en cause. Un exemple de génération des valeurs :

cat > .env <<EOF
JWT_SECRET=$(openssl rand -hex 32)
ENCRYPTION_KEY=$(openssl rand -hex 32)
RELAYER_PRIVATE_KEY=0x$(openssl rand -hex 32)
WEBHOOK_SECRET=$(openssl rand -hex 24)
METRICS_TOKEN=$(openssl rand -hex 24)
EOF

#Service blockchain et compte opérateur

Le service blockchain est construit depuis smart-contract/Dockerfile et lance start-local-chain.sh, qui enchaîne :

1. npx hardhat node --hostname 0.0.0.0 --port 8545 en arrière-plan ;
2. une boucle qui interroge eth_chainId jusqu'à ce que le nœud réponde ;
3. npx hardhat run scripts/deploy-local.ts --network localhost, qui déploie VRFCoordinatorV2_5Mock, crée et finance un abonnement, déploie BlockLucky (tours de 30 minutes) et BlockLuckyPOAP, enregistre le contrat comme consommateur VRF, puis répartit les rôles (administrateur et propriétaire VRF au compte n° 2, trésorerie au compte n° 1, opérateur selon la clé reçue) ;
4. la création de /tmp/blockchain-ready, qui rend la sonde saine ;
5. scripts/local-vrf-responder.ts en arrière-plan : il surveille les événements RandomWordsRequested toutes les 2 secondes et répond avec le compte Hardhat n° 9.

Le service reçoit deux variables :

OPERATOR_PRIVATE_KEY est la même clé que RELAYER_PRIVATE_KEY côté backend. deploy-local.ts en déduit l'adresse, lui accorde OPERATOR_ROLE et PAUSER_ROLE sur BlockLucky, MINTER_ROLE sur BlockLuckyPOAP et, en local, DEFAULT_ADMIN_ROLE en administrateur additionnel pour setTreasury (sauf LOCAL_STRICT_ROLES=true). Si elle diffère du compte qui déploie (compte Hardhat n° 0, ce qui est le cas avec le profil app), le script lui envoie 1 000 ethers fictifs (OPERATOR_FUNDING_ETH) et retire tous ses rôles au compte n° 0. La répartition est faite par scripts/lib/roles.ts, commun au déploiement Sepolia. Sans cette habilitation, le keeper ne pourrait pas demander le tirage, le disjoncteur serait refusé et les badges ne seraient pas émis. Le rôle du compte opérateur est détaillé dans Client RPC et compte opérateur.

Les adresses des contrats sont déterministes : elles dépendent seulement du compte qui déploie et de son nonce. Les transactions de rôles sont envoyées après les deux déploiements et ne modifient pas ces adresses. Tant que l'ordre des transactions de deploy-local.ts ne change pas, BlockLucky est en 0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9 et BlockLuckyPOAP en 0x5FC8d32690cc91D4c39d9d3abcBD16989F875707, les valeurs écrites dans x-backend-env. Modifier le script de déploiement impose de vérifier ces adresses.

#Arrêt

backend et worker déclarent stop_grace_period: 30s. À docker compose stop, Docker envoie SIGTERM (le Dockerfile fixe STOPSIGNAL SIGTERM) et attend 30 secondes avant SIGKILL. Le backend ferme ses ressources dans l'ordre et se force à quitter après SHUTDOWN_TIMEOUT_MS (25 s par défaut), donc avant l'échéance de Docker. Le détail de la séquence est dans Observabilité.

#Valider le fichier

La CI vérifie la syntaxe et la résolution des ancres, profil app compris :

docker compose --profile app config -q

Sans -q, la commande affiche le fichier final fusionné, utile pour contrôler une surcharge.