Déployer dans votre infrastructure

Vous recevez le socle avec des Dockerfiles de référence et un contrat d'exécution portable. Votre plateforme fournit le registre, le réseau, les secrets, la terminaison TLS, le stockage persistant et la supervision. Vous raccordez ensuite les intégrations propres à votre application.

Cette procédure vous présente les invariants à conserver, puis les choix à adapter à Docker Compose, Kubernetes, OpenShift, ECS ou Nomad.

Comprendre la topologie de référence

Le runtime nominal réunit trois rôles :

1. le frontend sert la SPA, injecte sa configuration publique et relaie /api/* ainsi que /sso/* vers le backend ;
2. le backend expose l'API, applique les migrations et initialise les données de socle ;
3. PostgreSQL conserve les données applicatives.

Le navigateur accède à votre application par le frontend. Le backend et PostgreSQL restent sur le réseau privé. PostgreSQL peut être conteneurisé avec un volume persistant ou remplacé par un service managé compatible.

01NavigateurLa session authentifiée de l'utilisateur

02FrontendSPA, assets statiques et proxy pour /api et /sso

03BackendAPI, autorisations, modules, jobs et health check

04Services de donnéesPostgreSQL, stockage et messagerie réellement utilisés

Les ports par défaut sont 3000 pour le frontend, 14000 pour le backend et 5432 pour PostgreSQL. Ils peuvent changer tant que les services, probes et règles réseau utilisent les mêmes valeurs. Le frontend et le backend ne s'appuient pas sur leur filesystem local pour stocker les données métier.

Préparer votre plateforme

Avant le premier déploiement, réunissez :

• un registre accessible par votre CI et votre plateforme ;
• un accès DNS et une terminaison TLS ;
• un réseau privé entre frontend, backend et PostgreSQL ;
• un mécanisme de secrets compatible avec l'orchestrateur ;
• un stockage PostgreSQL persistant, avec sauvegarde et restauration testées ;
• les accès sortants nécessaires aux intégrations réellement activées ;
• des destinations centralisées pour les logs et, selon vos besoins, les métriques et traces.

Le build part de la racine du repository afin d'inclure le workspace et son lockfile. Les Dockerfiles de référence ciblent actuellement linux/amd64. Si votre plateforme utilise une autre architecture CPU, prévoyez un build et une recette dédiés.

Les Dockerfiles utilisent la syntaxe BuildKit docker/dockerfile:1 et COPY --parents. Utilisez Docker avec BuildKit ou, pour un BuildConfig OpenShift, Buildah 1.40 ou plus récent. La résolution de l'image de syntaxe peut aussi nécessiter un accès sortant au registre Docker pendant le build.

L'image backend lance des commandes pnpm au démarrage via Corepack. Si la version attendue de pnpm n'est pas déjà présente dans le cache de l'image, autorisez l'accès sortant à registry.npmjs.org ou préparez cette version dans l'image avant sa publication.

Construire et publier des images immuables

Construisez le frontend et le backend depuis le même commit :

docker build -f infra/docker/backend.Dockerfile --platform linux/amd64 \
  -t <registry>/<application>-backend:<version> .

docker build -f infra/docker/frontend.Dockerfile --platform linux/amd64 \
  -t <registry>/<application>-frontend:<version> .

Publiez un tag immuable ou un digest, puis conservez les deux références dans la preuve de recette. Aucun secret ne doit être injecté au build ou rester dans une couche d'image. Le build frontend conserve MOCK_API=false afin de produire votre application reliée à l'API réelle.

L'image officielle PostgreSQL suffit lorsque vos migrations n'utilisent que les extensions disponibles sur votre plateforme. Le Dockerfile PostgreSQL du socle permet de dériver une image si votre projet requiert une extension supplémentaire. Fixez alors la version et les extensions dans votre matrice de compatibilité.

Configurer sans exposer les secrets

Injectez la configuration au runtime. Conservez les valeurs secrètes dans le mécanisme de secrets de votre plateforme et ne les committez jamais.

Conteneur PostgreSQL

Backend

Le backend accepte aussi des variables conditionnelles ou optionnelles :

• DEFAULT_USER_PASSWORD pour le bootstrap initial ;
• FRONTEND_URL pour les redirections SSO ;
• PORT, avec 14000 par défaut ;
• POSTGRES_SSL et POSTGRES_SSL_CA pour PostgreSQL sur TLS ;
• NODE_EXTRA_CA_CERTS pour une PKI privée, notamment celle d'un IdP ;
• CORS_ALLOWED_ORIGINS pour une topologie réellement cross-origin ;
• COOKIE_DOMAIN pour partager explicitement une session entre plusieurs hosts ;
• WORKSPACE_SSO_ENABLED pour les fournisseurs SSO propres aux workspaces ;
• CRON_ENABLED, CRON_INSTANCE_ID et CRON_SHUTDOWN_DRAIN_MS pour les tâches planifiées ;
• LOG_LEVEL pour le niveau des logs ;
• HTTPS_PROXY et NO_PROXY lorsque l'accès sortant de Corepack passe par un proxy d'entreprise ;
• COREPACK_HOME lorsque votre plateforme impose un UID arbitraire ;
• OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, OTEL_TRACES_EXPORTER et OTEL_SDK_DISABLED pour OpenTelemetry.

DATABASE_URL peut configurer le pool applicatif, mais ne remplace pas les variables PostgreSQL séparées dans l'image actuelle : le bootstrap lancé au démarrage les consomme encore.

OpenTelemetry reste désactivé tant qu'aucun exporteur n'est configuré. OTEL_EXPORTER_OTLP_ENDPOINT active l'envoi vers le collecteur, OTEL_SERVICE_NAME identifie votre application dans les traces, OTEL_TRACES_EXPORTER=console sert aux vérifications locales et OTEL_SDK_DISABLED=true force la désactivation.

Dans l'image backend actuelle, le bootstrap PostgreSQL s'authentifie avec POSTGRES_DB_USER et POSTGRES_PASSWORD, puis le runtime applicatif utilise POSTGRES_DB_USER et POSTGRES_DB_USER_PASSWORD. Avec le conteneur PostgreSQL nominal, ces valeurs désignent généralement le même compte et le même secret. Une séparation stricte entre compte d'administration et compte applicatif nécessite d'adapter le job ou l'entrypoint de bootstrap.

Frontend et SDK Maleus

Le SDK Maleus est optionnel et désactivé lorsque MALEUS_APP_API_KEY est vide. Cette clé est une information sensible de configuration à portée limitée, mais pas un secret serveur : lorsqu'elle est activée, le frontend l'injecte dans maleus-config.js et le navigateur peut la lire. Elle ne doit accorder aucun privilège administratif ni accès aux données applicatives.

MALEUS_SDK_CONFIG contient un objet JSON valide. Une valeur absente ou invalide applique une configuration fermée qui désactive le widget et ses fonctionnalités. Lorsque le SDK est activé, les navigateurs doivent pouvoir joindre en HTTPS les origines définies par MALEUS_FRONTEND_PUBLIC_URL et MALEUS_API_PUBLIC_URL.

Cette liste couvre le socle courant. Les variables propres aux fonctionnalités générées, comme le stockage objet, le SMTP, les API métier ou d'autres intégrations, sont ajoutées depuis le code et le contrat de configuration du repository livré.

Configurer le SSO

Configurez les fournisseurs OIDC ou SAML dans l'interface d'administration. Le socle les conserve en base. Leurs issuer, client ID, client secret, certificats et mappings ne sont pas des variables d'environnement du socle.

Sur le backend, définissez BACKEND_URL et FRONTEND_URL avec l'URL publique complète de votre application, préfixe de chemin compris. Les routes de connexion et de callback utilisent le chemin /sso/... sous l’URL publique et passent par le proxy /sso/* du frontend. Le backend reste privé.

Si l'IdP utilise une autorité de certification privée, montez la chaîne CA PEM dans le backend et définissez NODE_EXTRA_CA_CERTS vers ce fichier. WORKSPACE_SSO_ENABLED=false désactive les fournisseurs propres aux workspaces.

Orchestrer le démarrage et les migrations

Le premier backend suit une séquence ordonnée :

1. attendre que PostgreSQL accepte les connexions ;
2. créer de façon idempotente les rôles, la base, les schémas et extensions nécessaires ;
3. appliquer les migrations ;
4. créer les fixtures de socle de façon idempotente ;
5. lancer le processus Node et exposer le health check.

Le frontend reçoit du trafic lorsque le backend est prêt. Le modèle de base démarre un seul backend contre une base donnée pendant les migrations. Pour plusieurs replicas, exécutez la migration dans un job exclusif ou séparez le bootstrap du serveur avant d'autoriser le déploiement parallèle.

Avant une migration sensible, produisez une sauvegarde restaurable. Une recette de restauration valide la procédure, le temps de reprise et les permissions nécessaires.

Adapter le contrat à l'orchestrateur

Docker Compose

Le fichier de déploiement contient un volume nommé PostgreSQL, un health check pg_isready, un backend dépendant de la base saine et un frontend dépendant du backend. Seul le port frontend est publié.

Injectez les secrets sous forme de variables d'environnement à l'aide du mécanisme de votre plateforme, ou depuis un fichier local ignoré par Git pour une validation Compose. Les Docker secrets montés comme fichiers nécessitent un entrypoint d'adaptation, car les images actuelles ne lisent pas automatiquement les variantes *_FILE.

Ajoutez une politique de redémarrage aux services. depends_on ordonne le premier démarrage, mais ne garantit pas qu'un backend redémarré attendra PostgreSQL. Le backend s'arrête volontairement si son bootstrap échoue et doit alors être relancé. Validez la configuration résolue, contrôlez l'état des services et inspectez les logs. Un second démarrage doit rester idempotent.

Kubernetes et OpenShift

Déployez le frontend et le backend dans des Deployment séparés, avec des Service privés. L'Ingress ou la Route cible uniquement le frontend. PostgreSQL utilise un service managé ou un StatefulSet avec volume persistant.

Distinguez startupProbe, readinessProbe et livenessProbe. Tant que les migrations restent au démarrage du backend, conservez un replica ou lancez un job de migration exclusif. Sur OpenShift, validez aussi la politique SCC, l'UID d'exécution, le filesystem en lecture seule et les droits des volumes. Si votre plateforme impose un UID arbitraire, définissez COREPACK_HOME=/tmp/corepack et rendez /tmp inscriptible.

ECS ou Nomad

Sur ECS, le frontend et le backend peuvent partager une task et communiquer par localhost, ou devenir des services séparés reliés par le réseau privé. L'ALB cible le frontend. Les secrets viennent du gestionnaire de secrets de votre plateforme et les logs sont centralisés.

Sur Nomad, regroupez les tâches qui communiquent par loopback ou déclarez des services privés. Les checks pilotent le redémarrage et le retrait du trafic. Le volume PostgreSQL est fourni par CSI ou remplacé par une base managée. La stratégie d'update empêche deux migrations simultanées.

Terminer TLS, persistance et health checks

Le reverse proxy ou le load balancer termine TLS, redirige HTTP vers HTTPS et applique HSTS. Il transmet correctement le host et le protocole d'origine. /api/* et /sso/* entrent par le frontend, qui relaie les requêtes vers le backend privé. Le navigateur ne joint pas directement le backend.

Pour servir votre application sous /myapp, configurez BASE_PATH=/myapp et BACKEND_API_URL=/myapp/api sur le frontend, puis BACKEND_URL=https://application.example/myapp et, si le SSO est utilisé, FRONTEND_URL=https://application.example/myapp sur le backend. Routez tout le préfixe /myapp vers le frontend sans réécriture d'URL. Le frontend sert la SPA et relaie /myapp/api/* ainsi que /myapp/sso/*. La même image frontend peut être réutilisée sans rebuild.

Les contrôles de santé de référence sont :

• PostgreSQL : pg_isready ;
• backend privé : GET /server/health-check ;
• backend via le point d'entrée public : GET /api/server/health-check ;
• frontend : la racine ou la racine définie par BASE_PATH.

Le health check backend renvoie 200 lorsque les dépendances contrôlées sont saines et 503 dans le cas contraire. Les délais de démarrage couvrent la durée des migrations sans provoquer une boucle de redémarrage.

PostgreSQL porte la persistance du socle nominal. La politique d'exploitation précise le RPO, le RTO, la rétention, le chiffrement, la supervision des sauvegardes et la fréquence des tests de restauration. Chaque stockage ajouté par le projet suit sa propre politique.