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

Update .gitignore, AGENTS.md, README.md for config/ split and deployment model

Browse Source
This commit is contained in:
Mike Teehan
2026-05-14 03:32:06 +00:00
parent dcb581a359
commit 0e7090a2cb
3 changed files with 15 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+9 -4
View File
@@ -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 <cmd> ──→ 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/<subsystem>/`.
- `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/<subsystem>/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 <cmd>` to apply.
Adding a new privileged command requires a sudoers entry **and** the `lib/` code.