Services et outils du projet

Ce guide décrit les intégrations présentes dans le code et les procédures d’exploitation, avec un inventaire vérifié le 13 octobre 2026. La présence d’un adaptateur ou d’une variable ne prouve pas qu’un abonnement est actif sur tous les environnements. Le fournisseur du serveur, le prestataire SMTP et les offres réellement souscrites doivent être confirmés dans le registre d’exploitation.

Comprendre les flux

Les contenus métier passent du navigateur au serveur SvelteKit, puis à l’API Go/PocketBase. Les cookies de session et les secrets backend restent côté serveur. Certaines ressources externes, notamment les cartes, les polices et les images de repli, sont chargées directement par le navigateur.

Flux	Qui effectue l’appel ?	Données ou ressources échangées
Consultation et édition des contenus	SvelteKit → PocketBase	Contenus, médias, demandes et informations nécessaires aux écrans
Cartographie MapTiler	Navigateur → MapTiler	Styles et ressources cartographiques ; IP, zone affichée et clé publique de carte
Génération OpenAI	Backend → OpenAI	Consignes et contenu nécessaire à la génération ou à la traduction
Envoi d’e-mail	Backend → relais SMTP	Destinataires, contenu du message et pièces jointes éventuelles
Synchronisation de calendrier	Backend → URL iCal externe	URL privée d’abonnement et événements de disponibilité
Polices et images de repli	Navigateur → Google Fonts ou Unsplash	Requêtes de ressources, IP et métadonnées HTTP
Livraison d’une version	GitHub Actions → GHCR → Dokploy	Code compilé, images Docker et demandes de déploiement
Sauvegarde du backend	Dokploy → stockage S3/R2	Copie du volume PocketBase, incluant base et fichiers

Le détail de la frontière navigateur–serveur est expliqué dans l’architecture.

Hébergement et livraison

Pour le remplacement du site Heroku, les nouveaux comptes fournisseurs et la bascule des domaines OVH, suivre le plan de migration de la plateforme.

GitHub, GitHub Actions et GHCR

Les dépôts Chris589/harmony-web et Chris589/harmony-backend contiennent le code, les PR, les issues et les releases. Les workflows sous .github/workflows/ exécutent les validations et les publications prévues par chaque dépôt. GHCR, le registre de conteneurs GitHub, conserve les images Docker utilisées par Dokploy. Les tags liés au SHA permettent d’identifier le code déployé.

Les secrets de publication et de déploiement sont injectés par GitHub Actions. Les workflows emploient notamment GITHUB_TOKEN, DOKPLOY_API_TOKEN et les identifiants de registre requis par le déploiement. Les valeurs exactes restent dans les coffres GitHub/Dokploy.

Une panne GitHub ou GHCR peut bloquer une nouvelle livraison ; les conteneurs déjà démarrés continuent à fonctionner. Vérifiez le résultat de la CI, la disponibilité de l’image et la révision exposée par le health check avant d’attribuer un problème au code applicatif.

Sources : workflows des deux dépôts, web/scripts/dokploy-deploy.sh et procédure de livraison. La politique de coûts CI décrit les contrôles sélectionnés et les caches.

Dokploy, Docker, Traefik et Caddy

Dokploy pilote les applications web, backend, Storybook et documentation sur les serveurs de l’exploitant. Docker exécute leurs images. Traefik gère le routage des domaines et les certificats dans l’infrastructure Dokploy. Caddy sert les builds statiques de Storybook et du portail documentaire, conformément aux Dockerfiles du dépôt web.

Le web utilise le port conteneur 3000, le backend 8090, et les services statiques 80. Le volume backend /app/pb_data conserve la base SQLite et les fichiers PocketBase. Le fournisseur du VPS n’est pas fixé par le code. Son abonnement s’ajoute au coût éventuel de Dokploy Cloud ; Dokploy auto-hébergé n’inclut pas un serveur gratuit.

