97 lines
3.5 KiB
Markdown
97 lines
3.5 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```json
|
|
{
|
|
"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)
|