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]>
78 lines
4.9 KiB
Markdown
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).
|