Configuration et secrets

La configuration Le Clos des Eucalyptus est répartie entre les variables d’environnement de Dokploy, les arguments de build et certains enregistrements PocketBase. Une valeur doit avoir un propriétaire unique : ne dupliquez pas un secret dans GitHub, Dokploy et PocketBase sans raison documentée.

Principes

• séparez strictement développement, staging, previews et production ;
• injectez les secrets à l’exécution, jamais dans une image ou une variable PUBLIC_* ;
• utilisez des clés différentes entre staging et production ;
• documentez le nom et le responsable d’un secret, pas sa valeur ;
• changez une seule famille de paramètres à la fois et validez le service dépendant ;
• conservez les variables facultatives désactivées plutôt que partiellement configurées.

Frontend SvelteKit

Variable	Exposition	Obligatoire	Usage
API_BASE_URL	serveur	oui hors environnement local	URL interne ou publique du backend, sans / final
API_TOKEN	secret	seulement pour les lectures système	token backend ajouté aux appels serveur anonymes nécessitant des champs privilégiés
LEGAL_CONTENT_SOURCE	serveur	non	api normalement, static uniquement pour le rollback temporaire des pages légales
LEGAL_CONTENT_FALLBACK_ENABLED	serveur	pendant la bascule légale	autorise le repli local si la version publiée est momentanément indisponible
PUBLIC_MAPTILER_KEY	navigateur	pour afficher la carte	clé MapTiler injectée au démarrage, non secrète
SEO_PUBLIC_ORIGIN	serveur	non	origine approuvée des canonical et Open Graph : https://www.leclosdeseucalyptus.com ; aucune origine de requête n’est utilisée
SEO_INDEXING_ENABLED	serveur	oui	true uniquement en production ; toute autre valeur applique noindex
SEO_INDEXING_ALLOWED_HOSTS	serveur	si l’indexation est activée	liste CSV exacte des hostnames publics autorisés à être indexés

| HARMONY_RELEASE_VERSION | serveur | injectée par le workflow production | version produit exposée par /healthz | | PUBLIC_HARMONY_RELEASE_VERSION | navigateur | injectée par le workflow production | version non sensible affichée sur la connexion |

API_BASE_URL doit être joignable depuis le conteneur web. Une URL comme 127.0.0.1:8090 désigne le conteneur web lui-même et ne fonctionne donc pas entre deux applications Dokploy. Utilisez le nom du service sur un réseau partagé ou l’URL HTTPS du backend.

PUBLIC_MAPTILER_KEY n’est pas un secret : limitez-la aux domaines de production, staging et preview dans le tableau de bord du fournisseur. Elle est lue dynamiquement par le runtime Node ; sa modification exige un redéploiement du conteneur, mais pas la construction d’une nouvelle image.

API_TOKEN, quand il est nécessaire, reste côté serveur. Les sessions du back-office emploient le token utilisateur stocké dans un cookie httpOnly ; elles ne doivent pas être remplacées par ce token global.

SEO_INDEXING_ENABLED est volontairement restrictif par défaut. Staging et toutes les previews utilisent false et une liste vide : X-Robots-Tag: noindex, nofollow, noarchive, nosnippet s’applique aux réponses, avec des directives équivalentes dans le HTML. La production publique définit explicitement true et SEO_INDEXING_ALLOWED_HOSTS=www.leclosdeseucalyptus.com.

La variante leclosdeseucalyptus.com redirige vers www.leclosdeseucalyptus.com ; elle ne figure pas dans la liste d’indexation. Une preview partageant l’application publique reste non indexable car le contrôle compare son hostname à cette liste exacte. Les domaines temporaires px-playground ne doivent pas être recopiés dans la configuration cible.

Le workflow officiel de promotion refuse une production dont le health check expose noindex. L’activation de l’indexation et le changement des URL de déploiement sont donc des opérations coordonnées avec la mise en ligne autorisée. Voir Domaines et indexation pour les valeurs actuelles confirmées par l’opérateur, les valeurs cibles et la recette HTTP.

Pendant la bascule des pages légales, conservez LEGAL_CONTENT_SOURCE=api et LEGAL_CONTENT_FALLBACK_ENABLED=true. Après vérification des trois versions publiées et des cinq locales, passez le fallback à false. En cas de rollback web, LEGAL_CONTENT_SOURCE=static remet immédiatement en service la copie française antérieure sans exposer de brouillon ; cette valeur doit rester temporaire et faire l’objet d’un incident suivi.

Backend PocketBase

