78 lines
4.6 KiB
Markdown
78 lines
4.6 KiB
Markdown
# ITWorx Pulse
|
|
|
|
<p align="center"><img src="apps/web/public/pulse-icon.svg" width="76" alt="ITWorx Pulse icon"></p>
|
|
<p align="center"><strong>A read-only operations view for self-hosted infrastructure.</strong></p>
|
|
<p align="center"><a href="#see-pulse-in-action">Interface</a> · <a href="#capabilities">Capabilities</a> · <a href="#try-it-locally">Quick start</a> · <a href="#production-deployment">Deployment</a></p>
|
|
|
|
ITWorx Pulse brings Unraid host, container, storage, network and service telemetry into one operator-focused interface. It helps teams see what needs attention, investigate the underlying resource, and keep dashboards, alerts, incidents and wallboards in the same context.
|
|
|
|
Current release: **v1.6.0**. See the [changelog](CHANGELOG.md) for release history.
|
|
|
|
Pulse is operationally **read-only**: it observes and explains infrastructure, but does not start, stop, delete or repair workloads. Missing or stale telemetry appears as **Unknown**, never as a reassuring green status.
|
|
|
|
## See Pulse in action
|
|
|
|
|
|
|
|
*This capture uses isolated validation fixtures and does not show a production host.*
|
|
|
|
## Capabilities
|
|
|
|
| Area | What operators can do |
|
|
| --- | --- |
|
|
| Overview and search | Move from an attention item to the exact host, container, service or storage resource. |
|
|
| Infrastructure detail | Inspect hosts, processes, containers, applications, arrays, disks, pools, shares and networks. |
|
|
| Dashboards | Compose versioned desktop, tablet, mobile and wallboard layouts. |
|
|
| Metrics | Explore bounded historical and live Prometheus queries without writing PromQL. |
|
|
| Alerts and incidents | Manage pending and recovery states, suppression, maintenance, timelines, notes and ownership. |
|
|
| Access and recovery | Use Authentik/OIDC roles, audit trails, verifiable backups and clean-room restore procedures. |
|
|
|
|
The global operator bar keeps time context, entity search, favorites, saved views and recent resources available while investigating. The interface supports responsive layouts and accessible keyboard navigation.
|
|
|
|
## Try it locally
|
|
|
|
Requirements: Go 1.26.6, Node.js 24+, pnpm 10.33+, Python 3, PowerShell 7 and 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 <http://localhost:18080>. The development stack uses explicit mock authentication and isolated local data. Do not put production credentials or production telemetry in this environment. Stop the stack with `docker compose -f deploy/compose.yaml -f deploy/compose.dev.yaml down --volumes` when its local data can be discarded.
|
|
|
|
## Architecture
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
Browser[Browser and wallboard] --> Web[Pulse web and API]
|
|
Web --> DB[(PostgreSQL domain state)]
|
|
Web --> Metrics[Prometheus metrics]
|
|
Worker[Pulse worker] --> DB
|
|
Agent[Read-only Unraid agent] --> Worker
|
|
```
|
|
|
|
The web/API tier has no Docker socket or host-root access. Only the agent receives explicitly configured read-only sources needed for observation. PostgreSQL stores configuration, inventory, dashboards, alerts and audit; the worker handles discovery, probes and notifications.
|
|
|
|
## Production deployment
|
|
|
|
Begin with the [public deployment guide](docs/PUBLIC_DEPLOYMENT.md). A production instance needs HTTPS, Authentik/OIDC, private PostgreSQL, externally managed secrets, a defined Prometheus source, least-privilege Unraid API access where required, a backup directory, and a reviewed network and mount projection. The supplied configuration fails closed when mandatory production settings are absent. Validate backup, restore and rollback before relying on alerts.
|
|
|
|
Run the public source verification with:
|
|
|
|
```powershell
|
|
pwsh -NoProfile -File scripts/public-verify.ps1
|
|
```
|
|
|
|
This checks Go tests and vet, frontend tests and build, contracts, wiring, secret markers, image digests and the public-source boundary. The optional Docker integration smoke is in `scripts/integration-smoke.ps1`.
|
|
|
|
## Further reading
|
|
|
|
- [System architecture](docs/architecture/SYSTEM_ARCHITECTURE.md) and [API contract](docs/architecture/API_CONTRACT.md)
|
|
- [Security threat model](docs/architecture/SECURITY_THREAT_MODEL.md)
|
|
- [Development setup](docs/operations/DEVELOPMENT_SETUP.md)
|
|
- [Backup and restore](docs/operations/BACKUP_RESTORE.md)
|
|
- [Public source boundary](docs/PUBLIC_SOURCE_BOUNDARY.md)
|
|
|
|
First-party source is licensed under **AGPL-3.0-or-later**; see [LICENSE](LICENSE). For vulnerabilities, follow [SECURITY.md](SECURITY.md) rather than posting sensitive details in an issue.
|