Paul Payne
a0ab8faa1c
SafeApply pattern (validate → backup → write → reload → verify → rollback): - HAProxy: SafeApply wraps existing validate+write+reload with backup and post-reload health check; rolls back to .bak on failure - dnsmasq: SafeApply validates via dnsmasq --test, backs up, atomic writes, restarts, verifies daemon is active; rolls back on failure - nftables: SafeApply validates via nft -c, backs up, atomic writes, applies to kernel, verifies table loaded; rolls back on failure Health tracking: - Add SubsystemHealth and Health structs to reconciler - Track per-subsystem status (ok/degraded/error) after each reconcile - Detect recovery: previous error → current ok broadcasts recovery event - GET /api/v1/health/reconcile endpoint exposes health state - HAProxy tracks excluded domains as "degraded" state SSE error events: - Broadcast haproxy:error, dnsmasq:error on SafeApply failure - Broadcast haproxy:recovered, dnsmasq:recovered on recovery from error Convergence loop: - 5-minute periodic reconcile drives system toward desired state - Catches config drift, daemon crashes, transient failures - Serialized by reconcile mutex — no race with event-driven reconciles Startup: - CheckPrerequisites verifies required (dnsmasq, haproxy) and optional (wg, authelia, cscli, cloudflared, nft) binaries before first reconcile
Wild Central
Wild Central is a networking platform for your LAN. It manages DNS, proxy routing, TLS certificates, VPN, firewall, and dynamic DNS — providing a unified networking layer for self-hosted services.
What it does
Wild Central runs on a device on your LAN (e.g., a Raspberry Pi) and manages:
- DNS (dnsmasq) — internal name resolution, split DNS, DHCP
- Gateway (HAProxy) — L4 SNI passthrough for k8s clusters, L7 reverse proxy for HTTP services
- TLS (certbot) — certificate provisioning via Let's Encrypt DNS-01
- VPN (WireGuard) — remote access with peer management
- Firewall (nftables) — host firewall rules
- DDNS (Cloudflare) — dynamic DNS A record management
- Security (CrowdSec) — intrusion detection
- NATS JetStream — coordination bus for service registration and events
Two sources of truth
Central state drives Central's own services — its UI domain, VPN, firewall, DHCP. These are managed through Central's web UI and state file.
Service registrations drive external consumer services. Wild Cloud registers its k8s instance domains. Wild Works registers its program services. Each registration is a domain that needs routing through Central's networking stack.
See docs/registrations.md for the full registration API reference.
Quick start
# Install
apt install wild-central
# Start
systemctl enable --now wild-central
# Access the web UI
open http://<device-ip>:5055
Development
make dev # Run with live reloading (requires air)
make build # Build binary
make test # Run tests
make check # Lint + test
Environment variables
| Variable | Default | Description |
|---|---|---|
WILD_CENTRAL_ENV |
— | Set to development for dev mode (Vite proxy) |
WILD_CENTRAL_DATA_DIR |
/var/lib/wild-central |
Data directory |
WILD_CENTRAL_PORT |
5055 |
API listen port |
WILD_CENTRAL_NATS_PORT |
4222 |
NATS JetStream port |
WILD_CENTRAL_VITE_URL |
http://localhost:5173 |
Vite dev server URL |
Architecture
Wild Central (this service)
├── Config-driven: DNS, VPN, firewall, DHCP, TLS for Central's own domain
├── Registration-driven: DNS, proxy, TLS, DDNS for consumer domains
├── NATS JetStream: coordination bus
└── Web UI: management interface
Wild Cloud ──registers domains──→ Wild Central
Wild Works ──registers domains──→ Wild Central
Wild Cloud and Wild Works are separate services that register their domains with Central. Central handles all the networking — DNS resolution, proxy routing, TLS certificates, and external DNS records.