N
Nanami Docs
Browse docs
Browse docs
Browse docs

Documentation

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

Section
Browse docs
Path
/deployment/domain-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
  • NANAMI_GATEWAY_ENDPOINT_DNS_MODE
  • NANAMI_DNS_BASE_DOMAIN
  • NANAMI_DNS_GATEWAY_HOST_TEMPLATE
  • NANAMI_GATEWAY_PUBLIC_IP
  • NANAMI_GATEWAY_PUBLIC_IPV6
  • NANAMI_GATEWAY_ENDPOINT_PORT
  • 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 runtime endpoints use NANAMI_GATEWAY_ENDPOINT_DNS_MODE. manual is the default. SaaS and Community use the generic endpoint template under NANAMI_DNS_BASE_DOMAIN. NANAMI_GATEWAY_PUBLIC_IP is the origin content for the DNS record, not a hostname override. OVERLAY_DNS_IP defines the DNS server inserted into node WireGuard configs.

Community example

bash
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
NANAMI_GATEWAY_ENDPOINT_DNS_MODE=manual
NANAMI_DNS_BASE_DOMAIN=example.com
NANAMI_DNS_GATEWAY_HOST_TEMPLATE=gateway-daemon-{gateway_id_short}-c-nanami
NANAMI_GATEWAY_PUBLIC_IP=203.0.113.10
OVERLAY_DNS_IP=100.64.0.10

SaaS example

bash
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
NANAMI_GATEWAY_ENDPOINT_DNS_MODE=manual
NANAMI_DNS_BASE_DOMAIN=example.com
NANAMI_DNS_GATEWAY_HOST_TEMPLATE=gateway-daemon-{gateway_id_short}-s-nanami
NANAMI_GATEWAY_PUBLIC_IP=203.0.113.10
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 endpoint DNS is protocol-neutral and supports:

  • manual: operator creates DNS-only records; Nanami validates and reports.
  • cloudflare: Nanami manages DNS-only Cloudflare records.

Gateway public IP is operator-provided through NANAMI_GATEWAY_PUBLIC_IP. Nanami does not auto-detect public IP in this release because NAT, load balancers, Kubernetes services, floating IPs, and router port forwarding can make outbound detection incorrect.

Gateway host format uses NANAMI_DNS_GATEWAY_HOST_TEMPLATE under NANAMI_DNS_BASE_DOMAIN in both manual and Cloudflare modes.

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.
  • Gateway runtime endpoint configuration is supported only through the canonical NANAMI_* endpoint keys.

DNS / Cloudflare Warning

For gateway DNS records:

  • Use DNS only mode.
  • Do not enable Cloudflare proxy for gateway endpoints.
  • WireGuard UDP and GRE require direct DNS-only records unless a protocol-capable proxy product is explicitly configured and proven.
  • See Gateway endpoint DNS modes for manual and Cloudflare-managed modes.
  • Required inbound reachability: WireGuard uses UDP 51820 or the configured port; GRE uses IP protocol 47 when enabled.

Community and SaaS usage

  • Community:
    • one workspace-level status page at STATUS_HOST
    • operator controls or explicitly automates gateway endpoint DNS and UDP forwarding
  • SaaS:
    • platform/global status page at STATUS_HOST
    • platform roles gate access to platform status views
    • gateway endpoints use the generic endpoint DNS contract

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:

bash
make verify-env

Validation enforces:

  • required domain keys are present,
  • hosts are host-only (no scheme/path),
  • gateway endpoint DNS mode is valid,
  • Cloudflare credentials are required only for Cloudflare mode,
  • explicit Community endpoint configuration is validated when no generic endpoint template is configured,
  • gateway endpoint pattern uses generic template or manual explicit host/IP fallback.