Paul Payne
d009e095c0
- README.md: project overview, two sources of truth (config vs registrations), quick start, development, architecture - docs/registrations.md: complete API reference for service registrations — fields, types, defaults, what Central does per combination, examples for each use case Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
72 lines
2.7 KiB
Markdown
72 lines
2.7 KiB
Markdown
# 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 config** drives Central's own services — its UI domain, VPN, firewall, DHCP. These are managed through Central's web UI and config 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](docs/registrations.md) for the full registration API reference.
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
# Install
|
|
apt install wild-central
|
|
|
|
# Start
|
|
systemctl enable --now wild-central
|
|
|
|
# Access the web UI
|
|
open http://<device-ip>:5055
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
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.
|