Référence opérateur - installation standard d'un environnement HeyMoov

Note de répartition : ce document a été déplacé depuis heymoov-api vers heymoov-docs, car il décrit une procédure opérateur transverse. L'automation exécutable vit dans heymoov-platform.

Objet

Ce document fige la convention d'installation d'un environnement HeyMoov sur un serveur.

Il sert de référence pour:

• installer et bootstrapper un environnement dev, staging ou prod sur un host déjà provisionné
• installer toujours les mêmes répertoires, services et vhosts
• séparer clairement artefacts applicatifs et configuration sensible
• distinguer clairement installation, remplissage, vérification et activation

Il ne remplace pas la couche de provisioning du host.

Convention cible

Pour tout environnement nommé <env>:

• runtime applicatif: /opt/heymoov-<env>
• template versionné sans valeurs réelles: deploy/env/heymoov-runtime.env.template
• fichier d'environnement runtime: /etc/heymoov/heymoov-<env>.env
• service API: heymoov-<env>-apigo.service
• service cleaner Expo: heymoov-<env>-clean-expo-tokens.service
• timer cleaner Expo: heymoov-<env>-clean-expo-tokens.timer
• utilisateur systemd: gopher
• groupe systemd: devs
• groupe opérateur secrets/déploiement: heymoov-deploy
• binaire goose partagé: /usr/local/bin/heymoov-goose
• binaire Hydra provisionné: /opt/heymoov-platform/bin/hydra
• binaire Mercure provisionné: /opt/heymoov-platform/bin/mercure

Couche de provisioning host

Un environnement HeyMoov s'installe sur un serveur déjà provisionné. La source de vérité transverse du provisioning host est:

• heymoov-docs/reference/infra/heymoov-host-provisioning.md

Ce document conserve uniquement le contrat consommé par les scripts backend:

• Hydra courant: /opt/heymoov-platform/bin/hydra
• Mercure courant: /opt/heymoov-platform/bin/mercure

Les commandes bootstrap-hydra-env et bootstrap-mercure-env n'installent pas Hydra ou Mercure; elles configurent les services dédiés de l'environnement.

Pourquoi gopher:devs

Constat relevé en lecture seule sur ls2i-staging le 2026-04-21:

• gopher existe déjà comme compte technique avec shell nologin
• des services applicatifs historiques et heymoov tournent déjà sous gopher:devs
• les répertoires runtime historiques et heymoov sont déjà possédés majoritairement par gopher:devs

Interprétation retenue:

• gopher est le compte technique dédié à l'exécution des binaires Go
• devs est le groupe partagé avec les développeurs disposant d'un compte sur le serveur

La convention cible conserve donc gopher:devs.

Convention DNS et vhosts

La surface HTTP cible d'un environnement est:

• landing: https://<env-prefix>heymoov.com
• app web + BFF + uploads: https://app.<env-prefix>heymoov.com
• Hydra/OIDC: https://auth.<env-prefix>heymoov.com
• Mercure: https://mercure.<env-prefix>heymoov.com

Où:

• dev: <env-prefix> = dev.
• staging: <env-prefix> = staging.
• prod: <env-prefix> = chaîne vide

Important:

• aucun vhost api.<env>.heymoov.com n'entre dans la convention cible immédiate
• app.<env>.heymoov.com sert le front web, le BFF et les URLs /uploads/
• FRONTEND_DOCUMENT_URL doit donc viser https://app.<env-prefix>heymoov.com/uploads/

Inventaire et slots de ports

La topologie courante non secrète est versionnée dans:

• heymoov-platform/deploy/inventory/heymoov.envs

Les scripts génériques restent agnostiques au serveur cible. Ils résolvent:

• ENV: identité fonctionnelle (dev, staging, prod)
• HOST: serveur cible
• PORT_SLOT: slot réseau local sur ce serveur

La commande make topology-env ENV=<env> rend cette résolution visible avant exécution. HOST et PORT_SLOT restent surchargeables pour une opération ponctuelle, mais le chemin opérateur standard doit laisser l'inventaire les résoudre.

Convention des slots:

