Domain and URL strategy

title: Domain and URL strategy description: Deterministic public host and gateway transport contract for Community and SaaS deployments.

Nanami uses one public-host contract for browser/API surfaces and one transport contract for gateway UDP endpoints.

Domain Contract

Contract keys:

• BASE_DOMAIN
• DASHBOARD_HOST
• API_HOST
• DOCS_HOST
• MARKETING_HOST
• STATUS_HOST
• GATEWAY_DOMAIN
• GATEWAY_ENDPOINT
• GATEWAY_HOST
• OVERLAY_DNS_IP

BASE_DOMAIN is required in both modes. DASHBOARD_HOST/API_HOST/DOCS_HOST/MARKETING_HOST/STATUS_HOST can be explicit or derived by mode defaults. GATEWAY_DOMAIN is required in SaaS and recommended in Community. Community may leave GATEWAY_DOMAIN empty only when it intentionally sets GATEWAY_ENDPOINT or GATEWAY_HOST for the explicit no-domain compatibility fallback. OVERLAY_DNS_IP defines the DNS server inserted into node WireGuard configs.

Community example

BASE_DOMAIN=example.com
DASHBOARD_HOST=app-c-nanami.example.com
API_HOST=api-c-nanami.example.com
DOCS_HOST=docs-c-nanami.example.com
MARKETING_HOST=nanami.example.com
STATUS_HOST=status-c-nanami.example.com
GATEWAY_DOMAIN=gateway-{id}-c-nanami.example.com
OVERLAY_DNS_IP=100.64.0.10

Community no-domain fallback example:

BASE_DOMAIN=example.com
DASHBOARD_HOST=app-c-nanami.example.com
API_HOST=api-c-nanami.example.com
DOCS_HOST=docs-c-nanami.example.com
MARKETING_HOST=nanami.example.com
STATUS_HOST=status-c-nanami.example.com
GATEWAY_DOMAIN=
GATEWAY_ENDPOINT=gateway.example.com:51820
OVERLAY_DNS_IP=100.64.0.10

SaaS example

BASE_DOMAIN=example.com
DASHBOARD_HOST=app-s-nanami.example.com
API_HOST=api-s-nanami.example.com
DOCS_HOST=docs-s-nanami.example.com
MARKETING_HOST=nanami.example.com
STATUS_HOST=status-s-nanami.example.com
GATEWAY_DOMAIN=gateway-{id}-s-nanami.example.com
OVERLAY_DNS_IP=100.64.0.10

Canonical URL layout

• Dashboard: https://${DASHBOARD_HOST}
• API: https://${API_HOST}
• Docs: https://${DOCS_HOST}
• Marketing: https://${MARKETING_HOST}
• Status page: https://${STATUS_HOST}

Reverse proxy contract

• Put browser/API HTTP surfaces behind a reverse proxy:
  • DASHBOARD_HOST
  • API_HOST
• Keep gateway UDP transport direct. Reverse proxies do not replace the current WireGuard transport endpoint contract.
• Published gateway domains are transport endpoint names, not a general service-publishing feature.

Gateway Endpoint Contract

Gateway host format supports both published-domain modes:

• Template mode (recommended): <template with {id} replaced>:<port>
• Legacy mode: gw-<shortId>.<GATEWAY_DOMAIN>:<port>

Example:

• gateway id: 8b7a1e86-88f3-4f6a-9a8b-3d1fd9cbb9b1
• endpoint host: gateway-8b7a1e8688f3-c-nanami.example.com
• endpoint: gateway-8b7a1e8688f3-c-nanami.example.com:51820

Important:

• Gateway endpoint host is never derived from gateway display name.
• Gateway names are metadata only.
• When both GATEWAY_ENDPOINT and GATEWAY_HOST are set, the explicit GATEWAY_ENDPOINT value wins.
• The Community no-domain fallback is a compatibility path for bring-up and lab installs. It is not the recommended long-term production posture.

DNS / Cloudflare Warning

For gateway DNS records:

• Use DNS only mode.
• Do not enable Cloudflare proxy for gateway endpoints.
• WireGuard UDP requires direct DNS-only records.

Community and SaaS usage

• Community:
  • one workspace-level status page at STATUS_HOST
  • operator controls gateway DNS and UDP forwarding
  • operator may choose the explicit no-domain gateway fallback for compatibility
• SaaS:
  • platform/global status page at STATUS_HOST
  • platform roles gate access to platform status views
  • published gateway domains remain required

Explicitly out of scope

• arbitrary service publishing through custom domains, paths, or ports
• a general HTTP/TCP/UDP publishing control plane
• teaching ingress/egress routing policy as if it were app publishing

Validation

Run:

make verify-env

Validation enforces:

• required domain keys are present,
• hosts are host-only (no scheme/path),
• Community no-domain fallback is explicit when GATEWAY_DOMAIN is empty,
• SaaS still requires GATEWAY_DOMAIN,
• gateway endpoint pattern uses either template mode or legacy mode when a published gateway domain is configured.