Variable	Obligatoire	Valeur par défaut	Effet opérationnel
HARMONY_TOTP_ENCRYPTION_KEY	production	secret PocketBase des utilisateurs	chiffre les secrets TOTP existants
HARMONY_CALENDAR_ENCRYPTION_KEY	production	secret PocketBase des utilisateurs	chiffre les URL privées iCalendar
HARMONY_MEDIA_WIDTHS	non	profil applicatif	largeurs des variantes d’images
HARMONY_MEDIA_MAX_PIXELS	non	profil applicatif	limite de pixels décodés, maximum accepté : 200 000 000
HARMONY_AI_ENABLED	non	false	active la génération assistée
HARMONY_AI_PROVIDER	si IA	aucune	fournisseur d’infrastructure
HARMONY_AI_MODEL_ECONOMY	si IA	aucune	modèle faible coût
HARMONY_AI_MODEL_BALANCED	si IA	aucune	modèle courant
HARMONY_AI_MODEL_QUALITY	si IA	aucune	modèle haute qualité
HARMONY_AI_TRANSLATION_MODEL	OpenAI	aucune	modèle de proposition de traduction
HARMONY_OPENAI_API_KEY	OpenAI	aucune	clé secrète du fournisseur
HARMONY_OPENAI_BASE_URL	non	https://api.openai.com/v1	URL de l’API Responses
HARMONY_RELEASE_NOTIFICATION_TOKEN	production	aucune	authentifie la notification post-déploiement
HARMONY_AI_TRANSLATION_TIMEOUT	non	30s	timeout fournisseur
HARMONY_AI_TRANSLATION_MAX_INPUT_CHARS	non	40000	limite d’entrée
HARMONY_AI_TRANSLATION_MAX_OUTPUT_TOKENS	non	4096	limite de sortie

Les deux clés de chiffrement doivent rester stables. Les changer sans procédure de migration rend respectivement les secrets TOTP et les URL de calendrier existants illisibles. Le fallback PocketBase permet au service de démarrer, mais produit un avertissement et couple des usages qui doivent être isolés en production.

L’IA est désactivée par défaut. Quand elle est activée, une configuration incomplète fait échouer le démarrage afin d’éviter un fonctionnement ambigu. Les journaux et ai_runs ne doivent contenir ni clé, ni prompt complet, ni texte source, ni réponse générée.

Configuration métier dans PocketBase

Les paramètres SMTP sont stockés dans la collection configs, entrée email :

Champ	Contenu
smtp_host	nom d’hôte du serveur SMTP
smtp_port	port, généralement 587
smtp_user	identifiant
smtp_password	mot de passe
from_address	adresse d’expédition
from_name	nom affiché
contact_recipient	destinataire des demandes de contact
booking_recipient	destinataire des demandes de réservation

Sans configuration complète, l’envoi d’e-mails est désactivé avec un avertissement, mais le backend continue de servir les autres fonctions. L’identité visuelle des e-mails provient de l’entrée configs/site.

Portail documentaire

Variable	Phase	Obligatoire	Description
PUBLIC_DOCUMENTATION_URL	build	production	URL canonique Astro
PUBLIC_STORYBOOK_URL	build	recommandée	destination du lien Storybook
HARMONY_BACKEND_DIR	build local	local uniquement	checkout backend contenant docs/openapi.yaml
HARMONY_BACKEND_OPENAPI_URL	build	CI/Docker	source distante du contrat OpenAPI

Pour une release, pointez HARMONY_BACKEND_OPENAPI_URL vers un commit ou un tag immuable. Une URL de branche peut publier une référence API différente du backend effectivement déployé.

Matrice minimale par environnement

Sujet	Local	Preview PR	Staging	Production
données	seed déterministe	isolées ou non persistantes	jeu de validation sans PII	données réelles
clés de chiffrement	locales	dédiées	dédiées	dédiées et sauvegardées
API web	127.0.0.1:8090	backend coordonné ou staging	backend staging	backend production
indexation	sans importance	Access + noindex si isolée	noindex	activée explicitement
logs	verbeux, sans secret	durée courte	exploitables pour recette	rétention contrôlée
OpenAPI docs	checkout local	commit de la PR backend	commit déployé	tag de release

Une preview web qui modifie le contrat backend doit cibler la preview backend correspondante. Si ce couplage n’est pas disponible, elle doit utiliser un contrat rétrocompatible ou signaler clairement la limite de recette.

Rotation d’un secret

1. Identifiez tous les lecteurs et l’impact d’une rotation.
2. Vérifiez qu’une restauration de données récente existe.
3. Ajoutez la nouvelle valeur dans le coffre de l’environnement ciblé.
4. Redéployez uniquement les consommateurs concernés.
5. Testez l’authentification ou l’intégration associée.
6. Révoquez l’ancienne valeur côté fournisseur.
7. Consignez la date, le périmètre et l’opérateur, jamais la valeur.

Pour les clés TOTP et calendrier, une simple rotation n’est pas transparente : prévoyez une réinscription des utilisateurs ou une migration/rechiffrement revu avant de modifier la valeur.

Contrôle avant déploiement

• aucune valeur de production n’apparaît dans le diff Git ;
• aucun secret n’utilise un préfixe PUBLIC_ ;
• API_BASE_URL est joignable depuis le réseau du conteneur web ;
• les clés TOTP et calendrier sont présentes et inchangées ;
• les restrictions de domaine de MapTiler couvrent le nouveau domaine ;
• l’IA est soit entièrement configurée, soit explicitement désactivée ;
• la source OpenAPI correspond au backend qui sera déployé.