Publish ITWorx Pulse source

2026-09-03 02:09:19 +02:00
commit bd774932d5
614 changed files with 77116 additions and 0 deletions
@@ -0,0 +1,92 @@
+# ITWorx Pulse
+
+ITWorx Pulse is een self-hosted observabilityplatform voor Unraid. Het brengt host-, container-, storage-, netwerk- en servicetelemetrie samen in één operatorgerichte interface, met configureerbare dashboards, alerts, incidenten en wallboards.
+
+Pulse is operationeel **read-only**: het observeert en verklaart, maar start, stopt, verwijdert of repareert geen infrastructuur. Ontbrekende of verouderde telemetrie verschijnt als `Onbekend`, nooit als vals groen.
+
+Actuele release: **v1.5.0**.
+
+## Wat je als gebruiker krijgt
+
+- een overzicht dat meteen toont wat gezond, gedegradeerd, kritisch of onbekend is en waarom;
+- detailpagina's voor host, processen, containers, applicaties, array, disks, pools, shares, services en netwerk;
+- versieerbare dashboards met afzonderlijke desktop-, tablet-, mobiele en wallboardlayouts;
+- begrensde historische en live Prometheus-query's zonder dat gebruikers zelf PromQL moeten schrijven;
+- alerts met pending/recovery, hysterese, suppressie, silences en maintenance;
+- incidentgroepering, tijdlijnen, notities, ownership en audit;
+- Authentik/OIDC-login met viewer-, operator-, editor- en administratorrollen;
+- controleerbare backups en een clean-room herstelprocedure;
+- hardened non-root containers en een minimale read-only collectorgrens.
+
+## Platform in één oogopslag
+
+```text
+Browser
+  └─ HTTPS / OIDC / REST / WebSocket
+       └─ Pulse Web + API
+            ├─ PostgreSQL       configuratie, inventory, dashboards, alerts en audit
+            ├─ Prometheus      begrensde historische en live metrics
+            ├─ Pulse Worker    discovery, probes, alerting en notifications
+            └─ Pulse Agent     minimale read-only Unraid- en hostobservatie
+```
+
+De web/API-laag krijgt geen Docker-socket of host-roottoegang. Alleen de agent ontvangt de expliciet geconfigureerde read-only bronnen die nodig zijn voor observatie.
+
+## Snel lokaal proberen
+
+Vereisten: Go 1.26.6, Node.js 24+, pnpm 10.33+, Python 3, PowerShell 7 en Docker Compose.
+
+```powershell
+Copy-Item .env.example .env
+pwsh -NoProfile -File scripts/bootstrap.ps1
+docker compose -f deploy/compose.yaml -f deploy/compose.dev.yaml up --build
+```
+
+Open daarna `http://localhost:18080`. De ontwikkelstack gebruikt expliciete mock-authenticatie en geïsoleerde lokale data; gebruik hiervoor nooit productiecredentials of productiedata.
+
+Stop en verwijder alleen deze lokale stack met:
+
+```powershell
+docker compose -f deploy/compose.yaml -f deploy/compose.dev.yaml down --volumes
+```
+
+## Valideren
+
+De private engineeringrepository gebruikt een uitgebreidere evidencegate. Een publieke source-export valideert de productcode met:
+
+```powershell
+pwsh -NoProfile -File scripts/public-verify.ps1
+```
+
+Deze gate controleert Go-tests/vet, frontendtests/typecheck/build, contracten, wiring, secretmarkers, image-digests en de publieke source boundary. De optionele Docker-integratiesmoke staat in `scripts/integration-smoke.ps1`.
+
+## Productie
+
+Begin bij [`docs/PUBLIC_DEPLOYMENT.md`](docs/PUBLIC_DEPLOYMENT.md). Productie vereist onder meer:
+
+- HTTPS en een Authentik/OIDC-provider;
+- een private PostgreSQL-database en externe secrets;
+- een expliciete Prometheusbron;
+- een least-privilege Unraid API-token en gecontroleerde CA-mount wanneer de agent de Unraid API gebruikt;
+- een operator-owned backupdirectory;
+- validatie van poorten, netwerken, mounts en rollback vóór de eerste start.
+
+De voorbeeldconfiguratie faalt bewust dicht wanneer verplichte productie-instellingen ontbreken.
+
+## Documentatie
+
+| Onderwerp | Document |
+|---|---|
+| Productscope en gebruikersflows | [`docs/product/PRODUCT_REQUIREMENTS.md`](docs/product/PRODUCT_REQUIREMENTS.md) |
+| Architectuur | [`docs/architecture/SYSTEM_ARCHITECTURE.md`](docs/architecture/SYSTEM_ARCHITECTURE.md) |
+| API en WebSocketcontract | [`docs/architecture/API_CONTRACT.md`](docs/architecture/API_CONTRACT.md) |
+| Securitymodel | [`docs/architecture/SECURITY_THREAT_MODEL.md`](docs/architecture/SECURITY_THREAT_MODEL.md) |
+| Lokale ontwikkeling | [`docs/operations/DEVELOPMENT_SETUP.md`](docs/operations/DEVELOPMENT_SETUP.md) |
+| Backup en herstel | [`docs/operations/BACKUP_RESTORE.md`](docs/operations/BACKUP_RESTORE.md) |
+| Publicatiegrens | [`docs/PUBLIC_SOURCE_BOUNDARY.md`](docs/PUBLIC_SOURCE_BOUNDARY.md) |
+
+## Bijdragen en security
+
+Lees [`CONTRIBUTING.md`](CONTRIBUTING.md) voordat je een wijziging indient. Meld kwetsbaarheden niet in een publieke issue; volg [`SECURITY.md`](SECURITY.md).
+
+First-party broncode in deze repository is gelicentieerd onder **AGPL-3.0-or-later**; zie [`LICENSE`](LICENSE). Componenten en assets van derden behouden hun eigen licentievoorwaarden.