initial commit

README.md

@@ -1,3 +1,73 @@
-# squid-configurator
+# Squid + WPAD + Configurator Stack
 
-Configurator for Squid Proxy via Node.js with a react frontend
+Selbstgehosteter Squid-Proxy mit Domain-Whitelist-Routing zu Gluetun, plus WPAD-Verteilung
+und einer Web-UI zur Konfiguration.
+
+## Komponenten
+
+| Service | Zweck | Erreichbar |
+|---|---|---|
+| `squid` | HTTP-Proxy, leitet Whitelist-Domains zu Gluetun | Port 3128 (LAN) |
+| `wpad` | nginx, served `wpad.dat` für Auto-Config | https://wpad.lan |
+| `configurator` | Web-UI + API zum Pflegen der Config | https://squid.lan |
+
+## Setup
+
+```bash
+# 1. Verzeichnisse anlegen
+sudo mkdir -p /opt/squid/{config,cache,logs,wpad,configurator/data}
+
+# 2. Repo nach /opt/squid/ kopieren
+sudo cp -r ./configurator/* /opt/squid/configurator/
+sudo cp ./wpad/nginx.conf /opt/squid/wpad/
+sudo cp ./docker-compose.yml /opt/squid/
+
+# 3. Stack hochziehen (Configurator schreibt beim ersten Start die Default-Configs)
+cd /opt/squid
+docker compose up -d --build
+
+# 4. AdGuard DNS Rewrites:
+#    wpad.lan      -> <Cerberus-IP>
+#    squid.lan     -> <Cerberus-IP>
+
+# 5. DHCP Option 252 setzen:
+#    http://wpad.lan/wpad.dat
+#    (oder https mit Step CA falls alle Geräte der CA vertrauen)
+```
+
+## Sicherheitshinweise
+
+- **Docker socket mount:** Der Configurator hat Zugriff auf den Docker Socket, um
+  `squid -k reconfigure` per `docker exec` auszulösen. Das ist effektiv root auf dem Host.
+  → Daher hinter Forward-Auth (Pocket ID) stellen, niemals ohne Auth ans Internet hängen.
+
+- **Auth via Pocket ID:** Im `docker-compose.yml` ist die Middleware-Zeile auskommentiert.
+  Aktiviere sie sobald deine Pocket-ID-Forward-Auth-Middleware in Traefik definiert ist:
+  ```yaml
+  - "traefik.http.routers.squid-cfg-lan.middlewares=pocketid-auth@file"
+  ```
+
+- **Input-Validierung:** Das Backend validiert CIDRs, Hostnames und Ports per Regex,
+  bevor irgendwas geschrieben wird. Trotzdem: nicht öffentlich erreichbar machen.
+
+## API
+
+| Endpoint | Method | Zweck |
+|---|---|---|
+| `/api/config` | GET | aktuellen State zurückgeben |
+| `/api/config` | POST | State validieren, speichern, Configs schreiben, Squid reloaden |
+| `/api/reload` | POST | Squid manuell reloaden (z.B. nach manueller Änderung) |
+| `/api/health` | GET | Healthcheck |
+
+## Datenfluss
+
+```
+Browser  ─POST /api/config─►  configurator
+                              │
+                              ├─► /data/state.json          (state of truth)
+                              ├─► /squid-config/squid.conf
+                              ├─► /squid-config/vpn_domains.txt
+                              ├─► /wpad/wpad.dat
+                              │
+                              └─► docker.sock ──► squid -k reconfigure
+```