Configurez les domaines, réseaux, variables d’exécution et volumes par environnement. Une panne du serveur ou du routage peut rendre le site indisponible. Contrôlez d’abord les domaines, certificats, conteneurs et health checks ; préservez le volume backend pendant toute réparation. Voir déploiement et previews et domaines.

Cloudflare Access

Les procédures actuelles utilisent Cloudflare Access pour protéger l’accès à la recette. Cette couche contrôle l’accès au domaine avant l’application ; elle est distincte de la connexion au back-office et de sa double authentification. Son activation est une configuration d’infrastructure, pas une option des formulaires SvelteKit.

Les vérifications automatisées qui doivent traverser Access nécessitent une autorisation adaptée. Une redirection vers la page de connexion Cloudflare ne prouve pas que l’application répond correctement. Vérifiez les politiques du domaine concerné et les exceptions de health check documentées dans la livraison continue.

Cloudflare R2 ou autre stockage S3 de sauvegarde

Dokploy crée les sauvegardes du volume backend vers une destination compatible S3. Les procédures backend mentionnent R2. Les identifiants, le bucket et les règles de rétention sont configurés dans l’infrastructure ; ils ne sont pas exposés au navigateur.

Cette destination contient potentiellement des données personnelles, des fichiers privés et des données d’authentification de PocketBase. Elle doit rester privée. R2 intervient ici dans les sauvegardes : cela ne signifie pas que tous les médias du site sont servis depuis R2.

Une panne du stockage peut empêcher une sauvegarde et bloquer une opération qui l’exige, sans arrêter automatiquement le site déjà en fonctionnement. Contrôlez la dernière sauvegarde réussie, sa rétention et un test de restauration. Sources : backend/docs/operations.md et sauvegardes et restauration.

Dimensionner les VPS

Ces configurations sont des recommandations pour un trafic modéré, à confirmer par des mesures de CPU, mémoire, disque et temps de réponse. Elles supposent des images compilées dans GitHub Actions et déployées depuis GHCR. Les imports et conversions de médias, les compilations locales et les previews simultanées peuvent augmenter sensiblement les besoins.

Production, staging et previews sur des serveurs séparés

Environnement	Configuration conseillée	Stockage SSD/NVMe	Hypothèse
Production	4 vCPU, 8 Go de RAM	100–160 Go	Dokploy, web, backend et trafic modéré
Staging	2 vCPU, 4 Go de RAM	60–80 Go	Une copie de recette, données maîtrisées et builds en CI
Serveur de previews	4 vCPU, 8 Go de RAM	80–160 Go	Une à deux previews web/backend actives, arrêt des anciennes

La capacité du serveur de previews est un budget partagé : elle n’est pas allouée intégralement à chaque PR. Limitez le nombre de previews simultanées et leur durée de vie. Une preview backend dispose de son propre volume ; elle ne doit jamais utiliser les données ou les secrets de production.

Séparer la production de la recette évite qu’une compilation, un import ou un disque plein sur le serveur de développement affecte directement les visiteurs. Cette séparation augmente le coût et le travail d’administration, sans assurer à elle seule une haute disponibilité.

Tous les environnements sur un VPS

Usage	Configuration conseillée	Stockage SSD/NVMe
Production seule, petit trafic : minimum de départ	2 vCPU, 4 Go de RAM	80 Go
Production et staging, peu de previews et builds en CI	4 vCPU, 8 Go de RAM	100–160 Go
Production, staging et plusieurs previews : choix confortable	4–8 vCPU, 16 Go de RAM	160 Go ou plus

Pour héberger l’ensemble sur une seule machine, prévoir 16 Go de RAM donne une marge utile pour les pointes de charge. Huit Go restent envisageables si les previews sont limitées et les opérations lourdes espacées. Le stockage doit être revu selon la médiathèque, les variantes d’images, les volumes de recette et les caches Docker.

