Update documentation for config/ migration, new install model, and firewall config API
Reflect config/ vs data/ split, install-time Jinja2 templating, auto-discovered paths, ZeroSSL/ACME support, and the new firewall save-then-apply API in all reference docs.
This commit is contained in:
+22
-10
@@ -6,7 +6,7 @@ Vacuum Wall is a zone-based firewall appliance with a built-in SSL reverse proxy
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
Vacuum Wall is built around four integrated subsystems managed through a central Flask web interface. The traffic plane uses firewalld with its nftables backend, supporting zone-based policies, source NAT, and destination NAT for port forwarding. The DNS/DHCP plane serves private subnets via dnsmasq, providing address allocation and local name resolution. The proxy plane runs nginx with automatic Let's Encrypt certificates through acme.sh, handling SSL termination and reverse proxying for backend services. The VPN plane uses WireGuard (wg-quick) for encrypted tunnel management. All subsystems are configured and monitored through the Flask web UI, which is itself proxied through nginx with basic HTTP authentication.
|
||||
Vacuum Wall is built around four integrated subsystems managed through a central Flask web interface. The traffic plane uses firewalld with its nftables backend, supporting zone-based policies, source NAT, and destination NAT for port forwarding. The DNS/DHCP plane serves private subnets via dnsmasq, providing address allocation and local name resolution. The proxy plane runs nginx with automatic ACME certificates through acme.sh, handling SSL termination and reverse proxying for backend services. The VPN plane uses WireGuard (wg-quick) for encrypted tunnel management. All subsystems are configured and monitored through the Flask web UI, which is itself proxied through nginx with basic HTTP authentication.
|
||||
|
||||
## Subsystems
|
||||
|
||||
@@ -20,7 +20,7 @@ dnsmasq serves as both the DHCP server and local DNS resolver. It is configured
|
||||
|
||||
### SSL Proxy
|
||||
|
||||
The nginx reverse proxy handles HTTPS termination for user-defined domains, with certificates automatically provisioned and renewed via acme.sh and Let's Encrypt. Each proxy domain is configured with an HTTP-to-HTTPS redirect, modern TLS settings, and a configurable backend target. New proxy domains are added through the web UI, and the configuration is applied without manual intervention.
|
||||
The nginx reverse proxy handles HTTPS termination for user-defined domains, with certificates automatically provisioned and renewed via acme.sh and an ACME provider (ZeroSSL by default). Each proxy domain is configured with an HTTP-to-HTTPS redirect, modern TLS settings, and a configurable backend target. New proxy domains are added through the web UI, and the configuration is applied without manual intervention.
|
||||
|
||||
### WireGuard
|
||||
|
||||
@@ -34,7 +34,7 @@ WireGuard support provides server-side VPN tunnel management. Peers are added th
|
||||
- nginx 1.26+
|
||||
- dnsmasq
|
||||
- WireGuard tools (wireguard-tools)
|
||||
- acme.sh for ACME/Let's Encrypt certificate management
|
||||
- acme.sh for ACME certificate management (ZeroSSL by default)
|
||||
- HTMX for dynamic UI updates
|
||||
- Jinja2 for server-side templating
|
||||
|
||||
@@ -43,24 +43,36 @@ WireGuard support provides server-side VPN tunnel management. Peers are added th
|
||||
To install Vacuum Wall on a Debian 13 system, run `install.sh` as root with the required environment variables:
|
||||
|
||||
```bash
|
||||
MGMT_DOMAIN=wall.lan MGMT_PASS=yourpassword ACME_EMAIL=admin@example.com \
|
||||
MGMT_PASS=yourpassword ACME_EMAIL=admin@example.com \
|
||||
bash install.sh
|
||||
```
|
||||
|
||||
After installation, access the management interface at `https://wall.lan` using the credentials you configured. The `install.sh` script provisions nginx, sets up authentication, obtains an initial Let's Encrypt certificate, and starts all services.
|
||||
After installation, access the management interface at `https://<hostname>.local` using the credentials you configured. The `install.sh` script auto-detects the system hostname (use `MGMT_DOMAIN` to override), provisions nginx, sets up authentication, generates an initial self-signed certificate, and starts all services.
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
├── install.sh # Deployment script
|
||||
├── install.sh # Deployment script (renders Jinja2 templates)
|
||||
├── pyproject.toml # Project metadata + dependencies
|
||||
├── .venv/ # Python virtual environment
|
||||
├── system/ # System file templates
|
||||
├── config/ # Declarative JSON configuration (source of truth)
|
||||
│ ├── dnsmasq/ # DHCP/DNS config
|
||||
│ ├── nginx/ # Proxy domain & SSL config
|
||||
│ └── wireguard/ # VPN interface & peer config
|
||||
├── data/ # Runtime artifacts & generated files
|
||||
│ ├── nginx/sites-enabled/ # Generated server blocks
|
||||
│ ├── dnsmasq/fragments/ # User config fragments
|
||||
│ ├── acme/ # ACME certificates
|
||||
│ └── firewall/ # Firewall rule backup
|
||||
├── system/ # System file templates (all Jinja2)
|
||||
│ ├── systemd/ # Service and timer unit files
|
||||
│ │ ├── vacuum-wall.service # Web UI service
|
||||
│ │ ├── vacuum-wall-acme.service # Certificate renewal service
|
||||
│ │ ├── vacuum-wall.service # Web UI service (rendered at install)
|
||||
│ │ ├── vacuum-wall-acme.service # Certificate renewal (rendered at install)
|
||||
│ │ └── vacuum-wall-acme.timer # Renewal schedule
|
||||
│ └── sudoers.d/ # Sudo whitelist for service account
|
||||
│ ├── sudoers.d/ # Sudo whitelist (rendered at install)
|
||||
│ ├── nginx/ # Nginx config templates (rendered at runtime)
|
||||
│ ├── dnsmasq.conf # Dnsmasq template (rendered at runtime)
|
||||
│ └── wireguard*.conf # WireGuard templates (rendered at runtime)
|
||||
├── lib/ # Subsystem abstraction layer
|
||||
│ ├── firewall.py # firewalld bindings
|
||||
│ ├── dnsmasq.py # DHCP/DNS configuration
|
||||
|
||||
Reference in New Issue
Block a user