• primary: API 9196, readyz 127.0.0.1:18081, Hydra public/admin 4444/4445, Mercure 2022, Redis DB 0
• secondary: API 9197, readyz 127.0.0.1:18082, Hydra public/admin 4446/4447, Mercure 2023, Redis DB 1

Inventaire courant:

• dev: ls2i-staging, primary
• staging: ls2i-staging, secondary
• prod: ls2i-rdscrap, primary

Si staging est déplacé seul sur une autre VM, son HOST change et son PORT_SLOT peut repasser à primary sans modifier les scripts.

Arborescence cible

Runtime applicatif

Le répertoire /opt/heymoov-<env> doit contenir au minimum:

• assets/
• config/
• logs/
• templates/
• translations/
• uploads/
• heymoov-apiGo-linux
• heymoov-clean-expo-tokens-linux

Le fichier d'environnement runtime n'est pas stocké dans ce répertoire.

Configuration système

Le serveur doit contenir au minimum:

• /etc/heymoov/heymoov-dev.env
• /etc/heymoov/heymoov-staging.env
• /etc/heymoov/heymoov-prod.env
• /etc/heymoov/hydra-dev.env
• /etc/heymoov/hydra-staging.env
• /etc/heymoov/hydra-prod.env
• /etc/heymoov/mercure-dev.env
• /etc/heymoov/mercure-staging.env
• /etc/heymoov/mercure-prod.env

Règles:

• le template versionné est une trame uniquement, sans aucune valeur effective
• heymoov-<env>.env est créé depuis le template par install-env
• hydra-<env>.env est créé par le bootstrap storage quand la base Hydra est préparée
• mercure-<env>.env et mercure-<env>.Caddyfile sont créés par le bootstrap Mercure
• chaque fichier est propre à son environnement
• les secrets ne sont jamais embarqués dans les scripts ni commités

Séparation des phases

Le workflow cible est découpé en 8 étapes:

1. install

Cette étape installe tout ce qui peut l'être sans config sensible complète:

• répertoire runtime /opt/heymoov-<env>
• binaires
• assets, templates, traductions, uploads
• unités systemd
• éventuellement le runtime nginx, via une séquence edge dédiée séparée du runtime applicatif
• copie initiale du template vers /etc/heymoov/heymoov-<env>.env si le fichier n'existe pas déjà

2. bootstrap-storage

Cette étape prépare le stockage de l'environnement. Elle orchestre PostgreSQL et Redis:

• rôle + base applicative, par défaut heymoov_<env>_app et heymoov_<env>
• rôle + base Hydra, par défaut heymoov_<env>_hydra et heymoov_<env>_hydra
• extensions applicatives postgis, pg_trgm et btree_gist
• resserrage des privilèges PostgreSQL par défaut: retrait des droits PUBLIC sur postgres, template1, les bases dédiées et les schémas public, puis regrant minimal au rôle cible
• génération serveur des mots de passe absents ou encore en placeholder
• écriture de PGS_HOST, PGS_PORT, PGS_LOGIN, PGS_PASS et PGS_DB dans /etc/heymoov/heymoov-<env>.env
• écriture du DSN Hydra dans /etc/heymoov/hydra-<env>.env
• écriture de REDIS_ADDRESS et REDIS_DATABASE dans /etc/heymoov/heymoov-<env>.env
• vérification SELECT + PING du namespace Redis retenu

Les secrets générés ne doivent pas sortir du serveur et ne doivent pas être affichés.

Les briques bas niveau restent disponibles séparément:

• bootstrap-postgres-env pour PostgreSQL uniquement
• bootstrap-redis-env pour Redis uniquement

3. bootstrap-runtime

Cette étape complète les valeurs runtime qui sont dérivables ou générables localement:

• HTTP_ADDR et READYZ_ADDR
• URLs publiques et internes Hydra
• callbacks Hydra
• URLs Mercure et préfixe de topics
• domaine cookie, CORS cible, URLs frontend
• secrets runtime locaux: clés JWT, peppers, keyring applicatif Hydra, secret client web Hydra, clés JWT Mercure

Les secrets générés ne doivent pas sortir du serveur et les valeurs finales déjà présentes sont conservées, sauf rotation explicite.

