Paul Payne
3c3d5be1ea
Document the project overview, architecture, development commands, environment variables, and the service registration API contract. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
89 lines
3.1 KiB
Markdown
89 lines
3.1 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 service registration, presence, and events
|
|
- **Service 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 services 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_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
|
|
|
|
## Service Registration API
|
|
|
|
The key abstraction. Services register with Central to get DNS, proxy, TLS, and public exposure.
|
|
|
|
```
|
|
POST /api/v1/services Register a service
|
|
GET /api/v1/services List all services
|
|
GET /api/v1/services/{name} Get service details
|
|
PATCH /api/v1/services/{name} Update service
|
|
DELETE /api/v1/services/{name} Deregister service
|
|
```
|
|
|
|
### Service payload
|
|
|
|
```json
|
|
{
|
|
"name": "my-api",
|
|
"source": "wild-works",
|
|
"domain": "my-api.payne.io",
|
|
"backend": {
|
|
"address": "192.168.8.60:9001",
|
|
"type": "http",
|
|
"health": "/health"
|
|
},
|
|
"reach": "internal",
|
|
"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 services)
|
|
- `static` — L7, static file serving (Wild Works frontends)
|
|
|
|
### Reach levels
|
|
|
|
- `off` — localhost only
|
|
- `internal` — LAN-visible (DNS + proxy + TLS)
|
|
- `public` — internet-visible (+ tunnel or direct exposure)
|