Référence opérateur - trame heymoov-staging.env

Note de répartition : ce document a été déplacé depuis heymoov-api vers heymoov-docs, car il décrit une trame opérateur transverse. Les valeurs effectives restent hors Git et l'automation exécutable vit dans heymoov-platform.

Objet

Ce document sert de trame opérateur pour préparer le fichier runtime heymoov-staging.

Il ne contient aucun secret versionné. Les secrets déjà présents sur le serveur sont conservés; lors d'une première installation ils sont générés hors Git par les bootstraps. Les credentials PostgreSQL de l'environnement doivent être générés sur le serveur par le bootstrap storage, puis stockés directement dans les fichiers /etc/heymoov.

Source de vérité utilisée

Source de configuration cible:

• cible de migration: /etc/heymoov/heymoov-staging.env
• runtime applicatif: /opt/heymoov-staging
• topologie non secrète: heymoov-platform/deploy/inventory/heymoov.envs
• surface publique: ligne staging de heymoov-runtime-target.md

Important:

• heymoov-staging doit être distinct de heymoov-dev
• la base, Redis, Hydra, Mercure, les clients OAuth2 et les uploads ne doivent pas être partagés avec dev
• les valeurs réelles du runtime ne doivent pas être commitées dans le repository
• le service doit charger ce fichier via EnvironmentFile=
• le répertoire /opt/heymoov-staging n'est pas l'emplacement cible des secrets
• les releases et migrations doivent utiliser ce fichier serveur comme source de vérité, sans copie locale .env.heymoov-staging
• les credentials applicatifs PostgreSQL sont écrits dans ce fichier par bootstrap-storage-env
• les credentials PostgreSQL du stockage Hydra sont écrits dans /etc/heymoov/hydra-staging.env
• le namespace Redis est écrit dans ce fichier par bootstrap-storage-env
• la configuration daemon Mercure est écrite dans /etc/heymoov/mercure-staging.env et /etc/heymoov/mercure-staging.Caddyfile

Règles de préparation

La préparation de heymoov-staging.env se fait à partir de la trame versionnée:

• heymoov-platform/deploy/env/heymoov-runtime.env.template

Le repository ne versionne aucune valeur effective du runtime staging.

Valeurs dérivées de la convention cible heymoov-staging

Les variables suivantes sont renseignées par make bootstrap-runtime-env ENV=staging. Le HOST et le PORT_SLOT sont résolus depuis l'inventaire heymoov-platform/deploy/inventory/heymoov.envs, qui place actuellement staging sur ls2i-staging en slot secondary.

• APP_NAME=HeyMoov
• APP_ENV=staging
• HTTP_ADDR=127.0.0.1:9197
• READYZ_ADDR=127.0.0.1:18082
• CORS_ALLOWED_ORIGINS_WEB=https://app.staging.heymoov.com
• SWAGGER_ENABLED=1
• AUTH_COOKIE_DOMAIN=staging.heymoov.com
• HYDRA_ADMIN_URL=http://127.0.0.1:4447
• HYDRA_PUBLIC_URL=https://auth.staging.heymoov.com
• HYDRA_INTERNAL_URL=http://127.0.0.1:4446
• HYDRA_OIDC_ISSUER_URL=https://auth.staging.heymoov.com
• HYDRA_CALLBACK_URL=https://app.staging.heymoov.com/v1/web/auth/callback
• HYDRA_MOBILE_CALLBACK_URL=https://app.staging.heymoov.com/v1/mobile/auth/callback
• HYDRA_FRONTEND_CALLBACK_URL=https://app.staging.heymoov.com/fr/auth/callback
• HYDRA_MOBILE_APP_RETURN_URL=heymoov://mobile/auth/complete
• MOBILE_WEBAUTHN_RP_ID=auth.staging.heymoov.com
• MOBILE_WEBAUTHN_RP_DISPLAY_NAME=HeyMoov
• MOBILE_WEBAUTHN_CHALLENGE_TTL=5m
• MOBILE_WEBAUTHN_ALLOWED_ORIGINS=https://auth.staging.heymoov.com comme valeur minimale; l'opérateur devra compléter avec les origins iOS/Android staging
• MERCURE_URL=https://mercure.staging.heymoov.com
• MERCURE_TOPICS_PREFIX=https://app.staging.heymoov.com/
• MERCURE_COOKIE_DURATION=60
• FRONTEND_DOCUMENT_URL=https://app.staging.heymoov.com/uploads/
• FRONTEND_SHOWCASE_URL=https://staging.heymoov.com
• FRONTEND_APP_URL=https://app.staging.heymoov.com
• MAX_UPLOAD_FILESIZE=500
• TURNSTILE_EXPECTED_HOSTNAME=app.staging.heymoov.com