4. bootstrap-hydra

Cette étape configure ou met à jour le daemon Hydra dédié de l'environnement. Elle requiert un binaire Hydra déjà provisionné sur le host:

• /opt/heymoov-platform/bin/hydra

Elle effectue:

• lecture de /etc/heymoov/heymoov-<env>.env pour les URLs, ports et callbacks
• lecture de /etc/heymoov/hydra-<env>.env pour le DSN PostgreSQL Hydra
• génération des secrets propres au daemon Hydra s'ils sont absents
• écriture des variables Hydra serveur dans /etc/heymoov/hydra-<env>.env
• exécution des migrations Hydra
• installation et activation de heymoov-<env>-hydra.service

Elle n'installe pas le binaire Hydra lui-même.

Les clients OAuth2 restent gérés par l'étape séparée bootstrap-hydra-clients, une fois le daemon Hydra joignable.

5. bootstrap-mercure

Cette étape configure ou met à jour le daemon Mercure dédié de l'environnement. Elle requiert un binaire Mercure/Caddy déjà provisionné sur le host:

• /opt/heymoov-platform/bin/mercure

Elle effectue:

• lecture de /etc/heymoov/heymoov-<env>.env pour les clés JWT Mercure et les origins frontend à autoriser
• écriture de /etc/heymoov/mercure-<env>.env avec les variables du daemon
• écriture de /etc/heymoov/mercure-<env>.Caddyfile
• installation et activation de heymoov-<env>-mercure.service
• exposition locale du hub sur le port Mercure du PORT_SLOT
• vérification locale de /healthz

Elle n'installe pas le binaire Mercure/Caddy lui-même.

Le fichier daemon Mercure reprend les clés publisher/subscriber du fichier runtime applicatif. Ces secrets restent sur le serveur.

Particularité cible:

• dev doit aussi autoriser l'origine subscriber http://localhost:3006 pour le front web local
• staging et prod restent limités à leur origin applicative publique

6. fill

Cette étape reste manuelle pour les valeurs non dérivées du bootstrap:

• l'opérateur complète /etc/heymoov/heymoov-<env>.env
• tous les placeholders __REQUIRED_*__ doivent disparaître
• les valeurs réelles ne sont jamais commitées

7. verify

Cette étape contrôle avant démarrage:

• présence du fichier /etc/heymoov/heymoov-<env>.env
• absence de placeholders restants
• présence des variables obligatoires
• cohérence minimale des URLs, callbacks Hydra, cookie domain et hostname Turnstile
• cohérence live de l'issuer OIDC exposé par Hydra sur le port interne du PORT_SLOT
• cohérence live du hub Mercure sur le port interne du PORT_SLOT, avec /healthz et preflight CORS depuis l'app du même environnement
• présence et forme attendue des clients Hydra web/mobile

8. activate

Cette étape effectue le basculement runtime:

• vérification du runtime après la séquence edge
• démarrage des services systemd
• activation du timer cleaner Expo

Interface opérateur visée

L'interface cible privilégie:

• make comme façade opérateur courte
• des scripts idempotents comme implémentation réelle

Exemples de cibles visées:

• make topology-env ENV=dev
• make topology-env ENV=dev FORMAT=json
• make topology-env ENV=dev CHECK=1
• make install-env ENV=dev
• make bootstrap-storage-env ENV=dev
• make bootstrap-runtime-env ENV=dev
• make bootstrap-hydra-env ENV=dev
• make bootstrap-mercure-env ENV=dev
• make bootstrap-hydra-clients ENV=dev
• make verify-env ENV=dev
• make activate-env ENV=dev

Principes:

• le Makefile ne porte pas toute la logique métier
• les scripts portent les étapes détaillées d'installation, vérification et activation
• les scripts restent réutilisables sans make si besoin
• les chemins des binaires plateforme viennent de la topologie/provisioning cible et restent surchargeables explicitement par HYDRA_BIN et MERCURE_BIN pour une opération ponctuelle

Scripts actuellement exposés:

