mteehan/vacuum-wall
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: unify project structure, improve security, and enhance deployment

Browse Source 
- Fix WireGuard private key leak in API responses and config updates
- Update systemd service to serve from repo root with adjusted sandbox
- Add CLI flags, idempotency, and dev mode to install.sh
- Extract common utilities to lib/common.py and webui/api/common.py
- Migrate frontend to htmx for simpler, more maintainable UI
- Update docs to reflect current architecture and deployment model
- Vendor htmx dependencies per project requirements
This commit is contained in:
Mike Teehan
2026-05-25 00:53:32 +00:00
parent 8829ac579d
commit d1ab717c0f
36 changed files with 857 additions and 626 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+28 -10
View File
@@ -22,7 +22,7 @@ A zone-based firewall appliance with a built-in SSL reverse proxy. Combines fire
- 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
### Install (Production)
```bash
MGMT_DOMAIN=wall.example.com \
@@ -32,12 +32,28 @@ 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) |
### Install (Development)
```bash
./install.sh --dev --mgmt-pass strongpassword --acme-email "admin@example.com"
```
`--dev` auto-detects the repo's file owner as the service user, skips the safety warning about running as a regular user, and keeps file ownership dev-friendly.
| Flag | Env Var | Required | Description |
|---|---|---|---|
| -- | `MGMT_DOMAIN` | No | Public domain for the management WebUI (auto-detected as `hostname.local`) |
| `--mgmt-pass` | `MGMT_PASS` | Yes | HTTP basic auth password for the WebUI |
| `--mgmt-user` | `MGMT_USER` | No | WebUI username (defaults to `admin`) |
| `--acme-email` | `ACME_EMAIL` | Yes | ACME registration email (ZeroSSL by default) |
| `--user, -u` | `USER_NAME` | No | System user for service (default: `vacuum-wall`) |
| `--path, -p` | `INSTALL_DIR` | No | Install directory (default: repo root) |
| `--dev` | -- | No | Auto-detect repo owner as service user, skip safety warning |
| `--mgmt-domain` | `MGMT_DOMAIN` | No | (alias for env var) |
| `--wan-iface` | `WAN_IFACE` | No | WAN interface (auto-detected) |
| `--lan-ifaces` | `LAN_IFACES` | No | LAN interfaces, comma-separated (auto-detected) |
CLI flags take precedence over environment variables. Run `./install.sh --help` for full usage.
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.
@@ -75,13 +91,15 @@ Start the WebUI locally (binds to 127.0.0.1:9090):
.venv/bin/ruff format lib/ webui/ tests/
```
All `lib/` modules share `lib.common` utilities (`run`, `run_proc`, `load_json`, `save_json`, `deep_merge`, `ensure_dirs`) and have full type hints and `__all__` exports. API blueprints share `_ok`/`_error` from `webui.api.common`.
### Tests
```bash
.venv/bin/python -m pytest tests/ -v
```
Tests mock all subprocess calls (firewalld, acme.sh, WireGuard, nginx, dnsmasq) — no system services required.
Tests mock all subprocess calls (firewalld, acme.sh, WireGuard, nginx, dnsmasq) — no system services required. 192 tests across 5 test modules.
### Documentation MCP Server
@@ -109,7 +127,7 @@ Flask ──→ lib/*.py ──→ sudo <cmd> ──→ system service
| `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.
See [docs/architecture.md](docs/architecture.md) for detailed request flow, zone model, and shared utility patterns.
---
@@ -117,7 +135,7 @@ See [docs/architecture.md](docs/architecture.md) for detailed request flow and z
- [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
- [Architecture](docs/architecture.md) — Request flow, subsystems, zone model, shared utilities
- [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