winzik/docs/domains.md
David Nurdin 87ad5126aa Embed kit and docs: a playground application on a partner's site without iframe nor CORS, and custom domains
tools/embed/jumphp-embed.php: one PHP file (7.4+, curl) that signs the requests to the
playground's /api/embed/<slug>/ (HMAC-SHA256 over method, path, query, time and body
hash), serves the application under the partner's base path (streamed, Range, gzip
passed through, immutable files kept on disk), relays the TCP tickets with the
visitor's address, and gives the blocks (disk cache, ETag revalidation, last copy when
the playground is down); no cookie either way, security headers. Its end-to-end test
(tools/embed/tests/test.sh, Docker), the WordPress plugin (shortcode
[jumphp_block app block], the base path answered at plugins_loaded, settings page,
secret possibly in wp-config.php), nginx / Caddy / plain PHP examples.

docs/embed.md (+ .en), docs/domains.md (+ .en), AGENTS.md section 14.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-11-14 02:41:11 +01:00

4.9 KiB

Un domaine personnalisé pour un projet du playground

Un projet publié sur le playground (https://jumphp.net) peut avoir sa propre adresse, par exemple monapp.example.org, servie comme le fait bin/jumphp deploy : le site du projet (site/) à la racine ({{DOMAIN}} = le domaine), le jeu ou l'application dans /play/. Le certificat HTTPS est obtenu tout seul, à la première visite.

Pour le propriétaire du projet

  1. Studio → le projet → Domaine personnalisé → le domaine → Ajouter le domaine.
  2. Chez l'hébergeur DNS du domaine, deux enregistrements (le studio les affiche, prêts à copier) :
    monapp.example.org.          CNAME  apps.jumphp.net.
    _jumphp.monapp.example.org.  TXT    "jumphp-verify=<le jeton du studio>"
    
    • le CNAME pointe vers le serveur ; sans proxy (chez Cloudflare : nuage gris, « DNS seul ») : le serveur doit voir la connexion TLS pour obtenir le certificat ;
    • le TXT prouve que le domaine est à vous ;
    • un domaine racine (example.org sans sous-domaine) ne peut pas avoir de CNAME : donnez-lui les mêmes adresses IP (A / AAAA) que apps.jumphp.net.
  3. Vérifier le DNS (la propagation peut prendre quelques minutes ; le studio dit ce qui manque : le TXT, ou le CNAME).
  4. Selon la configuration du playground, l'administrateur approuve le domaine (état « En attente de l'administrateur »), ou il est en ligne dès la vérification.
  5. Ouvrez https://monapp.example.org/ : la première visite fait le certificat (quelques secondes).

Désactiver le domaine le coupe aussitôt (plus de certificat, plus de réponse) ; Activer le remet. Une nouvelle vérification qui échoue (le CNAME retiré) le met hors ligne. Le domaine sert toujours la version publiée (pas de brouillon, pas d'ancienne version), et rien du portail : ni studio, ni connexion, ni cookie.

Le jeu y demande ses tickets TCP à sa propre origine (https://monapp.example.org/api/tcp/ticket) et ouvre le pont wss://monapp.example.org/tcp : rien à régler.

Pour l'administrateur du playground

Administration → Sites partenaires et domaines : tous les domaines, leur état, Vérifier le DNS, Approuver / retirer l'approbation, Bloquer (le propriétaire ne peut pas le rétablir), Supprimer.

Comment c'est servi

visiteur ──TLS (SNI monapp.example.org)──► Traefik :443 ──passthrough──► Caddy du conteneur app
                                             (routeurs lus sur              │  certificat à la demande
                                              /api/domains/traefik)         │  (on_demand_tls, ask → /api/domains/ask)
                                                                            ▼
                                                   Symfony : CustomDomainController (/ = site, /play/ = le projet)
  • Traefik ne passe au Caddy du playground que les domaines servis : son fournisseur HTTP lit http://jumphp-playground-internal:9180/api/domains/traefik (routeur TCP HostSNI(...) en passthrough vers le service jumphp-playground-tls@docker, et routeur HTTP du port 80 vers jumphp-playground-http@docker pour le défi ACME HTTP et la redirection). Pas de routeur HostSNI(*) de priorité basse : dans Traefik les routeurs TCP passent avant les routeurs HTTP d'un même point d'entrée, un attrape-tout prendrait le TLS de tous les autres sites de ce Traefik.
  • Caddy (docker/Caddyfile) : un bloc https:// (variable CUSTOM_DOMAINS_SITE) avec tls { on_demand }, et on_demand_tls { ask http://127.0.0.1:9180/api/domains/ask } : il ne demande un certificat que si le playground répond 200. L'écoute interne :9180 ne répond qu'à /api/domains/ask et /api/domains/traefik et n'est publiée nulle part.
  • Le playground : /api/domains/ask?domain=x répond 200 pour un domaine servi (vérifié, actif, non bloqué, approuvé si l'approbation est exigée, projet publié), 404 sinon. Les requêtes d'un domaine servi passent par leur propre pare-feu (pas de session), sans les redirections de langue du portail.

Variables (deploy/.env) :

Variable Défaut
CUSTOM_DOMAINS_SITE https://custom-domains.localhost (rien de servi) https:// pour activer
CUSTOM_DOMAINS_TARGET apps.jumphp.net le nom vers lequel pointent les CNAME
CUSTOM_DOMAINS_APPROVAL 1 1 : l'administrateur approuve chaque domaine ; 0 : la vérification DNS suffit
TRAEFIK_ENTRYPOINT, TRAEFIK_HTTP_ENTRYPOINT les points d'entrée nommés dans /api/domains/traefik

Mise en place (une fois) : l'enregistrement apps.jumphp.net A <IP du serveur> en DNS seul, le fournisseur HTTP dans la configuration statique de Traefik :

providers:
  http:
    endpoint: "http://jumphp-playground-internal:9180/api/domains/traefik"
    pollInterval: "15s"

puis CUSTOM_DOMAINS_SITE=https:// dans deploy/.env et un redéploiement du playground (migrations au démarrage).