Le slot secondary est lié à la colocalisation actuelle de dev et staging sur ls2i-staging. Si staging est déplacé seul sur une autre VM, il pourra utiliser PORT_SLOT=primary et donc les ports standards 9196, 18081 et 4444/4445, avec Mercure sur 2022.

Secrets renseignés par le bootstrap runtime

Ces valeurs sont générées sur le serveur par make bootstrap-runtime-env ENV=staging si elles sont absentes ou encore en placeholder:

• WEB_UI_JWT_HS256_KEY
• SECRET_PEPPER
• TOKEN_PEPPER
• HYDRA_ENCRYPTION_KEYS
• HYDRA_ENCRYPTION_KEY_CURRENT
• HYDRA_STATE_COOKIE_KEY
• HYDRA_CLIENT_SECRETS
• MERCURE_PUBLISHER_JWT_KEY
• MERCURE_SUBSCRIBER_JWT_KEY

Sans ROTATE_GENERATED_SECRETS=1, les secrets finaux déjà présents sont conservés.

Valeurs renseignées par le bootstrap storage

Ces variables sont renseignées par make bootstrap-storage-env ENV=staging.

Le bootstrap storage orchestre les deux briques bas niveau:

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

Par défaut, le bootstrap retient:

• rôle applicatif: heymoov_staging_app
• base applicative: heymoov_staging
• rôle Hydra: heymoov_staging_hydra
• base Hydra: heymoov_staging_hydra
• Redis: 127.0.0.1:6379, base 1 car staging utilise le slot secondary

Dans /etc/heymoov/heymoov-staging.env, il renseigne:

• PGS_HOST
• PGS_PORT
• PGS_LOGIN
• PGS_PASS
• PGS_DB
• REDIS_ADDRESS=127.0.0.1:6379
• REDIS_DATABASE=1

Dans /etc/heymoov/hydra-staging.env, il renseigne:

• HYDRA_PGS_HOST
• HYDRA_PGS_PORT
• HYDRA_PGS_LOGIN
• HYDRA_PGS_PASS
• HYDRA_PGS_DB
• DSN

Les mots de passe sont générés sur le serveur si les valeurs sont absentes ou encore en placeholder. Ils ne doivent pas être recopiés depuis le poste opérateur.

Valeurs renseignées par le bootstrap Hydra daemon

Ces variables sont renseignées par make bootstrap-hydra-env ENV=staging dans /etc/heymoov/hydra-staging.env.

Avec le slot secondary courant, le bootstrap retient:

• service systemd: heymoov-staging-hydra.service
• public interne Hydra: 127.0.0.1:4446
• admin Hydra: 127.0.0.1:4447
• issuer OIDC: https://auth.staging.heymoov.com
• login Hydra: https://app.staging.heymoov.com/v1/web/auth/login
• consent Hydra: https://app.staging.heymoov.com/v1/web/auth/consent

Il renseigne ou conserve:

• 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

Ces secrets appartiennent au daemon Hydra. Ils ne doivent pas être recopiés dans le fichier runtime applicatif ni dans le repository.

Valeurs renseignées par le bootstrap Mercure daemon

Ces variables sont renseignées par make bootstrap-mercure-env ENV=staging dans /etc/heymoov/mercure-staging.env.

Avec le slot secondary courant, le bootstrap retient:

• service systemd: heymoov-staging-mercure.service
• Caddyfile: /etc/heymoov/mercure-staging.Caddyfile
• data dir: /var/lib/heymoov-mercure/staging
• URL interne Mercure: http://127.0.0.1:2023/.well-known/mercure
• URL publique Mercure: https://mercure.staging.heymoov.com
• origin CORS/publish: https://app.staging.heymoov.com

Il renseigne le daemon à partir des secrets déjà présents dans /etc/heymoov/heymoov-staging.env:

