# 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.