install: two-user model ownership and deployment

docs/deployment.md

@@ -26,7 +26,7 @@ Download the Vacuum Wall repository onto the target machine, then run the instal
 MGMT_DOMAIN=wall.example.com \
 MGMT_PASS="strongpassword" \
 ACME_EMAIL="admin@example.com" \
-bash install.sh
+./install.sh --user vacuum-wall
 
 # Dev mode: CLI flags, auto-detects repo owner
 ./install.sh --dev --mgmt-pass strongpassword --acme-email "admin@example.com"
@@ -46,7 +46,7 @@ All settings that can be passed as an environment variable also have a CLI flag
 | `--mgmt-pass` | `MGMT_PASS` | Yes | Password for HTTP basic auth protecting the WebUI. |
 | `--mgmt-user` | `MGMT_USER` | No | Username for WebUI access. Defaults to `admin`. |
 | `--acme-email` | `ACME_EMAIL` | Yes | Email for ACME provider (ZeroSSL by default). |
-| `--user, -u` | `USER_NAME` | No | System user for the WebUI service. Defaults to `vacuum-wall`. |
+| `--user, -u` | `USER_NAME` | Yes* | WebUI service user (created if it does not exist). Required for non-dev mode. In `--dev` mode, auto-detected from repo owner. |
 | `--path, -p` | `INSTALL_DIR` | No | Install directory. Defaults to repo root. Set to deploy from a custom path (e.g., `/opt/vacuum-wall`). |
 | `--dev` | -- | No | Development mode: auto-detects repo owner as service user, skips safety warning. |
 | `--wan-iface` | `WAN_IFACE` | No | WAN interface name. Auto-detected from default gateway. |
@@ -57,6 +57,33 @@ Run `./install.sh --help` for full usage.
 
 ---
 
+## Dev Mode
+
+The `--dev` flag is designed for developers working in a git clone. It auto-detects the repo owner and uses that user as the WebUI service user.
+
+### Ownership Model
+
+In dev mode, the ownership model preserves the developer's ability to work with the repository:
+
+- **Project directory**: Owned by the repo owner (e.g., `wall`), group is the repo owner's primary group (e.g., `wall`). The developer retains full control — `git add`, `git commit`, editing code and config files all work normally.
+- **Daemon access**: The daemon user (`vacuum-walld`) has the repo owner's primary group as its own primary group, granting read access to all project files. The project directory has the setgid bit (`g+s`) on all subdirectories, ensuring new files inherit the group.
+- **`.venv/` and `data/`**: Owned by the repo owner, group is the repo owner's primary group. The developer can run `pip install`, inspect logs, and manage runtime artifacts. The daemon reads `.venv/` (Python interpreter) and writes to `data/` (runtime files) via group permissions.
+- **Daemon socket** (`data/daemon.sock`): Owned by `vacuum-walld:<group>` (mode `0660`). The repo owner accesses it via primary group membership.
+
+### Running the Installer in Dev Mode
+
+```bash
+./install.sh --dev --mgmt-pass strongpassword --acme-email "dev@example.com"
+```
+
+The script detects the repo owner (e.g., `wall`), creates the `vacuum-walld` daemon user with the repo owner's primary group, and sets up the ownership model described above.
+
+### Idempotent Re-Runs
+
+Running `--dev` again is safe. The ownership is idempotent (`chown -R` to the same owner), supplementary group membership is deduplicated by the OS, and setgid bits are applied recursively each time.
+
+---
+
 ## Container / Custom Deployment
 
 You can deploy Vacuum Wall in a container or at any custom path. Use `--path` (or `INSTALL_DIR`) for the mount or bind path, and `--user` (or `USER_NAME`) for whatever system user exists:
@@ -77,14 +104,14 @@ The systemd service unit files and sudoers whitelist are rendered from Jinja2 te
 The installer performs the following steps automatically:
 
 - **Package installation**: Installs firewalld, nginx, dnsmasq, avahi-daemon, wireguard-tools, python3, python3-pip, jq, curl, iptables, nftables, and apache2-utils.
-- **Shared group creation**: Creates a shared system group (`vacuum-wall`) both service users belong to.
+- **WebUI user creation**: Creates the WebUI user (from `--user`) as a system user if it does not exist.
+- **Shared group**: Uses the WebUI user's primary group as the shared group between both service users.
 - **Daemon user creation**: Creates `vacuum-walld` (derived from WebUI user name) — a system user with `NOPASSWD` sudo access for privileged operations. Owns the project directory and daemon socket.
-- **WebUI user creation**: Creates a dedicated system user (default: `vacuum-wall`, configurable via `USER_NAME`) with zero sudo access. Communicates with the daemon via Unix socket.
 - **Python venv**: Creates the Python virtual environment and installs project dependencies. Skips if already present (use `--force-venv` to recreate).
 - **acme.sh installation**: Copies the vendored acme.sh client to the data directory for ACME certificate management. Skips if already installed.
 - **Directory setup**: Creates config directories under `config/` for each subsystem's declarative JSON, and data directories under `data/` for generated files (nginx sites, dnsmasq fragments, firewall backup, WireGuard config).
 - **Template rendering**: Renders system template files (`systemd/*.service`, `sudoers.d/`) via Jinja2, substituting `USER_NAME`, `INSTALL_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-walld` granting the daemon user `NOPASSWD` sudo for only the specific privileged commands needed for firewall, nginx, dnsmasq, and acme.sh management. Validates syntax with `visudo -cf`. The WebUI user's sudoers file (`/etc/sudoers.d/vacuum-wall`) is empty — it has no sudo access.
+- **Sudoers whitelist**: Installs a restrictive sudoers file at `/etc/sudoers.d/vacuum-walld` granting the daemon user `NOPASSWD` sudo for only the specific privileged commands needed for firewall, nginx, dnsmasq, and acme.sh 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. Appends only if not already present.
 - **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.