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

78 lines
4.9 KiB
Markdown

# 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 :
```yaml
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).