Dokploy indique un minimum de 2 Go de RAM et 30 Go de disque pour son installation ; ce minimum ne représente pas une recommandation pour toute la plateforme. Voir les prérequis officiels.

Configuration et exploitation conseillées

• Choisir Ubuntu 24.04 LTS, un disque SSD/NVMe et un datacenter proche des visiteurs, en France ou dans une région européenne adaptée. Aucun GPU n’est nécessaire pour l’IA appelée chez OpenAI.
• Conserver les builds web, backend, Storybook et documentation dans la CI quand le pipeline le permet. Limiter les compilations simultanées sur le serveur d’exploitation.
• Garder une seule instance backend écrivant dans chaque volume PocketBase ; augmenter les ressources du VPS ne transforme pas la base SQLite en cluster multi-écrivains.
• Définir des limites de ressources pour la recette et les previews afin de conserver de la mémoire et du CPU pour la production, Dokploy et le système.
• Sauvegarder les données PocketBase vers une destination externe comme R2. Une sauvegarde locale ou un snapshot fournisseur ne remplace pas la rétention et les tests de restauration.
• Nettoyer régulièrement les images et caches Docker inutilisés ainsi que les anciennes previews, sans supprimer les volumes persistants nécessaires.

Comme seuils de suivi initiaux, investiguer une RAM utilisée durablement au-delà de 75–80 %, un CPU saturé pendant les requêtes, des arrêts par manque de mémoire ou un disque rempli à plus de 80 %. Ces seuils guident une investigation ; ils ne constituent pas une mesure de capacité ou un SLA. Adapter ensuite la configuration au trafic et aux imports réellement observés.

Avant de choisir une offre, vérifier le prix après promotion, l’engagement, les frais d’installation, les options de sauvegarde, le lieu du datacenter et la possibilité d’agrandir le disque. Le nombre de vCPU de deux fournisseurs ne garantit pas des performances identiques.

Intégrations fonctionnelles

MapTiler et MapLibre GL

MapLibre GL est la bibliothèque qui affiche les cartes dans le navigateur. MapTiler fournit les styles et les ressources du fond de carte : DiscoveryMap.svelte pour le site public et BackOfficeLocationMap.svelte pour le placement des lieux dans le back-office.

La variable PUBLIC_MAPTILER_KEY est volontairement accessible au navigateur. Limitez son utilisation aux domaines autorisés dans le compte MapTiler. La carte publique peut aussi recevoir une URL de style explicite, qui prend priorité sur la clé. Les lieux et leurs coordonnées viennent des données du projet ; ils ne constituent pas un catalogue récupéré auprès de MapTiler.

Sans clé ou style configuré, les composants prévoient un fond de repli local, sans carte géographique détaillée. Une panne ou un quota épuisé peut empêcher le chargement du fond. Vérifiez la clé, les restrictions de domaine et les réponses de api.maptiler.com dans le navigateur. Voir configuration et tarification MapTiler.

OpenAI API

Le backend contient l’adaptateur OpenAI sous backend/infra/ai/openai/. Le navigateur appelle les actions ou routes BFF du back-office ; le backend contacte ensuite l’API du fournisseur. Cette intégration sert aux propositions de traduction et aux fonctions de génération éditoriale assistée par IA. Les suggestions doivent être vérifiées avant application.

L’IA est désactivée par défaut avec HARMONY_AI_ENABLED=false. Son activation nécessite HARMONY_AI_PROVIDER=openai, HARMONY_OPENAI_API_KEY et les modèles des profils HARMONY_AI_MODEL_ECONOMY, HARMONY_AI_MODEL_BALANCED, HARMONY_AI_MODEL_QUALITY ainsi que HARMONY_AI_TRANSLATION_MODEL. L’URL fournisseur peut être configurée avec HARMONY_OPENAI_BASE_URL ; la valeur par défaut est https://api.openai.com/v1.

