CLAUDE.md

Project Overview

Wild Central is the networking and coordination platform for the Wild product family. It runs as a standalone service on a local network device (e.g., Raspberry Pi) and manages:

DNS (dnsmasq) — internal name resolution + optional DHCP
Gateway (HAProxy) — L4 SNI passthrough + L7 HTTP reverse proxy with TLS termination
Firewall (nftables) — host firewall rules
VPN (WireGuard) — remote access with peer management
TLS (certbot) — certificate provisioning via DNS-01
Tunnels (cloudflared) — outbound-only public exposure via Cloudflare
DDNS (Cloudflare) — A record + CNAME management
Security (CrowdSec) — intrusion detection
NATS JetStream — coordination bus for domain registration, presence, and events
Domain Registration — the contract API for Wild Cloud and Wild Works

Architecture

Wild Central is a Go service that manages Linux networking daemons via config file generation and systemctl commands. It provides an HTTP API and an embedded NATS JetStream server.

Consumers:

Wild Cloud — registers k8s instance domains for L4 SNI passthrough
Wild Works — registers domains for L7 HTTP reverse proxy with TLS termination

Both connect to Central's NATS (port 4222) or use the HTTP API (port 5055) to register services.

Development

make dev    # Run with live reloading (requires air)
make build  # Build binary
make test   # Run tests
make check  # Lint + test

Environment Variables

WILD_CENTRAL_DATA_DIR — Data directory (default: /var/lib/wild-central)
WILD_CENTRAL_PORT — API listen port (default: 5055)
WILD_CENTRAL_NATS_PORT — NATS listen port (default: 4222)
WILD_CENTRAL_DNSMASQ_CONFIG_PATH — dnsmasq config path
WILD_CENTRAL_HAPROXY_CONFIG_PATH — HAProxy config path
WILD_CENTRAL_NFTABLES_RULES_PATH — nftables rules path
WILD_CENTRAL_VPN_CONFIG_PATH — WireGuard config path
WILD_CENTRAL_CORS_ORIGINS — Allowed CORS origins
WILD_CENTRAL_STATIC_DIR — Web UI static files directory
WILD_CENTRAL_VITE_URL — Vite dev server URL for frontend proxying

Data Directory

Runtime state is persisted in {WILD_CENTRAL_DATA_DIR}/:

state.yaml — operator, domain, firewall, DDNS, DHCP settings (managed via API)
secrets.yaml — API tokens and credentials
domains/ — per-domain registration files
nats/ — embedded NATS JetStream data
instances/ — Wild Cloud instance configs

Domain Registration API

The key abstraction. Domains register with Central to get DNS, gateway routing, TLS, and public exposure.

POST   /api/v1/domains              Register a domain
GET    /api/v1/domains              List all domains
GET    /api/v1/domains/{domain}     Get domain details
PATCH  /api/v1/domains/{domain}     Update domain
DELETE /api/v1/domains/{domain}     Deregister domain

Domain payload

{
  "domain": "my-api.payne.io",
  "source": "wild-works",
  "backend": {
    "address": "192.168.8.60:9001",
    "type": "http",
    "health": "/health"
  },
  "public": false,
  "tls": "terminate"
}

Backend types

tcp-passthrough — L4, SNI routing, backend handles TLS (Wild Cloud k8s)
http — L7, Central terminates TLS with wildcard cert (Wild Works)
dns-only — DNS resolution only, no gateway routing (SSH, game servers, etc.)

Public

false (default) — LAN-visible only (DNS + gateway + TLS)
true — internet-visible (+ DDNS or tunnel exposure)

3.5 KiB Raw Permalink Blame History