diff --git a/.gitignore b/.gitignore index 3984d2d..4ea3644 100644 --- a/.gitignore +++ b/.gitignore @@ -16,5 +16,7 @@ __pycache__/ opencode.json # Runtime data configs (source-of-truth for services) -data/dnsmasq/config.json +config/dnsmasq/config.json +config/nginx/config.json +config/wireguard/config.json data/nginx/sites-enabled/ diff --git a/AGENTS.md b/AGENTS.md index 19cddfa..a7fdf5b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,7 +3,7 @@ ## What This Is SSL proxy / firewall appliance. Python 3 Flask WebUI behind nginx reverse proxy. -Deploys on Debian 13 (trixie). Target system: `/home/wall/vacuum-wall`. +Deploys on Debian 13 (trixie). Install dir: `/opt/vacuum-wall`. ## Architecture @@ -15,14 +15,17 @@ Flask ──→ lib/*.py ──→ sudo ──→ system service - `webui/server.py` — Flask app entry point. **Only** file that creates the `app`. - `webui/api/*.py` — Flask blueprints, one per subsystem. Routes prefix `/api//`. - `lib/*.py` — Backend modules. Wrap system commands via `subprocess.run(["sudo", ...])`. -- `data/` — Declarative JSON configs (source of truth). Generated `.conf` in `data/nginx/sites-enabled/`. +- `data/` — Runtime artifacts (generated .confs, `.htpasswd`, ACME certs, firewall backup, dnsmasq fragments). +- `config//config.json` — Declarative JSON configs (source of truth). Generated `.conf` in `data/nginx/sites-enabled/`. Certs in `data/acme/`. - `system/` — System file templates. `systemd/` (service units installed to `/etc/systemd/system/`), `sudoers.d/`, `nginx/`. Project uses `.venv`. Install deps with `pip install -e .` (from `pyproject.toml`). `__init__.py` files in `webui/` and `lib/` are intentionally empty — no `sys.path` boilerplate needed. -## Fixed Path +## Deployment -Every module hardcodes `/home/wall/vacuum-wall`. Changing it requires updating `lib/*.py`, `system/systemd/*.service`, `install.sh`, and `system/sudoers.d/vacuum-wall`. +`install.sh` deploys to `/opt/vacuum-wall` by rsyncing the repo. The `vacuum-wall` system user has `HOME=/opt/vacuum-wall` but no actual home directory (`--no-create-home`). + +All Python modules use `Path(__file__).resolve().parent.parent` for `PROJECT_DIR` — no hardcoded paths. ACME certs live at `PROJECT_DIR/data/acme/`. ## Local Dev @@ -46,6 +49,8 @@ In production the systemd unit runs as the `vacuum-wall` system user (`NoNewPriv `lib/` modules call `sudo` for everything that touches system services. Whitelist is `system/sudoers.d/vacuum-wall`. +**acme.sh must never run as root** — always as the service user via `sudo -u`. + Pattern for mutations: write JSON → render native config → `sudo ` to apply. Adding a new privileged command requires a sudoers entry **and** the `lib/` code. diff --git a/README.md b/README.md index 802150a..34ee62a 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ A zone-based firewall appliance with a built-in SSL reverse proxy. Combines fire - Debian 13 (trixie) target platform - Python 3.13+, Flask 3.x web UI - firewalld (nftables backend), dnsmasq, nginx, WireGuard -- acme.sh for Let's Encrypt +- acme.sh for ACME certificates (ZeroSSL) - HTMX + Jinja2 templates --- @@ -37,7 +37,7 @@ bash install.sh | `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 | Let's Encrypt registration email | +| `ACME_EMAIL` | Yes | ACME registration email (ZeroSSL by default) | After installation, access the WebUI at `https://`. The initial certificate is self-signed — use the Certs tab to issue a real one once DNS is propagating. @@ -45,7 +45,7 @@ After installation, access the WebUI at `https://`. The initial cer 1. **Assign interfaces** to zones from the Interfaces tab 2. **Configure DHCP** ranges for your LAN -3. **Add proxy domains** with Let's Encrypt certificates +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.