• MERCURE_PUBLISHER_JWT_KEY
• MERCURE_SUBSCRIBER_JWT_KEY
• MERCURE_PUBLISHER_JWT_ALG=HS256
• MERCURE_SUBSCRIBER_JWT_ALG=HS256
• MERCURE_SERVER_NAME=http://127.0.0.1:2023
• MERCURE_CORS_ORIGINS=https://app.staging.heymoov.com
• MERCURE_PUBLISH_ORIGINS=https://app.staging.heymoov.com

Les clés publisher/subscriber doivent rester identiques entre le runtime applicatif et le daemon Mercure. Elles ne doivent pas être recopiées dans le repository.

Valeurs à reprendre depuis une source opérateur

Ces variables doivent être reprises depuis l'environnement courant ou une source opérateur de confiance, mais ne doivent pas être écrites dans le repository:

• MOBILE_WEBAUTHN_ALLOWED_ORIGINS doit être complétée avec les origins iOS/Android staging si la valeur minimale posée par le bootstrap ne suffit pas
• EMAIL_NOREPLY
• EMAIL_CONTACT
• EMAIL_PROVIDER
• SIB_API_KEY quand EMAIL_PROVIDER=BREVO
• TURNSTILE_TIMEOUT
• TURNSTILE_MAX_CHALLENGE_AGE

Valeurs à figer explicitement pour staging

La convention retenue pour heymoov-staging est:

• APP_ENV=staging
• EMAIL_PROVIDER=BREVO
• HYDRA_WEB_CLIENT_ID=heymoov-staging-web
• HYDRA_MOBILE_CLIENT_ID=heymoov-staging-mobile

Convention attendue:

• heymoov-staging-web est un client confidentiel en client_secret_post
• heymoov-staging-mobile est un client public PKCE en token_endpoint_auth_method=none
• en conséquence, HYDRA_CLIENT_SECRETS n'a besoin de contenir que le secret du client web

Secrets à fournir ou régénérer hors Git

Ces valeurs doivent être reprises depuis l'existant ou régénérées, mais jamais commitées:

• SIB_API_KEY si EMAIL_PROVIDER=BREVO
• TURNSTILE_SECRET_KEY
• REDIS_PASSWORD si défini

Workflow opérateur

1. Contrôler la topologie résolue avec make topology-env ENV=staging CHECK=1.
2. Copier la trame heymoov-platform/deploy/env/heymoov-runtime.env.template vers /etc/heymoov/heymoov-staging.env si le fichier n'existe pas déjà, ou lancer make install-env ENV=staging.
3. Lancer make bootstrap-storage-env ENV=staging.
4. Lancer make bootstrap-runtime-env ENV=staging.
5. Lancer make bootstrap-hydra-env ENV=staging.
6. Lancer make bootstrap-mercure-env ENV=staging.
7. Remplir manuellement les valeurs requises restantes.
8. Lancer make bootstrap-hydra-clients ENV=staging.
9. Poser les permissions root:heymoov-deploy et 0640 sur /etc/heymoov/heymoov-staging.env, /etc/heymoov/hydra-staging.env et /etc/heymoov/mercure-staging.env.
10. Vérifier qu'aucun placeholder __REQUIRED_*__ ne reste dans le fichier runtime.

Points de contrôle avant activation

Avant toute activation de heymoov-staging, vérifier au minimum:

• APP_ENV=staging
• les variables PGS_* et REDIS_* ont été renseignées par le bootstrap storage et pointent vers le stockage staging
• heymoov-staging-hydra.service est actif et exposé Hydra sur 127.0.0.1:4446/4447
• heymoov-staging-mercure.service est actif et exposé Mercure sur 127.0.0.1:2023
• make verify-env ENV=staging valide l'issuer live https://auth.staging.heymoov.com
• make verify-env ENV=staging valide /healthz Mercure et le preflight CORS depuis https://app.staging.heymoov.com
• AUTH_COOKIE_DOMAIN correspond bien au domaine staging
• FRONTEND_DOCUMENT_URL pointe vers /uploads/ sur le vhost app
• les callbacks Hydra pointent tous vers le vhost app
• TURNSTILE_EXPECTED_HOSTNAME correspond bien au host app
• HYDRA_CLIENT_SECRETS ne contient que les secrets des clients confidentiels
• le groupe heymoov-deploy est restreint aux opérateurs autorisés à lire les secrets et lancer les migrations