Le fournisseur reçoit le contenu nécessaire à la requête. Ne transmettez pas de secrets ou de données personnelles sans besoin métier autorisé. Les journaux d’audit ai_runs enregistrent des métadonnées d’exécution et de consommation, pas les clés, prompts complets ou réponses brutes. Une panne, une limite de quota ou la désactivation de l’IA affecte la génération assistée ; les fonctions sans IA restent disponibles. Vérifiez l’activation, les modèles, quotas et erreurs normalisées côté backend. Sources : backend/infra/ai/config.go, backend/docs/ai-generation.md et configuration des secrets.

Relais SMTP

La boîte [email protected] est hébergée chez OVH et y reste après la migration. Cela ne détermine pas automatiquement le fournisseur du relais SMTP utilisé par l’application. La bascule DNS doit conserver les enregistrements de messagerie OVH, indépendamment de l’IP du VPS web.

Le backend utilise Gomail pour le transport et Hermes pour construire les messages HTML et texte. Le relais SMTP envoie les e-mails de contact, réservation, devis, invitations et récupération de mot de passe. Le fournisseur n’est pas imposé par l’application.

Les paramètres de connexion viennent des variables backend HARMONY_SMTP_HOST, HARMONY_SMTP_PORT, HARMONY_SMTP_USER et HARMONY_SMTP_PASSWORD. L’identité de l’expéditeur et les destinataires métier viennent de la collection PocketBase configs, entrée email. HARMONY_PUBLIC_SITE_URL permet de définir l’origine publique des liens envoyés. Aucun mot de passe SMTP ne doit être placé dans une variable PUBLIC_*.

Le prestataire reçoit les adresses, messages et pièces jointes, notamment les PDF de devis. Une indisponibilité empêche ou retarde les envois ; plusieurs parcours disposent de files et de relances, sans garantie qu’une demande acceptée soit déjà livrée. Pour la récupération de mot de passe, une configuration indisponible peut produire une erreur 503, distincte d’un refus CSRF. Vérifiez la configuration, les logs d’envoi et les files de livraison. Sources : backend/infra/email/config.go, backend/main.go, backend/docs/password-recovery.md et démarrage du back-office.

Calendriers iCal/ICS

Le backend importe des disponibilités depuis les URL de calendriers configurées et expose des exports compatibles iCal/ICS. Cela permet des échanges avec Airbnb, Booking.com ou d’autres consommateurs compatibles, sans adaptateur API dédié à chaque plateforme.

Les URL privées d’abonnement doivent être traitées comme des secrets. Les imports vérifient les destinations réseau ; le fetcher exige une URL HTTPS et bloque les adresses privées ou locales. La synchronisation périodique des calendriers externes est enregistrée toutes les cinq minutes dans backend/main.go.

Une panne du fournisseur peut rendre les disponibilités synchronisées périmées. Consultez l’état de chaque source et la dernière synchronisation ; n’interprétez pas un échec de chargement comme une disponibilité confirmée. Sources : backend/infra/externalcalendar/, backend/docs/calendar-exports.md et paramètres du back-office.

Google Fonts, Unsplash et liens externes

web/src/app.css charge Lato, Geist, Geist Mono et Material Symbols depuis Google Fonts. Une indisponibilité peut modifier les polices ou les icônes affichées. Ces requêtes partent directement du navigateur vers le fournisseur.

Des URL Unsplash servent d’images de repli dans les pages publiques et de contenus de démonstration. Les médias éditoriaux configurés peuvent les remplacer. Une image de repli reste une dépendance externe tant que son URL est utilisée à l’affichage.

Les liens d’itinéraire Google Maps ouvrent un service externe avec les coordonnées du lieu. Le lien WhatsApp de la page de maintenance utilise actuellement un numéro de démonstration, à remplacer avant usage réel. Ces liens ne constituent pas une intégration de facturation Google Maps Platform ni de WhatsApp Business API dans le projet.

Sources : web/src/app.css, web/src/routes/(app)/+page.svelte, web/src/routes/(app)/services/spa/+page.svelte, SurroundingsPageViewModel.ts et web/src/routes/maintenance/+page.svelte.