• heymoov-platform/scripts/install_environment.sh
• heymoov-platform/scripts/heymoov_env_common.sh
• heymoov-platform/scripts/bootstrap_storage_environment.sh
• heymoov-platform/scripts/bootstrap_postgres_environment.sh
• heymoov-platform/scripts/bootstrap_redis_environment.sh
• heymoov-platform/scripts/bootstrap_runtime_environment.sh
• heymoov-platform/scripts/bootstrap_hydra_environment.sh
• heymoov-platform/scripts/bootstrap_mercure_environment.sh
• heymoov-platform/scripts/verify_environment.sh
• heymoov-platform/scripts/activate_environment.sh
• heymoov-platform/scripts/bootstrap_hydra_clients.sh
• heymoov-platform/scripts/verify_edge_dns.sh
• heymoov-platform/scripts/render_edge_nginx_vhosts.sh
• heymoov-platform/scripts/install_edge_nginx_vhosts.sh
• heymoov-platform/scripts/issue_edge_certs.sh

État actuel du repository

Le repository automatise maintenant:

• la création de l'arborescence runtime /opt/heymoov-<env>
• la copie initiale du template runtime vers /etc/heymoov/heymoov-<env>.env si le fichier n'existe pas déjà
• le bootstrap storage local de l'environnement, avec PostgreSQL, Redis, génération serveur des secrets DB et mise à jour des fichiers /etc/heymoov
• le bootstrap runtime de l'environnement, avec génération serveur des secrets applicatifs locaux et conventions d'URLs/ports
• le bootstrap du daemon Hydra dédié, avec génération des secrets Hydra serveur, migrations Hydra et unité systemd
• la compilation et la copie des binaires applicatifs
• la synchronisation assets, templates/mail et translations
• l'installation des unités systemd
• le bootstrap des clients Hydra web/mobile depuis le fichier runtime
• la vérification de cohérence du runtime et du fichier d'environnement
• l'activation applicative via nginx reload, restart API et activation du timer cleaner

Limite actuelle:

• les surfaces nginx de heymoov-dev et heymoov-staging sont versionnées
• heymoov-prod reste à versionner côté edge

Ce qui requiert des secrets

Runtime applicatif

Le contenu de /opt/heymoov-<env> n'a pas besoin de secrets applicatifs.

Il peut être installé avant remplissage du fichier runtime.

systemd

Les unités systemd n'ont pas besoin de contenir les secrets.

Elles ont seulement besoin de référencer:

• WorkingDirectory=/opt/heymoov-<env>
• EnvironmentFile=/etc/heymoov/heymoov-<env>.env

Migrations de release

La phase 1 de déploiement retient un modèle où les migrations sont commandées depuis le poste opérateur, mais exécutées sur le serveur cible.

Objectifs:

• utiliser /etc/heymoov/heymoov-<env>.env comme source de vérité unique
• ne plus dépendre d'une copie locale .env.heymoov-* pour les releases
• ne plus ouvrir de tunnel PostgreSQL pour le flux standard de release
• ne pas faire sortir PGS_PASS du serveur

Le serveur doit donc disposer de:

• /usr/local/bin/heymoov-goose, version pilotée par le repository
• /opt/heymoov-<env>/migrations, synchronisé uniquement avec les migrations exécutables (*.sql, et *.go si un jour utilisé)
• un fichier /etc/heymoov/heymoov-<env>.env lisible par les opérateurs autorisés via le groupe heymoov-deploy

Le mot de passe DB ne doit pas être passé en argument de commande. Le runner serveur doit construire GOOSE_DRIVER et GOOSE_DBSTRING dans l'environnement du process heymoov-goose, sans journaliser la chaîne de connexion.

Bootstrap PostgreSQL

La création des rôles, bases et credentials PostgreSQL est distincte des migrations applicatives.

Le mécanisme retenu en phase 1 est:

• le bootstrap s'exécute sur le serveur cible via SSH et sudo
• il utilise le superuser PostgreSQL local postgres
• il génère les secrets DB absents ou encore en placeholder sur le serveur
• il crée ou met à jour le rôle applicatif et la base applicative
• il crée ou met à jour le rôle Hydra et la base Hydra
• il retire les droits PUBLIC inutiles sur postgres, template1, les bases dédiées et les schémas public, puis regrant les droits minimaux au rôle de l'environnement
• il écrit les credentials applicatifs dans /etc/heymoov/heymoov-<env>.env
• il écrit le DSN Hydra dans /etc/heymoov/hydra-<env>.env
• il repose les permissions root:heymoov-deploy 0640

