winzik/docs/domains.en.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

47 lines
3.3 KiB
Markdown

# A custom domain for a playground project
A project published on the playground (https://jumphp.net) can have **its own address**, e.g. `monapp.example.org`, served like
`bin/jumphp deploy` does: the project's site (`site/`) at the root (`{{DOMAIN}}` = the domain), the game or application in
`/play/`. The HTTPS certificate comes by itself at the first visit.
## For the project's owner
1. Studio → the project → **Custom domain** → the domain → **Add the domain**.
2. At the domain's DNS host, two records (the studio shows them, ready to copy):
```
monapp.example.org. CNAME apps.jumphp.net.
_jumphp.monapp.example.org. TXT "jumphp-verify=<the studio's token>"
```
- the CNAME points to the server, **without proxy** (Cloudflare: grey cloud, "DNS only"): the server must see the TLS connection
to get the certificate;
- the TXT proves the domain is yours;
- a root domain (no subdomain) cannot have a CNAME: give it the same IP addresses (A / AAAA) as `apps.jumphp.net`.
3. **Check the DNS** (propagation can take minutes; the studio says what is missing: the TXT, or the CNAME).
4. Depending on the playground's settings, the administrator **approves** the domain ("Waiting for the administrator"), or it is
online as soon as it is verified.
5. Open `https://monapp.example.org/`: the first visit makes the certificate (a few seconds).
Disabling the domain cuts it at once; Enable brings it back. A later failed check (CNAME removed) takes it offline. The domain always
serves the **published version**, and nothing of the portal (no studio, no sign-in, no cookie). The game asks its TCP tickets from its
own origin and opens `wss://<the domain>/tcp`: nothing to set.
## For the playground's administrator
Administration → **Partner sites and domains**: every domain, its state, **Check the DNS**, **Approve** / remove the approval,
**Block** (the owner cannot restore it), **Delete**.
How it is served: Traefik passes **only the served domains** through to the playground's Caddy (its HTTP provider reads
`http://jumphp-playground-internal:9180/api/domains/traefik`: a TCP `HostSNI(...)` passthrough router to `jumphp-playground-tls@docker`
and a port-80 router to `jumphp-playground-http@docker`). No low-priority `HostSNI(`*`)` catch-all: Traefik applies TCP routers
**before** the HTTP routers of the same entry point, so a catch-all would take the TLS of every other site of that Traefik. Caddy
(`docker/Caddyfile`) has an `https://` site (`CUSTOM_DOMAINS_SITE`) with `tls { on_demand }` and
`on_demand_tls { ask http://127.0.0.1:9180/api/domains/ask }`; `/api/domains/ask?domain=x` answers 200 only for a served domain
(verified, on, not blocked, approved when approval is required, project published).
Settings (`deploy/.env`): `CUSTOM_DOMAINS_SITE` (`https://` turns it on; default serves nothing), `CUSTOM_DOMAINS_TARGET`
(`apps.jumphp.net`), `CUSTOM_DOMAINS_APPROVAL` (`1`: the administrator approves each domain; `0`: the DNS check is enough),
`TRAEFIK_ENTRYPOINT`, `TRAEFIK_HTTP_ENTRYPOINT`.
Once: `apps.jumphp.net A <server IP>` (DNS only), Traefik's static configuration
`providers.http.endpoint: "http://jumphp-playground-internal:9180/api/domains/traefik"` (`pollInterval: "15s"`), then
`CUSTOM_DOMAINS_SITE=https://` in `deploy/.env` and a redeploy of the playground.