Nanami DocsGuide
Search docsFilter pages by title

Domain and URL strategy

Nanami uses one domain contract for all public surfaces.

Domain Contract

Contract keys:

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

BASE_DOMAIN and GATEWAY_DOMAIN are required. DASHBOARD_HOST/API_HOST/DOCS_HOST/MARKETING_HOST/STATUS_HOST can be explicit or derived by mode defaults. OVERLAY_DNS_IP defines the DNS server inserted into node WireGuard configs.

Community example

bash
BASE_DOMAIN=example.com
DASHBOARD_HOST=dashboard-c-nanami.example.com
API_HOST=control-plane-c-nanami.example.com
DOCS_HOST=documentation-s-nanami.example.com
MARKETING_HOST=marketing-s-nanami.example.com
STATUS_HOST=status-c-nanami.example.com
GATEWAY_DOMAIN=gateway-daemon-{id}-c-nanami.example.com
OVERLAY_DNS_IP=100.64.0.10

SaaS example

bash
BASE_DOMAIN=example.com
DASHBOARD_HOST=dashboard-s-nanami.example.com
API_HOST=control-plane-s-nanami.example.com
DOCS_HOST=documentation-s-nanami.example.com
MARKETING_HOST=marketing-s-nanami.example.com
STATUS_HOST=status-s-nanami.example.com
GATEWAY_DOMAIN=gateway-daemon-{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}

Gateway Endpoint Contract

Gateway host format supports both 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-daemon-8b7a1e8688f3-c-nanami.example.com
  • endpoint: gateway-daemon-8b7a1e8688f3-c-nanami.example.com:51820

Important:

  • Gateway endpoint host is never derived from gateway display name.
  • Gateway names are metadata only.

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 tenant-level status page at STATUS_HOST
    • operator controls gateway DNS and UDP forwarding
  • SaaS:
    • platform/global status page at STATUS_HOST
    • platform roles gate access to platform status views

Validation

Run:

bash
make verify-env

Validation enforces:

  • required domain keys are present,
  • hosts are host-only (no scheme/path),
  • gateway endpoint pattern uses either template mode or legacy mode.
Edit this page