Le script ne doit pas afficher les secrets, ne doit pas les passer en argument de commande et ne doit pas les stocker dans un fichier temporaire lisible. La mise à jour du mot de passe PostgreSQL est exécutée dans une session qui désactive au mieux le logging de statement avant l'ALTER ROLE.

La rotation explicite reste une action opérateur séparée:

• ROTATE_APP_PASSWORD=1
• ROTATE_HYDRA_PASSWORD=1

Sans rotation explicite, un secret final déjà présent dans les fichiers /etc/heymoov est réutilisé.

Bootstrap storage

Le bootstrap storage prépare les dépendances de stockage de l'environnement.

Le mécanisme retenu en phase 1 est:

• le bootstrap s'exécute sur le serveur cible via SSH et sudo
• il lance le bootstrap PostgreSQL pour les bases applicative et Hydra
• il lance le bootstrap Redis pour le namespace de l'environnement
• il conserve les valeurs finales déjà présentes
• il remplace les placeholders et valeurs absentes par les conventions de l'environnement
• il génère les secrets PostgreSQL absents ou encore en placeholder
• il vérifie la connexion Redis sur REDIS_ADDRESS et REDIS_DATABASE
• il repose les permissions root:heymoov-deploy 0640

Les valeurs remplies par ce bootstrap incluent notamment:

• PGS_HOST, PGS_PORT, PGS_LOGIN, PGS_PASS, PGS_DB
• HYDRA_PGS_HOST, HYDRA_PGS_PORT, HYDRA_PGS_LOGIN, HYDRA_PGS_PASS, HYDRA_PGS_DB, DSN
• REDIS_ADDRESS, REDIS_DATABASE

La rotation explicite des secrets PostgreSQL reste une action opérateur séparée:

• ROTATE_APP_PASSWORD=1
• ROTATE_HYDRA_PASSWORD=1

Le check Redis peut être ignoré temporairement avec SKIP_STORAGE_REDIS_CHECK=1, mais ce ne doit pas être l'état d'activation normal.

Bootstrap runtime

Le bootstrap runtime complète le fichier /etc/heymoov/heymoov-<env>.env avec les valeurs applicatives que l'opérateur ne doit pas recopier à la main.

Le mécanisme retenu en phase 1 est:

• le bootstrap s'exécute sur le serveur cible via SSH et sudo
• il conserve les valeurs finales déjà présentes
• il remplace les placeholders et valeurs absentes par les conventions de l'environnement
• il génère les secrets locaux absents ou encore en placeholder
• il repose les permissions root:heymoov-deploy 0640

Les valeurs remplies par ce bootstrap incluent notamment:

• APP_ENV, HTTP_ADDR, READYZ_ADDR
• AUTH_COOKIE_DOMAIN, CORS_ALLOWED_ORIGINS_WEB
• HYDRA_ADMIN_URL, HYDRA_PUBLIC_URL, HYDRA_INTERNAL_URL, callbacks et client IDs
• MERCURE_URL, MERCURE_TOPICS_PREFIX
• FRONTEND_DOCUMENT_URL, FRONTEND_SHOWCASE_URL, FRONTEND_APP_URL
• les secrets JWT, peppers, keyring applicatif Hydra, secret client web Hydra et clés JWT Mercure

CORS_ALLOWED_ORIGINS_WEB_DEV est rempli uniquement pour APP_ENV=dev, car les surfaces CORS de développement ne sont pas montées en staging ni en prod. JWT_LEGACY_HS256_KEY suit la même logique: il n'est rempli que pour APP_ENV=dev, où il signe encore les tokens de la surface /v1/dev/legacy/*.

La rotation explicite des secrets générés reste une action opérateur séparée:

• ROTATE_GENERATED_SECRETS=1

Bootstrap Hydra daemon

