# Vacuum Wall

A zone-based firewall appliance with a built-in SSL reverse proxy. Combines firewalld policy control, DHCP/DNS, WireGuard VPN, and automated certificate provisioning into a single device managed through one web UI.

## Tech Stack

- Debian 13 (trixie) target platform
- Python 3.13+, Flask 3.x web UI
- firewalld (nftables backend), dnsmasq, nginx, WireGuard
- acme.sh for ACME certificates (ZeroSSL)
- HTMX + Jinja2 templates

---

## For Operators

### Prerequisites

- Clean Debian 13 system with root access
- git installed
- One public-facing NIC (external) and at least one LAN NIC (internal)
- A DNS A record pointing to the appliance's public IP for the management domain
- Minimum hardware: 1 CPU, 512 MB RAM, 4 GB disk

### Install

```bash
MGMT_DOMAIN=wall.example.com \
MGMT_PASS="strongpassword" \
MGMT_USER="admin" \
ACME_EMAIL="admin@example.com" \
bash install.sh
```

| Variable | Required | Description |
|---|---|---|
| `MGMT_DOMAIN` | Yes | Public domain for the management WebUI |
| `MGMT_PASS` | Yes | HTTP basic auth password for the WebUI |
| `MGMT_USER` | No | WebUI username (defaults to `admin`) |
| `ACME_EMAIL` | Yes | ACME registration email (ZeroSSL by default) |

After installation, access the WebUI at `https://<MGMT_DOMAIN>`. The initial certificate is self-signed — use the Certs tab to issue a real one once DNS is propagating.

### Next Steps

1. **Assign interfaces** to zones from the Interfaces tab
2. **Configure DHCP** ranges for your LAN
3. **Add proxy domains** with ACME certificates
4. **Set up WireGuard** (optional)

See [docs/deployment.md](docs/deployment.md) for the full guide, including troubleshooting.

---

## For Developers

### Local Development

```bash
git clone <repo-url> && cd vacuum-wall
python3 -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
```

Start the WebUI locally (binds to 127.0.0.1:9090):

```bash
.venv/bin/python webui/server.py
```

### Lint and Format

```bash
.venv/bin/ruff check lib/ webui/ tests/
.venv/bin/ruff format lib/ webui/ tests/
```

### Tests

```bash
.venv/bin/python -m pytest tests/ -v
```

Tests mock all subprocess calls (firewalld, acme.sh, WireGuard, nginx, dnsmasq) — no system services required.

### Documentation MCP Server

This project uses `docs-mcp-server` for grounded, real-time documentation lookups during development.

```bash
pipx install docs-mcp-server
docs-mcp init
```

Then run with Claude Code or Opencode to activate it. It automatically checks live docs before answering technical questions — no manual doc search needed.

### Architecture

```
Client ──→ nginx (SSL + basic auth) ──→ Flask (127.0.0.1:9090)
Flask ──→ lib/*.py ──→ sudo <cmd> ──→ system service
```

| Blueprint | URL prefix | Backend module |
|---|---|---|
| `webui/api/firewall` | `/api/firewall/` | `lib.firewall` |
| `webui/api/dhcp` | `/api/dhcp/` | `lib.dnsmasq` |
| `webui/api/proxy` | `/api/proxy/` | `lib.nginx` |
| `webui/api/certs` | `/api/certs/` | `lib.acme` |
| `webui/api/wireguard` | `/api/wireguard/` | `lib.wireguard` |

See [docs/architecture.md](docs/architecture.md) for detailed request flow and zone model.

---

## Documentation

- [Overview](docs/overview.md) — Feature summary and tech stack
- [Deployment Guide](docs/deployment.md) — Full installation and post-install configuration
- [Architecture](docs/architecture.md) — Request flow, subsystems, zone model
- [API Reference](docs/api.md) — REST API endpoints
- [Security Model](docs/security.md) — Privilege model and sudo whitelist
- [Configuration](docs/config.md) — Declarative config file formats and locations