Référence opérateur - trame `heymoov-dev.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-dev.

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.

Source de vérité utilisée¶

Constat mis à jour le 2026-04-30 sur ls2i-staging:

fichier source observé: runtime dev actuellement en service sur ls2i-staging
cible de migration: /etc/heymoov/heymoov-dev.env
topologie non secrète: heymoov-platform/deploy/inventory/heymoov.envs
stockage dédié actif: heymoov_dev pour l'app et heymoov_dev_hydra pour Hydra

Important:

heymoov-dev utilise maintenant un stockage PostgreSQL dédié
les anciennes bases legacy spoc et hydra ont été sauvegardées puis supprimées le 2026-04-30
backup final avant purge legacy: /var/backups/heymoov-legacy-postgres-drop/20260430T202011Z
les valeurs secrets du runtime courant ne doivent pas être commitées dans le repository
le service doit charger ce fichier via EnvironmentFile=
le répertoire /opt/heymoov-dev 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-dev

Règles de préparation¶

La préparation de heymoov-dev.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 dev.

Valeurs dérivées de la convention cible `heymoov-dev`¶

Les variables suivantes doivent être renseignées à partir de la ligne dev de heymoov-runtime-target.md:

HTTP_ADDR=127.0.0.1:9196
READYZ_ADDR=127.0.0.1:18081
CORS_ALLOWED_ORIGINS_WEB
SWAGGER_ENABLED=1
AUTH_COOKIE_DOMAIN
HYDRA_PUBLIC_URL
HYDRA_OIDC_ISSUER_URL
HYDRA_CALLBACK_URL
HYDRA_MOBILE_CALLBACK_URL
HYDRA_FRONTEND_CALLBACK_URL
HYDRA_MOBILE_APP_RETURN_URL
MOBILE_WEBAUTHN_RP_ID=auth.dev.heymoov.com
MOBILE_WEBAUTHN_RP_DISPLAY_NAME=HeyMoov
MOBILE_WEBAUTHN_ALLOWED_ORIGINS
MOBILE_WEBAUTHN_CHALLENGE_TTL=5m
MERCURE_URL
MERCURE_TOPICS_PREFIX
FRONTEND_DOCUMENT_URL
FRONTEND_SHOWCASE_URL
FRONTEND_APP_URL
TURNSTILE_EXPECTED_HOSTNAME

Exception transitoire au 26 avril 2026:

tant que la landing staging.heymoov.com appelle encore https://app.dev.heymoov.com/v1/public/contact-us, CORS_ALLOWED_ORIGINS_WEB_DEV doit aussi autoriser https://staging.heymoov.com
cette exception ne doit pas devenir l'état cible de heymoov-dev
TURNSTILE_EXPECTED_HOSTNAME reste strictement app.dev.heymoov.com pour heymoov-dev

Valeurs live transitoires actuellement posées sur ls2i-staging:

CORS_ALLOWED_ORIGINS_WEB_DEV="http://localhost:3006,https://staging.heymoov.com"

Retour à la cible attendue une fois app.staging.heymoov.com en service:

retirer https://staging.heymoov.com de CORS_ALLOWED_ORIGINS_WEB_DEV
ne plus faire appeler la landing staging vers app.dev.heymoov.com

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:

APP_NAME
APP_ENV
PGS_HOST
PGS_PORT
PGS_LOGIN
PGS_DB
CORS_ALLOWED_ORIGINS_WEB_DEV
JWT_SECRET_DURATION
REFRESH_COOKIE_DURATION
FORGOT_PASSWORD_LINK_DURATION
CHANGE_EMAIL_LINK_DURATION
SECURITY_TOKEN_DURATION
HYDRA_ADMIN_URL
HYDRA_INTERNAL_URL si utilisé
HYDRA_ENCRYPTION_KEY_CURRENT
MERCURE_COOKIE_DURATION
REDIS_ADDRESS
REDIS_DATABASE
EMAIL_NOREPLY
EMAIL_CONTACT
EMAIL_PROVIDER
MAILPIT_URL, MAILDEV_URL, MAILTRAP_URL, MAILTRAP_INBOX_ID ou SIB_API_KEY selon le provider retenu (SIB_API_KEY est requis quand EMAIL_PROVIDER=BREVO)
MAX_UPLOAD_FILESIZE
TURNSTILE_TIMEOUT
TURNSTILE_MAX_CHALLENGE_AGE

Valeurs à figer explicitement pour `dev`¶

La convention retenue pour heymoov-dev est:

HYDRA_WEB_CLIENT_ID=heymoov-dev-web
HYDRA_MOBILE_CLIENT_ID=heymoov-dev-mobile

Convention retenue sur ls2i-staging:

heymoov-dev-web est un client confidentiel en client_secret_post
heymoov-dev-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

Valeurs passkeys mobiles pour `dev`¶

La convention passkeys mobile retenue pour heymoov-dev est:

MOBILE_WEBAUTHN_RP_ID=auth.dev.heymoov.com
MOBILE_WEBAUTHN_RP_DISPLAY_NAME=HeyMoov
MOBILE_WEBAUTHN_CHALLENGE_TTL=5m
MOBILE_WEBAUTHN_ALLOWED_ORIGINS doit contenir les origins natives autorisées par l'app mobile dev

Origins Android actuellement attendues:

android:apk-key-hash:t8pZmppGQfI3Qoo_fn48QLsOarp8g5O8p5V94jBhUuM
android:apk-key-hash:-sYXRdwJA3hvue3mKpYrOZ9zSPC7b4mbgzJmdZEDO5w

Origin web/iOS à poser dans l'allowlist backend:

https://auth.dev.heymoov.com

Valeurs renseignées par le bootstrap Mercure daemon¶

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

Avec le slot primary courant, le bootstrap retient:

service systemd: heymoov-dev-mercure.service
Caddyfile: /etc/heymoov/mercure-dev.Caddyfile
data dir: /var/lib/heymoov-mercure/dev
URL interne Mercure: http://127.0.0.1:2022/.well-known/mercure
URL publique Mercure: https://mercure.dev.heymoov.com
origin publish stricte: https://app.dev.heymoov.com
origins subscriber CORS: https://app.dev.heymoov.com et http://localhost:3006

Il renseigne le daemon à partir des secrets déjà présents dans /etc/heymoov/heymoov-dev.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:2022
MERCURE_CORS_ORIGINS=https://app.dev.heymoov.com http://localhost:3006
MERCURE_PUBLISH_ORIGINS=https://app.dev.heymoov.com

L'origine http://localhost:3006 fait partie de la cible normale de heymoov-dev: elle permet au front web lancé localement par les développeurs d'utiliser le hub Mercure partagé de l'environnement dev. Cette exception ne s'applique pas à staging ni à prod.

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:

PGS_PASS
JWT_LEGACY_HS256_KEY
WEB_UI_JWT_HS256_KEY
SECRET_PEPPER
TOKEN_PEPPER
HYDRA_ENCRYPTION_KEYS
HYDRA_STATE_COOKIE_KEY
HYDRA_CLIENT_SECRETS
MERCURE_PUBLISHER_JWT_KEY
MERCURE_SUBSCRIBER_JWT_KEY
MAILTRAP_API_KEY si EMAIL_PROVIDER=MAILTRAP
SIB_API_KEY si EMAIL_PROVIDER=BREVO
TURNSTILE_SECRET_KEY
REDIS_PASSWORD si défini

Valeurs à ne pas reporter telles quelles¶

Points à corriger pendant la création de heymoov-dev:

remplacer TURNSTILE_MAX_CHALLENGE_AGE_SEC par TURNSTILE_MAX_CHALLENGE_AGE
ne pas reporter les variables GOOGLE_APPLICATION_CREDENTIALS
ne pas reporter les variables GOOGLE_CLOUD_PROJECT_ID
ne pas reporter les variables GOOGLE_RECAPTCHA_PUBLIC_KEY

Les variables GOOGLE_* ne sont pas consommées par le bootstrap principal du backend actuel.

Workflow opérateur¶

Contrôler la topologie résolue avec make topology-env ENV=dev CHECK=1.
Copier la trame heymoov-platform/deploy/env/heymoov-runtime.env.template vers /etc/heymoov/heymoov-dev.env si le fichier n'existe pas déjà, ou lancer make install-env ENV=dev.
Remplir manuellement toutes les valeurs requises.
Générer le secret du client web puis remplir HYDRA_CLIENT_SECRETS.
Lancer make bootstrap-hydra-clients ENV=dev.
Poser les permissions root:heymoov-deploy et 0640 sur /etc/heymoov/heymoov-dev.env.
Vérifier qu'aucun placeholder __REQUIRED_*__ ne reste dans le fichier.

Points de contrôle avant activation¶

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

AUTH_COOKIE_DOMAIN correspond bien au domaine dev
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

Référence opérateur - trame heymoov-dev.env¶