Le bootstrap Hydra configure le daemon OIDC dédié de l'environnement.

Il suppose que le binaire Hydra a déjà été provisionné par Ansible sous:

• /opt/heymoov-platform/bin/hydra

Le mécanisme retenu en phase 1 est:

• le bootstrap s'exécute sur le serveur cible via SSH et sudo
• il lit /etc/heymoov/heymoov-<env>.env pour HYDRA_ADMIN_URL, HYDRA_INTERNAL_URL, HYDRA_OIDC_ISSUER_URL et FRONTEND_APP_URL
• il lit /etc/heymoov/hydra-<env>.env pour le DSN PostgreSQL généré par le bootstrap storage
• il conserve les secrets Hydra daemon déjà présents
• il génère SECRETS_SYSTEM, SECRETS_COOKIE et OIDC_SUBJECT_IDENTIFIERS_PAIRWISE_SALT si nécessaire
• il renseigne les ports SERVE_PUBLIC_* et SERVE_ADMIN_* à partir des URLs internes runtime
• il lance hydra migrate sql -e --yes sans passer le DSN en argument de commande
• il installe heymoov-<env>-hydra.service, recharge systemd, puis active/redémarre le service

Il ne télécharge pas et n'installe pas le binaire Hydra.

Les valeurs remplies dans /etc/heymoov/hydra-<env>.env incluent notamment:

• SECRETS_SYSTEM, SECRETS_COOKIE
• URLS_SELF_ISSUER, URLS_LOGIN, URLS_CONSENT
• SERVE_PUBLIC_HOST, SERVE_PUBLIC_PORT
• SERVE_ADMIN_HOST, SERVE_ADMIN_PORT
• OIDC_SUBJECT_IDENTIFIERS_SUPPORTED_TYPES, OIDC_SUBJECT_IDENTIFIERS_PAIRWISE_SALT
• LOG_LEVEL

La rotation explicite des secrets du daemon Hydra reste une action opérateur séparée:

• ROTATE_HYDRA_DAEMON_SECRETS=1

Les migrations ou le redémarrage peuvent être ignorés temporairement avec:

• SKIP_HYDRA_MIGRATE=1
• SKIP_HYDRA_RESTART=1

nginx

nginx n'a pas besoin des secrets applicatifs du backend.

Il a seulement besoin:

• de ses vhosts
• de ses certificats TLS et clés privées, gérés séparément de la configuration applicative
• d'un webroot ACME technique, ici /var/www/heymoov-<env>-acme

Activation de l'environnement

Le démarrage effectif de l'API requiert:

• un fichier /etc/heymoov/heymoov-<env>.env complet et cohérent
• les clients Hydra déjà créés
• les certificats TLS disponibles
• la résolution DNS fonctionnelle sur app, auth et mercure

Règles de permissions

Pour le runtime applicatif:

• propriétaire: gopher
• groupe: devs

Pour le fichier d'environnement runtime:

• propriétaire: root
• groupe: heymoov-deploy
• droits recommandés: 0640

Pour le répertoire de configuration /etc/heymoov:

• propriétaire: root
• groupe: heymoov-deploy
• droits recommandés: 0751

Justification: le bit de traversal o+x permet au process Mercure gopher de lire son Caddyfile public, tout en gardant les fichiers sensibles protégés par leurs modes fichiers.

Pour heymoov-goose:

• chemin: /usr/local/bin/heymoov-goose
• propriétaire: root
• groupe: root
• droits recommandés: 0755

Pour les migrations synchronisées par environnement:

• répertoire: /opt/heymoov-<env>/migrations
• propriétaire: gopher
• groupe: devs
• droits recommandés: 0770
• fichiers: 0660

Justification:

• les binaires et répertoires applicatifs doivent être exploités par le compte de service
• le fichier de secrets doit être lisible par systemd et par les opérateurs autorisés aux migrations
• le compte runtime gopher n'a pas besoin de lire directement /etc/heymoov/heymoov-<env>.env; c'est systemd qui charge EnvironmentFile=
• les secrets ne doivent pas être lisibles par tout le groupe devs

Prérequis par environnement

