Déployer avec Dokploy

Un déploiement Le Clos des Eucalyptus concerne jusqu’à quatre applications : backend, web, Storybook et portail documentaire. Le backend porte les données et doit être traité avec plus de précautions que les services statiques.

Ordre recommandé

1. Validez les commits exacts dans les deux dépôts.
2. Sauvegardez pb_data avant toute migration backend.
3. Déployez le backend si le contrat reste compatible avec le web en place.
4. Vérifiez sa santé et quelques endpoints représentatifs.
5. Déployez le web, puis exécutez un smoke test public et back-office.
6. Déployez Storybook et la documentation si leur contenu a changé.
7. Observez erreurs, latence et journaux pendant la fenêtre de surveillance.

Si le contrat n’est pas rétrocompatible, introduisez d’abord une phase compatible avec les deux versions. Évitez un basculement simultané impossible à annuler proprement.

Backend

Le backend/Dockerfile produit un binaire Go statique dans une image Alpine, écoute sur 8090 et exécute :

serve --http=0.0.0.0:8090 --dir=/app/pb_data

Configuration Dokploy :

Paramètre	Valeur
build	Dockerfile du dépôt backend
port interne	8090
health check	GET /api/health
volume persistant	monté sur /app/pb_data
utilisateur	UID 1000 dans l’image

Le point d’entrée remet le propriétaire du volume à l’utilisateur applicatif avant de lancer le binaire. Un volume absent ou monté ailleurs crée une nouvelle base vide ; un volume non inscriptible provoque généralement une erreur SQLite au démarrage.

Ne lancez pas make seed en production. Créez le premier superuser avec la commande PocketBase contrôlée et un mot de passe fort, puis supprimez toute information d’identification temporaire.

Web

Le web utilise l’adaptateur Node officiel et son Dockerfile applicatif écoute sur 3000. Il doit recevoir API_BASE_URL côté serveur et PUBLIC_MAPTILER_KEY au démarrage. Le contrôle GET /healthz est indépendant du backend et renvoie la révision immuable de l’image dans l’en-tête X-Harmony-Revision.

Après déploiement, validez :

• page d’accueil et page d’appartement rendues côté serveur ;
• changement de langue et navigation publique ;
• carte avec une clé autorisée pour le domaine ;
• redirection d’une URL /back-office non authentifiée vers /login ;
• connexion TOTP et une lecture back-office avec un compte de recette ;
• absence de token ou de secret dans les sources chargées par le navigateur.

Pour la bascule des pages légales, déployez le backend en premier puis vérifiez /api/legal-documents/{slug}?locale=fr pour terms, privacy_policy et booking_conditions : la réponse doit annoncer la version 1, une publication au 2026-06-10 et huit articles. Déployez ensuite le web avec LEGAL_CONTENT_SOURCE=api. Gardez le fallback activé pendant la fenêtre de surveillance, puis désactivez-le lorsque les cinq locales, les métadonnées SEO et le parcours de publication ont été vérifiés.

Storybook

Dockerfile.storybook construit les stories avec Node 22.19.0, copie le site statique dans Caddy et écoute sur 80. Le fichier robots.txt interdit l’indexation.

Paramètre	Valeur
Dockerfile	Dockerfile.storybook
port interne	80
données	aucune persistance

Contrôlez au minimum le chargement de l’index, une story publique et une story back-office.

Documentation

Dockerfile.documentation construit Starlight avec Node 22.19.0, puis sert dist/ avec Caddy.

Paramètre	Valeur
Dockerfile	Dockerfile.documentation
port interne	80
health check	GET /healthz
données	aucune persistance
en-tête staging	X-Robots-Tag: noindex, nofollow

Publication automatisée sur GHCR

Le workflow .github/workflows/deploy-documentation.yml construit l’image avec Dockerfile.documentation, la publie sur ghcr.io/chris589/harmony-documentation, puis appelle le script scripts/dokploy-deploy.sh. Dokploy reçoit le digest sha256 exact de l’image. Le contrôle /healthz vérifie également l’en-tête X-Harmony-Revision : une ancienne instance encore accessible ne suffit pas à valider le déploiement.

L’exécution automatique suit une CI réussie sur un push de develop dans ce dépôt. Les événements de pull request, forks et branches de fonctionnalité ne déploient pas. Un lancement manuel depuis l’onglet Actions est possible sur develop ou main ; il reconstruit le commit sélectionné et ne garantit pas à lui seul que sa CI est passée. Utilisez un commit validé. Le workflow doit être présent sur la branche par défaut pour recevoir workflow_run.

Configuration GitHub

Créez un environnement GitHub nommé documentation, distinct de staging et production. Configurez les valeurs suivantes dans cet environnement :

Type	Nom	Valeur ou rôle
Variable	PUBLIC_DOCUMENTATION_URL	URL HTTPS du portail, sans slash final
Variable	PUBLIC_STORYBOOK_URL	URL HTTPS du Storybook déployé
Variable	DOKPLOY_URL	URL HTTPS de Dokploy
Variable	DOKPLOY_APPLICATION_ID	Identifiant de l’application dédiée à la documentation
Secret	DOKPLOY_API_TOKEN	Clé API autorisée à configurer et déployer cette application
Secret	DOKPLOY_REGISTRY_USERNAME	Compte GitHub pouvant lire le package GHCR
Secret	DOKPLOY_REGISTRY_TOKEN	PAT classique avec read:packages, et autorisation SSO si nécessaire
Secret facultatif	CF_ACCESS_CLIENT_ID	Identifiant d’un service token Cloudflare Access
Secret facultatif	CF_ACCESS_CLIENT_SECRET	Secret du même service token

