mteehan/vacuum-wall
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
37039351be050287add5f4eeffd86db3ed4e281e
vacuum-wall/docs/deployment.md
T
mteehan dcb581a359 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.
2026-05-14 03:31:59 +00:00

13 KiB
Raw Blame History

Deployment Guide

This guide walks through deploying Vacuum Wall on a real appliance or server. Vacuum Wall is an SSL proxy firewall appliance that combines edge proxying, firewall management, DHCP, DNS, and WireGuard in a single device.

Prerequisites

  • OS: Clean Debian 13 (Trixie) system. Also works on Debian 12 with backports for firewalld.
  • git: Required for cloning the repository.
  • Access: Root access to the machine.
  • Networking:
    • One public-facing network interface (external/edge). This receives inbound traffic and serves the management UI.
    • At least one LAN network interface (internal). This connects to your downstream network and will serve DHCP/DNS.
  • DNS: A DNS record pointing to the appliance's public IP for the management domain (e.g., wall.example.com).
  • Minimum hardware: 1 CPU, 512 MB RAM, 4 GB disk.

Installation

Download the Vacuum Wall repository onto the target machine, then run the installer with the required environment variables:

# Option A: Public DNS
PROJECT_DIR="/opt/vacuum-wall" \
USER_NAME="vacuum-wall" \
MGMT_DOMAIN=wall.example.com \
MGMT_PASS="strongpassword" \
MGMT_USER="admin" \
ACME_EMAIL="admin@example.com" \
bash install.sh

# Option B: mDNS (LAN-only, no DNS record needed)
MGMT_DOMAIN=vacuum-wall.local \
MGMT_PASS="strongpassword" \
MGMT_USER="admin" \
ACME_EMAIL="admin@example.com" \
bash install.sh

Environment Variables

Variable Required Description
PROJECT_DIR No Directory where the project resides. Auto-discovers from install.sh location if not set.
USER_NAME No System user that runs the WebUI service. Defaults to vacuum-wall.
MGMT_DOMAIN No The domain for the management WebUI. Defaults to $hostname.local (auto-detected from the system hostname), which works with mDNS on your LAN (avahi-daemon is installed and enabled automatically). Set explicitly for a custom DNS domain (e.g., wall.example.com). Errors if hostname is undetectable and this var is not set.
MGMT_PASS Yes The password for HTTP basic auth protecting the WebUI. Use a strong, randomly generated password.
MGMT_USER No The username for WebUI access. Defaults to admin.
ACME_EMAIL Yes The email address registered with the ACME provider (ZeroSSL by default) for certificate issuance and expiry notifications.

Container / Custom Deployment

You can deploy Vacuum Wall in a container or at any custom path. Set PROJECT_DIR to the mount or bind path, and USER_NAME to whatever system user exists in the container or host environment:

# Docker volume mount example
PROJECT_DIR="/app/vacuum-wall" \
USER_NAME="ww-app" \
MGMT_DOMAIN="proxy.internal" \
MGMT_PASS="strongpassword" \
ACME_EMAIL="admin@example.com" \
bash install.sh

The systemd service unit files and sudoers whitelist are rendered from Jinja2 templates at install time, substituting USER_NAME and PROJECT_DIR. This means no hardcoded paths remain after installation.

What install.sh Does