Avant toute activation d'un environnement, il faut disposer de:

• la base PostgreSQL cible
• la base PostgreSQL Hydra cible
• le Redis cible ou le namespace Redis cible
• le daemon Hydra dédié du même environnement
• le daemon Mercure dédié du même environnement
• les clients Hydra du même environnement
• le fichier /etc/heymoov/heymoov-<env>.env
• les enregistrements DNS landing, app, auth et mercure
• les certificats TLS correspondants
• les vhosts nginx installés dans leur mode final

Ordre d'installation recommandé

1. Vérifier le host provisionné

• vérifier la présence du compte gopher
• vérifier la présence du groupe devs
• vérifier la présence du groupe heymoov-deploy
• ajouter uniquement les comptes opérateurs autorisés au groupe heymoov-deploy
• créer /opt/heymoov-<env>
• créer /etc/heymoov
• installer ou vérifier /usr/local/bin/heymoov-goose
• vérifier que le package manager a installé PostgreSQL, Redis, Nginx, Certbot et les prérequis système
• vérifier que Hydra est provisionné sous /opt/heymoov-platform/bin/hydra
• vérifier que Mercure est provisionné sous /opt/heymoov-platform/bin/mercure

2. Installer la trame de configuration

• copier le template versionné vers /etc/heymoov/heymoov-<env>.env si le fichier n'existe pas déjà
• vérifier les permissions root:heymoov-deploy 0640

3. Bootstrap storage

• lancer make bootstrap-storage-env ENV=<env>
• vérifier que PGS_* a été renseigné dans /etc/heymoov/heymoov-<env>.env
• vérifier que /etc/heymoov/hydra-<env>.env a été créé pour le futur service Hydra
• vérifier que REDIS_ADDRESS et REDIS_DATABASE ont été renseignés
• vérifier que Redis est joignable sur le namespace retenu
• ne pas afficher ni recopier les secrets générés

4. Bootstrap runtime

• lancer make bootstrap-runtime-env ENV=<env>
• vérifier que SWAGGER_ENABLED=1 pour dev et staging
• vérifier que SWAGGER_ENABLED=0 pour prod
• vérifier que les secrets générés restent uniquement sur le serveur

5. Bootstrap Hydra

• lancer make bootstrap-hydra-env ENV=<env>
• vérifier que heymoov-<env>-hydra.service est installé et actif
• vérifier que /etc/heymoov/hydra-<env>.env contient les variables serveur Hydra
• ne pas afficher ni recopier les secrets générés

6. Bootstrap Mercure

• lancer make bootstrap-mercure-env ENV=<env>
• vérifier que heymoov-<env>-mercure.service est installé et actif
• vérifier que /etc/heymoov/mercure-<env>.env et /etc/heymoov/mercure-<env>.Caddyfile existent
• vérifier que le hub répond localement sur le port Mercure du slot retenu
• ne pas afficher ni recopier les secrets générés

7. Compléter la configuration runtime

• compléter manuellement les valeurs restantes dans /etc/heymoov/heymoov-<env>.env
• vérifier que les URLs pointent vers app, auth et mercure sous heymoov.com

8. Installer le runtime applicatif

• déposer les binaires
• synchroniser assets, config, templates, translations, uploads
• appliquer gopher:devs sur le runtime

9. Installer systemd

• installer heymoov-<env>-apigo.service
• installer heymoov-<env>-clean-expo-tokens.service
• installer heymoov-<env>-clean-expo-tokens.timer
• vérifier que chaque unité pointe vers:
• WorkingDirectory=/opt/heymoov-<env>
• EnvironmentFile=/etc/heymoov/heymoov-<env>.env
• User=gopher
• Group=devs

10. Bootstrap clients Hydra

• lancer make bootstrap-hydra-clients ENV=<env>
• vérifier que les clients web/mobile existent dans l'admin API Hydra du même environnement
• créer ou mettre à jour le client web heymoov-<env>-web
• créer ou mettre à jour le client mobile heymoov-<env>-mobile
• relire les callbacks depuis /etc/heymoov/heymoov-<env>.env
• vérifier que la metadata OIDC Hydra expose l'issuer public attendu
• vérifier que Mercure répond à /healthz et autorise le CORS de https://app.<env>.heymoov.com