Le GITHUB_TOKEN fourni automatiquement au workflow publie l’image grâce à packages: write. Le jeton GHCR de lecture est distinct : Dokploy le conserve pour pouvoir télécharger les images privées après la fin du workflow. Le compte doit aussi avoir accès au package.

Si Cloudflare Access protège le portail, configurez les deux secrets de service token et une politique Service Auth qui autorise ce token pour le portail. Le script transmet ces en-têtes uniquement au contrôle de santé. L’API Dokploy doit également être accessible depuis le runner GitHub : ce mécanisme ne traverse pas une protection Access placée devant l’API Dokploy.

Ajoutez enfin la variable de dépôt DOCUMENTATION_DEPLOY_ENABLED=true pour activer le job. Elle doit être au niveau dépôt, car sa lecture précède le chargement de l’environnement. En son absence, aucun build, publication ou déploiement documentaire ne démarre. Les protections et approbations de l’environnement GitHub restent applicables.

Configuration Dokploy

1. Créez une application dédiée avec le fournisseur Docker, sans build Git ni auto-déploiement concurrent. Le workflow renseigne l’image et les identifiants du registre via l’API.
2. Configurez le domaine du portail, son certificat HTTPS et le port interne 80.
3. Faites pointer le DNS du sous-domaine vers le VPS ; aucun volume n’est nécessaire.
4. Configurez GitHub, puis activez le workflow et lancez-le depuis une branche autorisée.
5. Vérifiez la réussite du job, la page d’accueil, une page profonde, la recherche, la référence API et les PDF de formation. Consignez le digest dans le résumé Actions.

Les URL Astro sont évaluées au build et exigent une reconstruction après modification. Le contrat API provient par défaut de documentation/openapi.yaml, versionné dans le dépôt web. Mettez cette copie à jour quand le contrat backend change. Pour un build Docker manuel, HARMONY_BACKEND_OPENAPI_URL permet de télécharger un contrat public à la place ; le workflow utilise volontairement la copie versionnée pour un build indépendant du backend en ligne.

Le fichier Dockerfile.documentation.dockerignore remplace le .dockerignore général pour ce build : la documentation est incluse, ses dépendances et sorties locales sont exclues. L’en-tête X-Robots-Tag interdit l’indexation dans tous les environnements ; il ne remplace pas un contrôle d’accès.

Retour à une image précédente

Reprenez le digest d’un déploiement réussi dans son résumé Actions, configurez cette image dans Dokploy et redéployez-la. Vérifiez /healthz et X-Harmony-Revision, puis les pages principales. Désactivez temporairement DOCUMENTATION_DEPLOY_ENABLED si vous devez conserver ce rollback pendant de nouveaux pushs sur develop. Relancer un ancien workflow reconstruit ses sources ; pour réutiliser exactement une image déjà publiée, utilisez son digest conservé sur GHCR.

Checklist avant lancement

• CI verte sur les commits déployés ;
• migrations relues, données existantes prises en compte et retour arrière documenté ;
• snapshot récent du volume backend vérifié ;
• variables comparées à la matrice de l’environnement ;
• domaines et certificats prêts ;
• branche ou SHA de chaque application consigné ;
• personne responsable du déploiement et fenêtre d’observation identifiées ;
• procédure de rollback comprise avant l’action.

La publication et la promotion normales sont décrites dans Livraison continue. Une action manuelle dans Dokploy reste une procédure d’incident : elle ne doit pas devenir un deuxième chemin de déploiement quotidien.

Contrôles après lancement

curl -fsS https://api.example.test/api/health
curl -fsSI https://docs.example.test/healthz
curl -fsSI https://www.example.test/

Complétez les checks HTTP par un vrai parcours : une réponse 200 ne prouve ni la connexion au bon volume, ni l’accès du web au backend, ni le bon fonctionnement de l’authentification.

Vérifiez aussi :

• aucune boucle de redirection ou erreur de certificat ;
• aucune hausse durable des réponses 5xx ;
• aucun avertissement de clé de chiffrement manquante ;
• migrations terminées une seule fois ;
• données attendues présentes dans PocketBase ;
• e-mail et calendrier fonctionnels si le lot les touche ;
• version de la référence API cohérente avec le backend.

Rollback

Les images web, Storybook et documentation sont sans état : revenez au SHA précédent et redéployez. Le backend exige une décision séparée :

• code seul et migration compatible : redéployez l’image précédente ;
• migration réversible explicitement testée : exécutez le retour prévu, puis l’image précédente ;
• migration destructive ou données déjà écrites dans le nouveau format : ne rétrogradez pas à l’aveugle ; stoppez les écritures concernées et appliquez un plan de remédiation revu.

Après tout rollback, refaites les mêmes checks qu’après un déploiement et consignez l’intervalle de temps pendant lequel la version défaillante a été active.

Pour un incident limité aux pages légales, positionnez temporairement LEGAL_CONTENT_SOURCE=static et redéployez uniquement le web. Cette opération ne modifie aucune version backend. Revenez à api dès que la version publiée et la connectivité sont rétablies.