Outils exécutés dans le projet

Ces outils sont des dépendances installées, pas nécessairement des services SaaS avec abonnement.

Groupe	Outils	Usage
Application web	Svelte, SvelteKit, TypeScript, Node.js, Vite	Interfaces, rendu serveur, BFF et compilation
Interface	Tailwind CSS, shadcn-svelte/Bits UI, Lucide, Svelte Sonner	Styles, composants, icônes et notifications
Traductions et dates	Paraglide/inlang, Luxon	Messages de l’interface publique et gestion des dates
API et persistance	Go, PocketBase, SQLite	Logique métier, authentification, fichiers et base locale au backend
E-mails et images	Hermes, Gomail, Imaging, encodeurs WebP/AVIF	Construction des messages et traitement des médias
Qualité	ESLint, Prettier, Svelte Check, gofmt, go vet, Staticcheck	Contrôles statiques et formatage
Tests	Vitest, Testing Library, Playwright/Chromium	Tests unitaires, composants et parcours navigateur
Documentation	Astro, Starlight, Scalar, OpenAPI	Portail documentaire et référence du contrat HTTP
Composants et livraison	Storybook, Git, Make, Docker/Buildx	Démonstrations UI, commandes communes et images

L’addon Chromatic est présent dans Storybook, mais aucun usage actif du service de snapshots ne peut être déduit de cette seule dépendance. Vérifiez le compte et les publications avant de compter un abonnement Chromatic dans le budget.

Les dépendances et leurs versions exactes sont dans web/package.json, web/documentation/package.json, backend/go.mod et leurs fichiers de verrouillage.

Coûts et suivi des abonnements

Les prix sont variables et les quotas se cumulent parfois au niveau d’un compte partagé. Les valeurs suivantes sont des repères vérifiés le 13 octobre 2026, à recontrôler avant achat.

Service	Mode de facturation	Source fournisseur
Serveur	Abonnement au VPS ; fournisseur et dimensionnement à confirmer	Facture de l’hébergeur
Dokploy	Auto-hébergement gratuit ; Cloud à partir de 4,50 $/mois par serveur, serveur en supplément	Tarifs Dokploy
MapTiler	Flex à partir de 30 $/mois, dépassements éventuels ; gratuit pour tests et usages non commerciaux	Tarifs MapTiler
OpenAI	Tokens consommés et modèle choisi ; aucun coût de requête si l’IA est désactivée	Tarifs OpenAI
SMTP	Offre du prestataire et volume d’envois	Compte SMTP de l’environnement
R2	Quota gratuit puis stockage et opérations ; 10 Go-mois gratuits en stockage standard	Tarifs R2
Cloudflare Access	Offre gratuite pour une petite équipe ; offres payantes selon le besoin	Tarifs Access
GitHub Actions	Quotas du compte, runners et stockage ; dépassements facturables	Facturation Actions
GHCR	Stockage et bande passante des images conteneur actuellement gratuits	Facturation Packages
Chromatic	Facultatif ; quotas gratuits et offres payantes	Tarifs Chromatic

Un budget indicatif de 50 à 80 € HT/mois, avec marge à 90 €, suppose un serveur à 15–25 €, MapTiler Flex autour de 27 € après conversion indicative, peu d’e-mails, une utilisation modérée de l’IA et des sauvegardes, et une CI restant proche de ses quotas. Ce n’est pas une mesure des dépenses actuelles. Domaines, maintenance humaine, abonnements personnels de développement et usages dépassant ces hypothèses sont exclus.

Pour chaque service activé, consignez son responsable, l’environnement, l’offre, le quota, la rétention et la date de renouvellement. Conservez un lien vers le coffre des secrets, jamais leur valeur dans ce guide. Contrôlez régulièrement les consommations de cartes, les tokens IA, les minutes CI, les envois SMTP et la taille moyenne des sauvegardes.