11. Installer nginx

• vérifier le DNS landing, app, auth et mercure
• pour dev et staging, lancer make bootstrap-swagger-basic-auth-env ENV=<env> avant d'activer les vhosts
• installer l'edge en mode http-only
• activer l'edge HTTP puis tester nginx
• émettre les certificats TLS via certbot
• installer l'edge en mode tls
• réactiver l'edge final puis tester nginx

Exemples pour heymoov-dev:

• make verify-edge-dns-heymoov-dev
• make bootstrap-swagger-basic-auth-heymoov-dev
• make install-edge-nginx-vhosts-heymoov-dev EDGE_MODE=http-only
• make enable-edge-nginx-vhosts-heymoov-dev EDGE_MODE=http-only
• make issue-edge-certs-heymoov-dev
• make install-edge-nginx-vhosts-heymoov-dev EDGE_MODE=tls
• make enable-edge-nginx-vhosts-heymoov-dev EDGE_MODE=tls
• make bootstrap-mercure-heymoov-dev
• make bootstrap-hydra-clients-heymoov-dev

Le Basic Auth Swagger utilise par défaut:

• fichier htpasswd nginx: /etc/nginx/heymoov-swagger.htpasswd
• secret opérateur: /etc/heymoov/secrets/heymoov-<env>-swagger-basic-auth.password
• utilisateur: heymoov-<env>-docs

Le password n'est affiché que sur demande explicite via make show-swagger-basic-auth-env ENV=<env>.

12. Activer l'environnement

• vérifier que le fichier runtime ne contient plus de placeholder __REQUIRED_*__
• vérifier que l'edge TLS est déjà en place
• démarrer les services systemd
• activer le timer cleaner Expo

13. Release applicative standard

Pour les releases courantes, le poste opérateur orchestre mais la migration est exécutée sur le serveur:

1. compiler localement le binaire avec GOCACHE=/tmp/heymoov-api-gocache
2. synchroniser le binaire .new
3. synchroniser uniquement les migrations exécutables vers /opt/heymoov-<env>/migrations
4. lancer heymoov-goose sur le serveur avec les variables DB lues depuis /etc/heymoov/heymoov-<env>.env
5. synchroniser assets, templates/mail et translations
6. remplacer atomiquement le binaire actif
7. redémarrer le service systemd
8. vérifier readyz

Pour prod, la commande de release doit exiger une confirmation explicite avant toute synchronisation, migration ou relance.

14. Valider

• vérifier l'accessibilité de app.<env>.heymoov.com
• vérifier la disponibilité de l'issuer OIDC auth.<env>.heymoov.com
• vérifier les cookies et le login web
• vérifier /uploads/ sur app.<env>.heymoov.com
• vérifier Mercure

Phase 2 - Credentials systemd

La phase 1 conserve temporairement les secrets dans /etc/heymoov/heymoov-<env>.env, protégés par root:heymoov-deploy 0640.

La phase 2 cible un modèle plus strict:

• conserver dans EnvironmentFile= uniquement la configuration non sensible
• déplacer PGS_PASS, les clés JWT, les secrets Hydra, les secrets Mercure et les secrets providers vers LoadCredential= ou LoadCredentialEncrypted=
• adapter le bootstrap Go pour lire les secrets depuis $CREDENTIALS_DIRECTORY
• adapter le runner de migrations pour être lancé via systemd-run ou une unité dédiée chargeant les mêmes credentials
• vérifier que les secrets ne sont jamais exposés en arguments de commande, logs ou fichiers temporaires

Cette phase implique des changements applicatifs et systemd plus larges que la simple correction du workflow de release.

Ce que la convention ne fait pas

Cette convention:

• ne provisionne pas une VM ni le socle host
• ne conserve pas de vhost api.* par inertie historique
• ne stocke pas de secrets dans le repository
• ne dépend pas d'un répertoire runtime historique
• ne télécharge pas Hydra ou Mercure depuis les bootstraps applicatifs
• ne fait pas du legacy historique une convention supportée