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:
+12
-12
@@ -1,10 +1,10 @@
|
||||
# Configuration Reference
|
||||
|
||||
This document describes the JSON configuration files used by Vacuum Wall to manage each subsystem. All configuration is stored in the `data/` directory as declarative JSON. The application renders these declarations into the format expected by each underlying service.
|
||||
This document describes the JSON configuration files used by Vacuum Wall to manage each subsystem. All persistent configuration is stored in the `config/` directory as declarative JSON. Runtime artifacts and generated files live in `data/`. The application renders these declarations into the format expected by each underlying service.
|
||||
|
||||
## DHCP/DNS Configuration
|
||||
|
||||
**File**: `data/dnsmasq/config.json`
|
||||
**File**: `config/dnsmasq/config.json`
|
||||
|
||||
This file defines all DHCP server settings and DNS resolution behavior for the dnsmasq service. The application renders it into `/etc/dnsmasq.d/vacuum-wall.conf`.
|
||||
|
||||
@@ -74,7 +74,7 @@ Additional dnsmasq directives can be appended verbatim by placing plain-text fil
|
||||
|
||||
## Nginx Configuration
|
||||
|
||||
**File**: `data/nginx/config.json`
|
||||
**File**: `config/nginx/config.json`
|
||||
|
||||
This file defines reverse proxy domains, the management interface, and global SSL settings. The application renders it into per-domain server block files in `data/nginx/sites-enabled/` and into the shared SSL snippet at `/etc/nginx/snippets/vacuum-wall-ssl.conf`.
|
||||
|
||||
@@ -99,7 +99,7 @@ This file defines reverse proxy domains, the management interface, and global SS
|
||||
}
|
||||
},
|
||||
"management": {
|
||||
"domain": "wall.lan",
|
||||
"domain": "<hostname>.local",
|
||||
"backend": {
|
||||
"host": "127.0.0.1",
|
||||
"port": 9090,
|
||||
@@ -107,7 +107,7 @@ This file defines reverse proxy domains, the management interface, and global SS
|
||||
},
|
||||
"auth": {
|
||||
"user": "admin",
|
||||
"htpasswd": "/home/wall/vacuum-wall/data/nginx/.htpasswd"
|
||||
"htpasswd": "$PROJECT_DIR/data/nginx/.htpasswd"
|
||||
}
|
||||
},
|
||||
"ssl": {
|
||||
@@ -132,7 +132,7 @@ The `domains` object maps domain names (keys) to proxy configurations. Each entr
|
||||
| `headers` | object | No | Custom headers to set on proxied requests. Supports nginx variable interpolation (e.g., `$remote_addr`). |
|
||||
| `cert` | object | No | Certificate configuration for this domain. Required unless the management domain shares its cert. |
|
||||
| `cert.type` | string | Yes (if `cert`) | Certificate provisioning method. One of: `acme`, `file`, or `selfsigned`. |
|
||||
| `cert.email` | string | Yes (if `acme`) | ACME account email used by Let's Encrypt. |
|
||||
| `cert.email` | string | Yes (if `acme`) | ACME account email used by the CA provider. |
|
||||
| `cert.path` | string | Yes (if `file`) | Full path to the public certificate file (PEM). |
|
||||
| `cert.key_path` | string | Yes (if `file`) | Full path to the private key file (PEM). |
|
||||
|
||||
@@ -140,9 +140,9 @@ The `domains` object maps domain names (keys) to proxy configurations. Each entr
|
||||
|
||||
| Type | Description |
|
||||
|---|---|
|
||||
| `acme` | Vacuum Wall uses acme.sh to request and renew a Let's Encrypt certificate via the HTTP-01 challenge. The nginx configuration is temporarily modified to serve the ACME challenge files at `/.well-known/acme-challenge/`. The `email` field is required. |
|
||||
| `acme` | Vacuum Wall uses acme.sh to request and renew an ACME certificate via the HTTP-01 challenge. The nginx configuration is temporarily modified to serve the ACME challenge files at `/.well-known/acme-challenge/`. The `email` field is required. |
|
||||
| `file` | Use a pre-existing certificate and private key from the local file system. The `path` and `key_path` fields must point to readable PEM files. Vacuum Wall will not attempt to renew these certificates. |
|
||||
| `selfsigned` | Vacuum Wall generates a self-signed certificate and private key on first apply. Useful for internal domains or testing. The generated certificate is stored alongside other acme-managed files in `~/.acme.sh/` with a `.selfsigned` marker. |
|
||||
| `selfsigned` | Vacuum Wall generates a self-signed certificate and private key on first apply. Useful for internal domains or testing. The generated certificate is stored at `$PROJECT_DIR/data/certs/`. |
|
||||
|
||||
### Management Domain
|
||||
|
||||
@@ -150,7 +150,7 @@ The `management` block configures the Vacuum Wall admin interface itself. It fol
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `domain` | string | Yes | The hostname used to access the management WebUI (e.g., `wall.lan`). |
|
||||
| `domain` | string | Yes | The hostname used to access the management WebUI (e.g., `<hostname>.local`). |
|
||||
| `backend` | object | Yes | Points to the Flask app at `127.0.0.1:9090`. |
|
||||
| `auth` | object | Yes | HTTP Basic Authentication configuration. |
|
||||
| `auth.user` | string | Yes | Username for the `.htpasswd` file. |
|
||||
@@ -159,7 +159,7 @@ The `management` block configures the Vacuum Wall admin interface itself. It fol
|
||||
The `.htpasswd` file can be created with the `htpasswd` utility:
|
||||
|
||||
```bash
|
||||
htpasswd -bc /home/wall/vacuum-wall/data/nginx/.htpasswd admin yourpassword
|
||||
htpasswd -bc $PROJECT_DIR/data/nginx/.htpasswd admin yourpassword
|
||||
```
|
||||
|
||||
### Global SSL Settings
|
||||
@@ -174,7 +174,7 @@ The `ssl` block defines TLS parameters applied to all HTTPS server blocks via th
|
||||
|
||||
## WireGuard Configuration
|
||||
|
||||
**File**: `data/wireguard/config.json`
|
||||
**File**: `config/wireguard/config.json`
|
||||
|
||||
This file defines the WireGuard server interface and all connected peers. The application renders it into `/etc/wireguard/wg0.conf` and applies it with `wg-quick`.
|
||||
|
||||
@@ -241,4 +241,4 @@ When configuration is saved through the WebUI or API, the application:
|
||||
4. Runs `sudo wg-quick up wg0` to apply the configuration.
|
||||
5. Returns success or error status to the caller.
|
||||
|
||||
If the interface is already up, `wg-quick up` will reconfigure it in place without dropping existing connections.
|
||||
If the interface is already up, `wg-quick up` will reconfigure it in place without dropping existing connections.
|
||||
Reference in New Issue
Block a user