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]>
47 lines
3.3 KiB
Markdown
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.
|