The installer performs the following steps automatically:

  • Package installation: Installs firewalld, nginx, dnsmasq, avahi-daemon, wireguard-tools, python3, Flask, pip, jq, curl, iptables, nftables, and apache2-utils.
  • System user creation: Creates a dedicated system user (default: vacuum-wall, configurable via USER_NAME) with a nologin shell that owns the project data and runs the WebUI service.
  • Python venv: Sets up a Python virtual environment and installs project dependencies.
  • acme.sh installation: Downloads and installs the acme.sh client to the project user's home directory for ACME certificate management.
  • Directory setup: Creates config directories under $PROJECT_DIR/config/ for each subsystem's declarative JSON, and data directories under $PROJECT_DIR/data/ for nginx sites, dnsmasq fragments, firewall rules, and WireGuard config. Sets ownership to the configured system user.
  • Template rendering: Renders system template files (systemd/*.service, sudoers.d/) via Jinja2, substituting USER_NAME, PROJECT_DIR, and ACME_HOME. Installed systemd and sudoers files contain no hardcoded values.
  • Sudoers whitelist: Installs a restrictive sudoers file at /etc/sudoers.d/vacuum-wall allowing the configured user to run only the specific privileged commands needed for firewall, nginx, and dnsmasq management. Validates syntax with visudo -cf.
  • IP forwarding: Enables net.ipv4.ip_forward=1 in sysctl.conf and applies it at runtime, required for routing traffic between zones.
  • Firewalld initialization: Starts and enables firewalld. Opens HTTP, HTTPS, and SSH services on the public zone for management access.
  • Dnsmasq initialization: Starts and enables dnsmasq for future DHCP/DNS serving on internal interfaces.
  • mDNS broadcast: Enables and starts avahi-daemon so the appliance advertises its hostname (<hostname>.local) on the local network.
  • Self-signed certificate: Generates a temporary self-signed X.509 certificate for the management domain with the correct CN and SAN, placed where acme.sh would store a real cert.
  • Management proxy configuration: Configures nginx as a reverse proxy that forward-proxies to the WebUI at 127.0.0.1:9090, with HTTP-to-HTTPS redirect, basic auth, and WebSocket upgrade support.
  • Credentials: Generates an htpasswd file using apache2-utils (with a Python fallback) for the management proxy's basic auth. Copies it to both $USER_HOME/.htpasswd (used by install.sh's initial nginx config) and $PROJECT_DIR/data/nginx/.htpasswd (used by the running app).
  • Initial nginx config: Writes $PROJECT_DIR/config/nginx/config.json with the management domain and auth settings pre-configured, so the WebUI can render management proxy config out of the box.
  • Systemd units: Installs three units (rendered from Jinja2 templates):
    • vacuum-wall.service — the Flask WebUI backend.
    • vacuum-wall-acme.service — the certificate renewal oneshot.
    • vacuum-wall-acme.timer — periodic timer that triggers cert renewals.
  • Firewalld zones: Creates initial zones:
    • internal — trusted LAN zone with DHCP, DNS, and NTP services allowed.
    • vpn — WireGuard tunnel zone.
  • Service startup: Enables and starts nginx, the WebUI service, and the ACME renewal timer.
  • ACME registration: Registers the ACME account with the provided email via acme.sh.

Post-Installation

Verify Services

After the installer completes, confirm all services are running:

systemctl status vacuum-wall nginx firewalld dnsmasq

Each should be active (running). The vacuum-wall-acme.timer should also be active (waiting).

Access the WebUI

Open a browser and navigate to:

https://wall.example.com

Log in with the username and password you provided during installation.

Certificate Note

The initial certificate is self-signed and generated during installation. Your browser will show a security warning. This is expected. Once DNS is pointing to the appliance and port 80 is accessible from the internet, use the Certs tab in the WebUI to issue a real ACME certificate for the management domain. After issuance, go to the Proxy tab and click Apply to reload nginx with the new cert.

Configuring Your First Network

After installation, the appliance has no interfaces assigned to zones and no DHCP ranges configured. Use the WebUI to set up your LAN.

1. Assign a LAN Interface to the Internal Zone

  1. Navigate to the Interfaces tab.
  2. From the interface list, select your LAN interface (e.g., eth1).
  3. Assign it to the internal zone.
  4. Click Apply to update the firewall configuration.

2. Enable NAT/Masquerade

  1. Go to the NAT tab.
  2. Enable masquerade on the internal zone. This allows devices on your LAN to reach the internet through the appliance's external interface.
  3. Click Apply.

3. Configure DHCP

  1. Go to the DHCP tab.
  2. Click Add Range.
  3. Specify:
    • Address range: e.g., 192.168.2.100-192.168.2.200
    • Lease time: e.g., 12h
    • Interface: eth1 (or whichever interface you assigned to internal)
  4. Click Apply. This writes the dnsmasq configuration and reloads the service.

DNS resolution will also be provided on this interface by dnsmasq, which forwards queries upstream.

Adding a Proxy Domain

Vacuum Wall's primary function is proxying incoming HTTPS traffic to internal backend services.

1. Add the Domain

  1. Navigate to the Proxy tab.
  2. Click Add Domain.
  3. Fill in:
    • Domain: The public domain name (e.g., app.example.com).
    • Backend Host: The internal IP address of the service (e.g., 192.168.2.50).
    • Backend Port: The port the service listens on (e.g., 8080).

2. Issue a Certificate

  1. Go to the Certs tab.
  2. Click Issue Certificate and enter the domain name.
  3. ACME validation requires that port 80 on the appliance is reachable from the internet and that the domain's DNS A record points to the appliance's public IP.

3. Reload Nginx

  1. Return to the Proxy tab.
  2. Click Apply to write the nginx configuration and reload the service.

The proxied domain is now accessible via HTTPS at the configured domain name.

Setting up WireGuard

Vacuum Wall includes integrated WireGuard server support for VPN access.

1. Initialize the Server

  1. Navigate to the WireGuard tab.
  2. Click Initialize. This generates the server's private and public keys and creates the wg0 interface configuration.

2. Add a Peer

  1. Click Add Peer.
  2. Enter a peer name (e.g., alice).
  3. Optionally set a specific AllowedIPs range for this peer (defaults to 0.0.0.0/0).
  4. Optionally set an Endpoint if you know the peer's static public IP (restricts incoming connections to that IP).
  5. Click Add. The peer's public key and preshared key are generated automatically.

3. Activate the Tunnel

  1. Click Apply to write the WireGuard configuration and bring up the wg0 interface.

4. Download Client Configuration

  1. In the peer list, use the peer actions menu to download the client configuration file for the peer.
  2. Install this configuration on the client device.

5. Assign WireGuard to a Firewall Zone

  1. Navigate to the Interfaces tab.
  2. Assign wg0 to the vpn zone.
  3. The vpn zone allows all traffic by default (target ACCEPT). Adjust firewall rules as needed to restrict VPN access to specific services.

6. Configure Firewall Rules for VPN Traffic

  1. Go to the Firewall tab or use the NAT tab.
  2. Add rules as needed to control what VPN peers can access. For example, you can restrict VPN peers to only reach specific internal services rather than the entire LAN.
  3. Optionally enable masquerade on the vpn zone to allow VPN clients to reach the internet through the appliance.

Troubleshooting

Services Won't Start

Check service logs and configuration:

journalctl -u vacuum-wall --no-pager -n 50
journalctl -u nginx --no-pager -n 50
nginx -t

Common causes include port conflicts (another service on port 80/443), missing dependencies, or file permission issues on $PROJECT_DIR/data/.

Firewall Rules Not Applying

Verify that firewalld is running:

firewall-cmd --state
systemctl status firewalld

If firewalld is not running, start it with systemctl start firewalld. Check that the sudoers whitelist is valid:

visudo -cf /etc/sudoers.d/vacuum-wall

Certificate Issuance Fails

ACME validation via the ACME provider requires:

  • The domain's DNS A record points to the appliance's public IP.
  • Port 80 (HTTP-01 challenge) is accessible from the internet on the external interface.
  • The ACME email was registered correctly. Check with:
su -s /bin/bash "$USER_NAME" -c "~/.acme.sh/acme.sh --list"

If port 80 is blocked or the DNS record hasn't propagated yet, wait and retry. The ACME timer will also attempt renewal automatically.

DHCP Not Working

Verify that:

  • The LAN interface is assigned to a firewalld zone (check the Interfaces tab or firewall-cmd --get-active-zones).
  • Dnsmasq is running: systemctl status dnsmasq.
  • A DHCP range is configured for the correct interface. Check dnsmasq config at $PROJECT_DIR/data/dnsmasq/.
  • The firewall allows DHCP traffic on the internal zone: firewall-cmd --zone=internal --list-services should include dhcp and dns.

WebUI Not Accessible

  1. Verify nginx is running: systemctl status nginx.
  2. Test nginx configuration: nginx -t.
  3. Check the management proxy configuration at /etc/nginx/conf.d/vacuum-wall-mgmt.conf (initial) or via the WebUI Proxy tab (after first apply).
  4. Ensure the WebUI service is listening on port 9090: ss -tlnp | grep 9090.
  5. If using the self-signed cert, confirm your browser trusts it or use the WebUI to issue a real ACME certificate.

Reference

Component Service Config Location
WebUI backend vacuum-wall.service $PROJECT_DIR/webui/
Reverse proxy nginx /etc/nginx/conf.d/vacuum-wall-mgmt.conf
Firewall firewalld Managed via WebUI and firewall-cmd
DHCP/DNS dnsmasq $PROJECT_DIR/config/dnsmasq/
VPN wireguard-tools $PROJECT_DIR/config/wireguard/
Certificates vacuum-wall-acme.timer ~/.acme.sh/
Sudoers — /etc/sudoers.d/vacuum-wall
Reference in New Issue View Git Blame Copy Permalink