Previews, domaines et TLS

Les Preview Deployments de Dokploy permettent de construire chaque PR et de la rendre accessible sur un sous-domaine temporaire. Ils sont particulièrement utiles pour le web, Storybook et les changements backend compatibles avec une base isolée.

Convention de domaines

Exemple de répartition :

Usage	Modèle
web staging	preview.px-playground.fr
web PR	*.preview.px-playground.fr
backend staging	api-preview.px-playground.fr
backend PR	*.api-preview.px-playground.fr
Storybook PR	*.storybook-preview.px-playground.fr

Le nom exact généré par Dokploy peut inclure l’application, la branche et un identifiant. Ne codez pas une URL de preview précise dans l’application.

DNS wildcard

Pour chaque famille de previews :

1. créez un enregistrement wildcard *.preview… vers l’IP du serveur Dokploy ;
2. créez aussi l’enregistrement du domaine racine si celui-ci doit répondre ;
3. évitez un proxy CDN pendant le diagnostic initial du certificat ;
4. vérifiez la propagation avec dig depuis un réseau externe ;
5. activez ensuite le domaine wildcard dans la configuration Preview Deployment.

Un wildcard *.preview.example.test ne couvre pas preview.example.test et ne couvre qu’un niveau de sous-domaine.

Certificats

Dokploy/Traefik doit pouvoir répondre aux challenges ACME sur les ports publics et écrire son état de certificat. En cas de ERR_CERT_DATE_INVALID :

1. vérifiez l’heure système et la date d’expiration présentée par le serveur ;
2. confirmez que le DNS pointe vers la bonne machine ;
3. consultez les logs Traefik autour du renouvellement ACME ;
4. vérifiez les ports 80 et 443, la résolution IPv4/IPv6 et les limites Let’s Encrypt ;
5. corrigez la cause avant de forcer un nouveau renouvellement.

Ne supprimez pas le stockage ACME comme premier réflexe : cela oublie tous les certificats et peut déclencher une réémission massive.

Configuration d’une preview web

• branche cible de la PR : develop ;
• domaine wildcard web ;
• variables publiques adaptées aux domaines temporaires ;
• API_BASE_URL vers un backend de preview coordonné ou vers staging ;
• données sans information personnelle ;
• durée de vie limitée à celle de la PR.

Si Vite sert directement un build de preview, le domaine doit être autorisé dans preview.allowedHosts. Pour un serveur de production SvelteKit ou un proxy statique, ce réglage ne doit pas se substituer à une vraie configuration d’hôte et d’origine.

Configuration d’une preview backend

Le conteneur doit écouter sur 0.0.0.0:8090, exposer le port 8090 à Dokploy et répondre sur /api/health. Une Bad Gateway avec un build réussi signifie généralement :

• processus arrêté après le build ;
• mauvais port interne ;
• serveur lié à 127.0.0.1 dans le conteneur ;
• volume non inscriptible ;
• configuration invalide au démarrage ;
• health check trop strict ou démarré trop tôt.

Inspectez d’abord les logs d’exécution et l’état du conteneur, pas uniquement les logs de build.

Recette d’une PR cross-stack

PR backend ─→ preview API isolée ─┐
                                  ├─→ parcours de recette
PR web ─────→ preview web ────────┘

Consignez l’URL backend utilisée dans la PR web. Fermer une PR doit supprimer ses routes et conteneurs de preview ; les volumes temporaires doivent avoir une politique de rétention explicite.

Checklist

• DNS A/AAAA résout vers le serveur attendu ;
• certificat valide pour le nom exact ;
• preview non indexable ;
• aucune donnée ou clé de production ;
• backend sain et port correctement routé ;
• web connecté au backend attendu ;
• commentaire de PR contenant l’URL et les limites de recette ;
• suppression automatique à la fermeture de la PR.