Skip to content

Publish at a hostname

Publish a reef's endpoint, here Triton, at a hostname of your own domain, while Nereus runs on your machine behind a Cloudflare tunnel.

Before you start

  • A cluster from Prepare the cluster with the secrets reef: the Nereid cloudflare requires it, and makes the vault edge.
  • A domain, a Cloudflare account on the free plan, and a named tunnel's credentials from cloudflared tunnel create nereus, in ~/.cloudflared/<UUID>.json.

Steps

1. Apply the edge reef

nereus reef apply edge adds the kinds Zone, Domain and Route.

nereus reef apply edge
output
✓ core/reefs/edge 0.1.0 created

2. Apply the Nereid cloudflare

nereus nereid apply cloudflare runs the zone and the tunnel.

nereus nereid apply cloudflare --reef edge
output
✓ core/nereids/cloudflare created, Ready

3. Keep the tunnel's credentials and name the tunnel

Keep the credentials file as the secret edge/cloudflare-tunnel with nereus secrets create edge/cloudflare-tunnel --from-file credentials.json=<file> (Keep a secret). Then the Mandate names the tunnel and that secret.

nereus mandate create cloudflare \
  --reef edge \
  --nereid cloudflare \
  --param tunnel=nereus \
  --param credentialsSecret=edge/cloudflare-tunnel \
  --default
output
✓ core/mandates/cloudflare created (reef: edge, nereid: cloudflare, default)

4. Delegate the domain

nereus edge zone create makes the zone and prints its nameservers; point your registrar at them.

nereus edge zone create getnereus.dev --mandate cloudflare
output
✓ edge/zones/getnereus.dev created, waiting for its delegation
  nameservers: ada.ns.cloudflare.com, bob.ns.cloudflare.com
  point the registrar of getnereus.dev at them; the zone turns Active once Cloudflare sees it

Changing the registrar from Nereus waits for the Nereid godaddy planned (#475).

5. Carry the hostname through the tunnel

nereus edge route create carries a hostname to the ingress gateway. Create the routes right after the Mandate: until one exists, the tunnel answers 404 for every hostname.

nereus edge route create triton --hostname triton.getnereus.dev
output
✓ edge/routes/triton created, Ready: https://triton.getnereus.dev

A route may also name the endpoint a reef publishes, never a cluster, a namespace, a Service or a port (#1951). nereus edge endpoint list shows every endpoint the Nereids publish, with the hostnames each one serves; none is published by default. The Nereid's own apply grants one, then the route names it:

nereus edge endpoint list
nereus nereid apply triton --reef messaging --publish mcp
nereus edge route create triton --hostname triton.getnereus.dev --endpoint messaging/mcp

The tunnel carries the hostname only when the endpoint is publishable, granted and served on that hostname; otherwise the route says why (NotPublished, NotServed, NoEndpoint, or Exposes when the hostname also serves an endpoint that may not leave the cluster: the tunnel carries the whole hostname). The kept cluster's routes move to endpoints with #2011.

Check it worked

nereus edge zone list shows the zone Active once the delegation arrives, and nereus edge route list shows every hostname the platform answers; then https://triton.getnereus.dev answers.

nereus edge route list
output
NAME     HOSTNAME               ENDPOINT  MANDATE     READY   URL
auth     auth.getnereus.dev     -         cloudflare  True    https://auth.getnereus.dev
portal   portal.getnereus.dev   -         cloudflare  True    https://portal.getnereus.dev
triton   triton.getnereus.dev   -         cloudflare  True    https://triton.getnereus.dev

Next

Learn more

  • With a Cloudflare API token in a secret of the vault edge (--param apiTokenSecret=edge/cloudflare-token on the Mandate), the Nereid creates or adopts the tunnel itself, with no cloudflared tunnel create (#1961, deploy/edge/README.md).
  • ADR 0005: Nereids publish their endpoints and commands in status.