mirror of
https://github.com/rcourtman/Pulse.git
synced 2026-08-27 18:05:55 +00:00
docs: refresh public repository surface
This commit is contained in:
rcourtman
parent
75e4105d83
commit
40d29ca442
25 changed files with 519 additions and 454 deletions
6
.github/ISSUE_TEMPLATE/bug_report.yml
vendored
6
.github/ISSUE_TEMPLATE/bug_report.yml
vendored
|
|
@ -46,7 +46,7 @@ body:
|
|||
attributes:
|
||||
label: Pulse version
|
||||
description: Exact version shown in the UI or logs.
|
||||
placeholder: v6.0.0
|
||||
placeholder: v6.x.y
|
||||
validations:
|
||||
required: true
|
||||
|
||||
|
|
@ -55,7 +55,7 @@ body:
|
|||
attributes:
|
||||
label: Agent version
|
||||
description: Exact agent version (or "none" if no agents are involved).
|
||||
placeholder: v6.0.0
|
||||
placeholder: v6.x.y or none
|
||||
validations:
|
||||
required: true
|
||||
|
||||
|
|
@ -64,7 +64,7 @@ body:
|
|||
attributes:
|
||||
label: Image tag or digest
|
||||
description: For container installs, the exact image reference used by the running container. Leave blank for LXC, bare metal, and other non-container installs.
|
||||
placeholder: rcourtman/pulse:v6.0.0 or rcourtman/pulse@sha256:...
|
||||
placeholder: rcourtman/pulse:v6.x.y or rcourtman/pulse@sha256:...
|
||||
validations:
|
||||
required: false
|
||||
|
||||
|
|
|
|||
4
.github/ISSUE_TEMPLATE/config.yml
vendored
4
.github/ISSUE_TEMPLATE/config.yml
vendored
|
|
@ -4,5 +4,5 @@ contact_links:
|
|||
url: https://github.com/rcourtman/Pulse/discussions
|
||||
about: Please ask and answer questions here
|
||||
- name: Documentation
|
||||
url: https://github.com/rcourtman/Pulse/wiki
|
||||
about: Check the wiki for guides and documentation
|
||||
url: https://github.com/rcourtman/Pulse/blob/main/docs/README.md
|
||||
about: Browse installation, platform, security, and troubleshooting guides
|
||||
|
|
|
|||
36
.github/ISSUE_TEMPLATE/feature_request.md
vendored
36
.github/ISSUE_TEMPLATE/feature_request.md
vendored
|
|
@ -1,20 +1,30 @@
|
|||
---
|
||||
name: Feature request
|
||||
about: Suggest an idea for this project
|
||||
title: ''
|
||||
labels: 'enhancement'
|
||||
assignees: ''
|
||||
|
||||
about: Describe an operator problem or workflow Pulse could improve
|
||||
title: "[Feature]: "
|
||||
labels: enhancement
|
||||
assignees: ""
|
||||
---
|
||||
|
||||
**Is your feature request related to a problem? Please describe.**
|
||||
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
|
||||
## Problem
|
||||
|
||||
**Describe the solution you'd like**
|
||||
A clear and concise description of what you want to happen.
|
||||
What are you trying to accomplish, and what makes it difficult today?
|
||||
|
||||
**Describe alternatives you've considered**
|
||||
A clear and concise description of any alternative solutions or features you've considered.
|
||||
## Current workflow
|
||||
|
||||
**Additional context**
|
||||
Add any other context or screenshots about the feature request here.
|
||||
Describe how you handle this now. Include the relevant platform, Pulse page,
|
||||
deployment type, and constraints.
|
||||
|
||||
## Desired outcome
|
||||
|
||||
What would a successful Pulse workflow let you do? Focus on the outcome rather
|
||||
than prescribing an implementation when possible.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
What workarounds, other tools, or different approaches have you tried?
|
||||
|
||||
## Additional context
|
||||
|
||||
Add screenshots, examples, or related issues. Do not include credentials,
|
||||
tokens, private keys, or unsanitized configuration files.
|
||||
|
|
|
|||
36
.github/workflows/public-docs.yml
vendored
Normal file
36
.github/workflows/public-docs.yml
vendored
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
name: Public docs
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
paths:
|
||||
- "*.md"
|
||||
- "docs/**"
|
||||
- ".github/ISSUE_TEMPLATE/**"
|
||||
- "scripts/check_public_docs.py"
|
||||
- ".github/workflows/public-docs.yml"
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
paths:
|
||||
- "*.md"
|
||||
- "docs/**"
|
||||
- ".github/ISSUE_TEMPLATE/**"
|
||||
- "scripts/check_public_docs.py"
|
||||
- ".github/workflows/public-docs.yml"
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
concurrency:
|
||||
group: public-docs-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
check:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Check out repository
|
||||
uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
|
||||
|
||||
- name: Validate public documentation
|
||||
run: python3 scripts/check_public_docs.py
|
||||
|
|
@ -1,6 +1,10 @@
|
|||
# Pulse Architecture
|
||||
|
||||
Pulse is a real-time infrastructure monitoring platform for **Proxmox VE**, **Proxmox Backup Server**, **Proxmox Mail Gateway**, **Docker**, **Host** systems, **Kubernetes**, and **TrueNAS**. It is built with a **Go 1.25+** backend and a **SolidJS / TypeScript** frontend, focusing on low latency, high concurrency, and a premium user experience.
|
||||
Pulse is a real-time infrastructure monitoring platform for **Proxmox VE**,
|
||||
**Proxmox Backup Server**, **Proxmox Mail Gateway**, **Docker**, **machine
|
||||
agents**, **Kubernetes**, **TrueNAS**, and early-access **VMware vSphere**
|
||||
environments. It uses a **Go 1.26** backend and a **SolidJS / TypeScript**
|
||||
frontend.
|
||||
|
||||
## 🏗 High-Level Overview
|
||||
|
||||
|
|
@ -27,6 +31,7 @@ flowchart TD
|
|||
Pulse -->|HTTPS :8007| PBS[Proxmox Backup Server]
|
||||
Pulse -->|HTTPS| PMG[Proxmox Mail Gateway]
|
||||
Pulse -->|HTTPS| TrueNAS[TrueNAS SCALE/CORE]
|
||||
Pulse -->|HTTPS| vSphere[VMware vCenter]
|
||||
DockerAgent[Docker Agent] -->|HTTPS POST| API
|
||||
HostAgent[Host Agent] -->|HTTPS POST| API
|
||||
K8sAgent[Kubernetes Agent] -->|HTTPS POST| API
|
||||
|
|
@ -50,7 +55,9 @@ All backend code lives under `cmd/`, `internal/`, and `pkg/`. The binary is asse
|
|||
- Supports graceful hot-reload via `SIGHUP` and `.env` file watching.
|
||||
|
||||
2. **Unified Resource Registry (`internal/unifiedresources`)**
|
||||
- Central data model that normalises resources from **7 data sources** (`proxmox`, `pbs`, `pmg`, `docker`, `agent`, `kubernetes`, `truenas`) into a single `Resource` struct.
|
||||
- Central data model that normalises resources from Proxmox, PBS, PMG,
|
||||
Docker, machine agents, Kubernetes, TrueNAS, and VMware providers into a
|
||||
shared `Resource` contract.
|
||||
- **Canonical v6 resource types**: `agent`, `vm`, `system-container`, `app-container`, `docker-host`, `k8s-cluster`, `k8s-node`, `pod`, `k8s-deployment`, `storage`, `pbs`, `pmg`, `ceph`, `physical_disk`.
|
||||
- Identity-matching engine: merges resources across sources using machine IDs, DMI UUIDs, hostnames, IPs, and MAC addresses.
|
||||
- Provides typed **views** (`NodeView`, `K8sClusterView`, etc.) for consumer-specific queries.
|
||||
|
|
@ -90,10 +97,14 @@ All backend code lives under `cmd/`, `internal/`, and `pkg/`. The binary is asse
|
|||
- **Intelligence Services**: Patterns, correlations, anomalies, baselines, forecasts, and incident recording. All surfaced via `/api/ai/intelligence/*`.
|
||||
- **Safety gates**: Command execution disabled by default (`--enable-commands` opt-in); circuit breakers and scoped permissions at every layer.
|
||||
|
||||
8. **Entitlements & Licensing (`internal/license`)**
|
||||
8. **Entitlements & Licensing (`pkg/licensing`)**
|
||||
- Capability-key based gating: `ai_autofix`, `rbac`, `multi_tenant`, `relay`, `agent_profiles`, `kubernetes_ai`, `ai_alerts`, etc.
|
||||
- Core tiers include **Community** (free), **Relay**, **Pro**, hosted **Cloud**, request-assisted **MSP**, and Enterprise/custom entitlements.
|
||||
- Trial lifecycle with activation, renewal, and expiry. All state exposed via `/api/license/*`.
|
||||
- Core tiers include **Community** (free), **Relay**, **Pro**, a reserved
|
||||
hosted **Cloud** capability tier, request-assisted **MSP**, and
|
||||
Enterprise/custom entitlements. The Cloud service is not generally
|
||||
available.
|
||||
- Activation, grant refresh, renewal, expiry, and legacy-license migration.
|
||||
Active state is exposed through `/api/license/*`.
|
||||
|
||||
9. **Provider-hosted MSP control plane (`internal/cloudcp`)**
|
||||
- A Stripe-free provider control plane can run one isolated Pulse runtime/container per client workspace.
|
||||
|
|
@ -134,20 +145,26 @@ The frontend is a modern SPA in `frontend-modern/`, built with **SolidJS** and *
|
|||
|
||||
### Routing & Navigation
|
||||
|
||||
Navigation is organised by **task**, not by platform:
|
||||
Navigation is organised around platform-shaped pages with cross-platform
|
||||
operational surfaces:
|
||||
|
||||
| Route | Page | Purpose |
|
||||
|---|---|---|
|
||||
| `/infrastructure` | Infrastructure | Hosts, nodes, clusters across all platforms |
|
||||
| `/workloads` | Workloads | VMs, LXCs, containers, K8s pods |
|
||||
| `/storage` | Storage | Proxmox storage, ZFS pools, Ceph |
|
||||
| `/recovery` | Recovery | Backups, snapshots, replication |
|
||||
| `/ceph` | Ceph | Detailed Ceph cluster view |
|
||||
| `/` and `/infrastructure` | Runtime home | Monitor-first authenticated entry point |
|
||||
| `/proxmox/*` | Proxmox | PVE, PBS, PMG, guests, storage, recovery, and Ceph |
|
||||
| `/docker/*` | Docker | Hosts, containers, Compose projects, Swarm, images, and storage |
|
||||
| `/kubernetes/*` | Kubernetes | Clusters, workloads, networking, storage, and events |
|
||||
| `/truenas/*` | TrueNAS | Systems, pools, datasets, disks, apps, VMs, and recovery |
|
||||
| `/vmware/*` | vSphere | Early-access vCenter, host, cluster, VM, datastore, and network views |
|
||||
| `/standalone/*` | Machines | Agent-backed machines and availability checks |
|
||||
| `/alerts/*` | Alerts | Alert rules, active alerts, history |
|
||||
| `/ai/*` | AI Intelligence | Patrol findings, investigations, forecasts |
|
||||
| `/settings/*` | Settings | Configuration, security, diagnostics, reporting, AI, relay |
|
||||
| `/actions/*` | Actions | Governed action proposals, approvals, delivery, and audit state |
|
||||
| `/patrol/*` | Patrol | Attention queue, findings, investigations, and run history |
|
||||
| `/settings/*` | Settings | Infrastructure, security, notifications, plans, and Intelligence |
|
||||
|
||||
Canonical v6 task surfaces live on the routes above; legacy aliases redirect into those canonical settings and patrol paths.
|
||||
The retired aggregate `/workloads`, `/storage`, and `/recovery` top-level
|
||||
routes are not canonical navigation. Shared resource, storage, and recovery
|
||||
contracts remain backend building blocks consumed inside platform pages.
|
||||
|
||||
### State Management
|
||||
- **WebSocket store** (`stores/websocket.ts`): Manages the live connection, reactive `State` object, reconnection logic, and per-org switching.
|
||||
|
|
@ -161,7 +178,9 @@ Canonical v6 task surfaces live on the routes above; legacy aliases redirect int
|
|||
- **Lazy-loaded pages**: All top-level pages are loaded via `lazy()` with optional preloading after initial render.
|
||||
- **Virtual table windowing**: Large resource lists use virtualised rendering for smooth scrolling at scale.
|
||||
- **Command Palette** (`Cmd/Ctrl+K`): Quick-access command launcher.
|
||||
- **Keyboard shortcuts**: `g i` → Infrastructure, `g w` → Workloads, `g s` → Storage, `g b` → Recovery, `g a` → Alerts, `g t` → Settings, `/` → Search.
|
||||
- **Keyboard shortcuts**: `g p` → Proxmox, `g d` → Docker, `g k` →
|
||||
Kubernetes, `g n` → TrueNAS, `g v` → vSphere, `g s` → Machines, `g a` →
|
||||
Alerts, `g r` → Patrol, `g t` → Settings, `/` → Search.
|
||||
|
||||
### Mobile Experience
|
||||
- **MobileNavBar** component: Bottom tab bar for touch navigation.
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@ and installer tooling.
|
|||
|
||||
## Project Overview
|
||||
|
||||
- **Backend (`cmd/`, `internal/`, `pkg/`)** – Go 1.25+ web server that embeds
|
||||
- **Backend (`cmd/`, `internal/`, `pkg/`)** – Go 1.26 web server that embeds
|
||||
the built frontend and exposes REST + WebSocket APIs.
|
||||
- **Architecture (`ARCHITECTURE.md`)** – High-level system design diagrams and explanations.
|
||||
- **Frontend (`frontend-modern/`)** – Vite + SolidJS app built with TypeScript.
|
||||
|
|
@ -66,13 +66,11 @@ and installer tooling.
|
|||
git clone https://github.com/rcourtman/Pulse.git
|
||||
cd Pulse
|
||||
|
||||
# Install dependencies
|
||||
brew install go node npm # or use your distro equivalents
|
||||
# Install Go 1.26 and Node.js 20 with your preferred package manager.
|
||||
|
||||
# Install JS deps
|
||||
cd frontend-modern
|
||||
npm install
|
||||
cd ..
|
||||
# Install the repository and frontend dependencies exactly from their locks
|
||||
npm ci
|
||||
npm --prefix frontend-modern ci
|
||||
```
|
||||
|
||||
### Hot Reload Dev Loop
|
||||
|
|
@ -127,9 +125,10 @@ examples where possible.
|
|||
- Browser proof pack: `npm run dev:verify`
|
||||
- Foreground managed launcher: `npm run dev:foreground`
|
||||
- Frontend-only escape hatch: `cd frontend-modern && npm run dev:frontend-only`
|
||||
- Tests: `npm run test`
|
||||
- Lint: `npm run lint`
|
||||
- Format: `npm run format`
|
||||
- Tests: `npm --prefix frontend-modern test`
|
||||
- Type check: `npm --prefix frontend-modern run type-check`
|
||||
- Lint: `npm --prefix frontend-modern run lint`
|
||||
- Format check: `npm --prefix frontend-modern run format:check`
|
||||
|
||||
The same managed runtime wrappers are available from `frontend-modern/` if you
|
||||
start there by habit, so `npm run dev`, `npm run dev:status`, and
|
||||
|
|
@ -167,14 +166,16 @@ Document rollout plans and kill switches in `MIGRATION_SCAFFOLDING.md` so future
|
|||
- Keep instructions evergreen; put release-specific notes in
|
||||
`docs/RELEASE_NOTES.md`.
|
||||
|
||||
Run a quick link check (`npm run lint-docs` if available, or `markdownlint`)
|
||||
before submitting large doc updates.
|
||||
Run `python3 scripts/check_public_docs.py` before submitting public
|
||||
documentation updates. It verifies local links and rejects retired navigation
|
||||
claims on the current documentation surface.
|
||||
|
||||
---
|
||||
|
||||
## Testing Expectations
|
||||
|
||||
- Every PR should note the tests run (`go test`, `npm test`, `scripts/tests/run.sh`).
|
||||
- Every requested PR should note the tests run (`go test`, frontend tests, or
|
||||
`scripts/tests/run.sh`, as applicable).
|
||||
- Add regression coverage when fixing bugs.
|
||||
- Mention manual verification steps (e.g., “Proxmox LXC installer tested on
|
||||
PVE 8.1”) if automated coverage is not feasible.
|
||||
|
|
@ -197,9 +198,9 @@ For maintainer-requested code help on a tracked issue:
|
|||
|
||||
1. Link the issue where the maintainer requested the patch.
|
||||
2. Fork + branch (`git checkout -b feature/my-change`).
|
||||
2. Make your edits and run relevant tests.
|
||||
3. Update docs and changelog entries as needed.
|
||||
4. Open a PR describing:
|
||||
3. Make your edits and run relevant tests.
|
||||
4. Update docs and changelog entries as needed.
|
||||
5. Open a PR describing:
|
||||
- What changed
|
||||
- Why it changed
|
||||
- Testing performed
|
||||
|
|
|
|||
337
README.md
337
README.md
|
|
@ -1,129 +1,71 @@
|
|||
# Pulse
|
||||
|
||||
<div align="center">
|
||||
<img src="docs/images/pulse-logo.svg" alt="Pulse Logo" width="120" />
|
||||
<p><strong>Monitoring for Proxmox, Docker, Kubernetes, TrueNAS, and vSphere that watches your infrastructure so you don't have to.</strong></p>
|
||||
<img src="docs/images/pulse-logo.svg" alt="Pulse logo" width="112" />
|
||||
<p><strong>Infrastructure monitoring that finds what needs attention.</strong></p>
|
||||
|
||||
[](https://github.com/rcourtman/Pulse)
|
||||
[](https://github.com/rcourtman/Pulse/releases/latest)
|
||||
[](https://github.com/rcourtman/Pulse/releases/latest)
|
||||
[](https://hub.docker.com/r/rcourtman/pulse)
|
||||
[](LICENSE)
|
||||
|
||||
[Live Demo](https://demo.pulserelay.pro) • [Pulse Pro](https://pulserelay.pro) • [Documentation](docs/README.md) • [Report Bug](https://github.com/rcourtman/Pulse/issues)
|
||||
|
||||
Localized getting started: [Deutsch](docs/i18n/de/README.md) • [Español](docs/i18n/es/README.md)
|
||||
[Live demo](https://demo.pulserelay.pro) · [Documentation](docs/README.md) · [Releases](https://github.com/rcourtman/Pulse/releases) · [Discussions](https://github.com/rcourtman/Pulse/discussions)
|
||||
</div>
|
||||
|
||||
---
|
||||
Pulse is a self-hosted monitoring workspace for Proxmox, Docker, Kubernetes,
|
||||
TrueNAS, physical and virtual machines, and early-access VMware vSphere
|
||||
environments. It combines live infrastructure state, history, alerts, recovery
|
||||
visibility, and scheduled health checks without requiring a conventional
|
||||
enterprise monitoring stack.
|
||||
|
||||
> **Pulse v6 is out.** A rebuilt unified workspace with TrueNAS and vSphere
|
||||
> support and a dedicated page for every platform. Upgrading from v5? See the
|
||||
> [v6 upgrade guide](docs/UPGRADE_v6.md).
|
||||
|
||||
|
||||
---
|
||||
## Why Pulse
|
||||
|
||||
Issue-first contribution policy: please open an issue or discussion before
|
||||
investing time in a code change. External pull requests are not part of the
|
||||
normal contribution flow for this repository. See [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||
- **It watches between visits.** Alerts and Pulse Patrol find failed backups,
|
||||
capacity pressure, restart loops, unhealthy containers, clock drift, and
|
||||
other problems that dashboards cannot surface when nobody is looking.
|
||||
- **It keeps each platform familiar.** Proxmox, Docker, Kubernetes, TrueNAS,
|
||||
vSphere, and machines have dedicated views, backed by one shared resource
|
||||
model for search, alerts, history, and investigation.
|
||||
- **It stays operator-controlled.** Credentials are encrypted at rest, API
|
||||
tokens are scoped, agent commands are disabled by default, and governed fixes
|
||||
require the configured policy and approval path.
|
||||
|
||||
## 🚀 Overview
|
||||
## Platform coverage
|
||||
|
||||
Dashboards show you what's happening when you look. Most infrastructure problems start while you're not looking: the backup job that has quietly failed three runs in a row, the ZFS pool creeping toward full, the VM stuck in a restart loop. Pulse is built for that gap.
|
||||
| Platform | Coverage |
|
||||
|---|---|
|
||||
| Proxmox VE, PBS, and PMG | Nodes, guests, storage, backups, replication, Ceph, mail gateways, and alerts |
|
||||
| Docker and Podman | Hosts, containers, Compose projects, Swarm services, health, images, and updates |
|
||||
| Kubernetes | Clusters, nodes, workloads, pods, services, storage, and events through the unified agent |
|
||||
| TrueNAS SCALE and CORE | Pools, datasets, disks, snapshots, replication tasks, apps, VMs, and alerts |
|
||||
| Linux, Windows, and macOS machines | Host health, filesystems, networking, temperatures, RAID, and availability through the unified agent |
|
||||
| VMware vSphere | Early-access inventory, hosts, clusters, VMs, datastores, networks, snapshots, and recovery context; validate against your own vCenter before production use |
|
||||
|
||||
Pulse monitors your Proxmox, Docker, Kubernetes, TrueNAS, and vSphere estate in one workspace and alerts you the moment something breaks. Beyond alerts, **Pulse Patrol** does an engineer's rounds on a schedule, finds the problems nobody configured a rule for, and explains what they mean. On Pro, Patrol also investigates issues and applies safe, policy-bound fixes with verification and an audit trail.
|
||||
Platform pages keep storage and recovery information beside the infrastructure
|
||||
it belongs to. Alerts, Actions, and Patrol remain cross-platform views.
|
||||
|
||||
Designed for homelabs, sysadmins, internal IT teams, and providers who want serious monitoring without running an enterprise monitoring stack. MSP access is a separate, request-assisted provider path and is not part of ordinary self-hosted setup.
|
||||
## Patrol: monitoring that does rounds
|
||||
|
||||
|
||||
Pulse Patrol runs scheduled checks across the current state and recent history
|
||||
of your infrastructure. Community installations can use a local model or their
|
||||
own AI provider for watch-only analysis. Pulse Pro adds investigation and
|
||||
policy-bound fixes with approval, verification, and an audit trail.
|
||||
|
||||
## ✨ Features
|
||||
|
||||
|
||||
### Watching, Not Just Showing
|
||||
- **Pulse Patrol**: Scheduled background health checks (every 10 minutes to every 7 days) that catch silent failures: failed backup jobs, pools approaching capacity, restart-looping VMs, clock drift, failing container health checks. Runs on every tier; community installs use your own AI provider or a local model.
|
||||
- **Investigation and Safe Fixes (Pro / hosted Cloud)**: Alert-triggered root-cause investigation, plus optional remediation under command safety policies with verification and an audit trail
|
||||
- **Chat Assistant (BYOK)**: Ask questions about your infrastructure in natural language
|
||||
- **Bring Your Own Agent (MCP)**: Prefer Claude Code, OpenCode, or another MCP client? Pulse ships an MCP server exposing the same governed tools the Assistant uses (inventory, metrics, alerts, storage, action proposals). Setup lives under Settings → Pulse Intelligence → Assistant → External agents
|
||||
- **Cost Tracking**: Track usage and costs per provider/model
|
||||
Pulse also includes an interactive Assistant and an MCP adapter for external
|
||||
clients such as Claude Code and OpenCode. Both sit on top of the same scoped
|
||||
inventory, metrics, alert, storage, and governed-action contracts.
|
||||
|
||||
### Core Monitoring
|
||||
- **Unified Monitoring**: View health and metrics for PVE, PBS, PMG, Docker, Kubernetes, and TrueNAS in one place
|
||||
- **Smart Alerts**: Adaptive, hysteresis-based thresholds that cut flapping noise, delivered via Discord, Slack, Telegram, Email, and more
|
||||
- **Auto-Discovery**: Automatically finds Proxmox nodes on your network
|
||||
- **Metrics History**: Persistent storage with configurable retention
|
||||
- **Recovery Views**: Backup, snapshot, and replication history for each platform (PBS, ZFS/TrueNAS, vSphere)
|
||||
## Quick start
|
||||
|
||||
### Multi-Platform
|
||||
- **Proxmox VE/PBS/PMG**: Full monitoring and management
|
||||
- **TrueNAS**: Pools, datasets, disks, ZFS snapshots, replication tasks, and alerts
|
||||
- **Kubernetes**: Complete K8s cluster monitoring via agents
|
||||
- **Docker/Podman**: Container and Swarm service monitoring
|
||||
- **OCI Containers**: Proxmox 9.1+ native container support
|
||||
Choose an exact version from the [latest release](https://github.com/rcourtman/Pulse/releases/latest)
|
||||
and keep that version pinned during installation.
|
||||
|
||||
### Security & Operations
|
||||
- **Secure by Design**: Credentials encrypted at rest, strict API scoping, agent commands disabled by default
|
||||
- **One-Click Updates**: Easy upgrades for supported deployments
|
||||
- **OIDC/SSO/SAML**: Single sign-on with multi-provider support
|
||||
- **Mobile Remote Access**: Relay protocol with end-to-end encryption for supported Pulse Mobile clients (Relay and above)
|
||||
- **Privacy Focused**: Outbound usage telemetry is enabled by default and [fully documented](docs/PRIVACY.md) — the payload uses a rotating pseudonymous install ID and does not include hostnames, credentials, names, email addresses, IP addresses, or infrastructure identifiers. Disable any time in Settings or via `PULSE_TELEMETRY=false`.
|
||||
### Docker
|
||||
|
||||
## 🧭 A Page for Every Platform
|
||||
|
||||
Patrol and alerts can only reason across your estate because Pulse sees all
|
||||
of it in one resource model. The UI keeps the platform-shaped views operators
|
||||
already know:
|
||||
- **Proxmox** (PVE, PBS, and PMG), **Docker**, **Kubernetes**, **TrueNAS**,
|
||||
**vSphere**, and **standalone machines** each get their own page
|
||||
- Storage and Recovery (backups, snapshots, replication) surface on the
|
||||
platform pages they belong to
|
||||
- **Alerts** and **Patrol** are top-level views across every platform
|
||||
|
||||
Power-user shortcuts:
|
||||
- `g p` → Proxmox, `g d` → Docker, `g k` → Kubernetes, `g n` → TrueNAS, `g v` → vSphere, `g s` → standalone machines
|
||||
- `g a` → Alerts, `g r` → Patrol, `g t` → Settings
|
||||
- `/` → search, `Cmd/Ctrl+K` → command palette, `?` → shortcuts help
|
||||
|
||||
## ⚡ Quick Start
|
||||
|
||||
> **Paid Pulse Pro / Relay / legacy customers:** GitHub release assets and the
|
||||
> public `rcourtman/pulse` Docker image are community builds. Activate your
|
||||
> license key under **Settings → Plans → Existing purchases** to unlock Pro
|
||||
> features. These community builds do not include the private Pulse Pro runtime hooks
|
||||
> (Audit Log, Audit Webhooks, RBAC, governed remediation). For those, use
|
||||
> <https://pulserelay.pro/download.html> with a **v6 activation key** (starts
|
||||
> with `ppk_live_`) to get the private Pulse Pro Docker image or Linux archive.
|
||||
> A v5 or legacy license key is not a `ppk_live_` activation key and will not
|
||||
> work on that page.
|
||||
|
||||
### Option 1: Proxmox LXC (Recommended)
|
||||
Replace `vX.Y.Z` with the exact release tag you want, verify the signed installer, then run it on your Proxmox host:
|
||||
|
||||
```bash
|
||||
export PULSE_VERSION=vX.Y.Z
|
||||
curl -fsSLO "https://github.com/rcourtman/Pulse/releases/download/${PULSE_VERSION}/install.sh"
|
||||
curl -fsSLO "https://github.com/rcourtman/Pulse/releases/download/${PULSE_VERSION}/install.sh.sshsig"
|
||||
ssh-keygen -Y verify \
|
||||
-f <(printf '%s\n' 'pulse-installer namespaces="pulse-install" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMZd/DaH+BldzOkq1A8KVTcFk73nAyrE8aJOyf7i00jm pulse-installer') \
|
||||
-I pulse-installer \
|
||||
-n pulse-install \
|
||||
-s install.sh.sshsig < install.sh
|
||||
bash install.sh --version "${PULSE_VERSION}"
|
||||
rm -f install.sh install.sh.sshsig
|
||||
```
|
||||
|
||||
Note: this installs the Pulse **server**. Agent installs and v5-to-v6 agent upgrades use the command generated in **Settings → Infrastructure → Install on a host** (served from `/install.sh` on your Pulse server).
|
||||
|
||||
Server and agent updates are separate lifecycle paths. Updating the server sets
|
||||
the version eligible v6 agents should reach, but it does not prove the fleet has
|
||||
converged. Current Unified Agents on Linux, Windows, and Docker-enabled hosts
|
||||
check shortly after startup and then hourly, install only a newer semantic
|
||||
version (including RC-to-stable), and retry after offline or failed checks.
|
||||
They bind the binary download to the exact server target so intermediary caches
|
||||
cannot silently return an older agent. v5 agents, PVE host agents, and agents
|
||||
with auto-update disabled or failed authentication, transport, trust, download,
|
||||
or self-test prerequisites need the manual per-host command from
|
||||
**Settings → Infrastructure**.
|
||||
|
||||
### Option 2: Docker
|
||||
```bash
|
||||
docker run -d \
|
||||
--name pulse \
|
||||
|
|
@ -134,133 +76,90 @@ docker run -d \
|
|||
rcourtman/pulse:vX.Y.Z
|
||||
```
|
||||
|
||||
Open Pulse at `http://<your-ip>:7655`.
|
||||
Open `http://<your-ip>:7655` and follow the bootstrap-token setup. Docker host
|
||||
monitoring is provided by the unified agent; the Pulse server container does
|
||||
not need the Docker socket.
|
||||
|
||||
## Local Development
|
||||
### Proxmox LXC, Linux, and Kubernetes
|
||||
|
||||
Use the managed dev runtime from the repo root:
|
||||
- [Signed Proxmox LXC and Linux installation](docs/INSTALL.md#quick-start-recommended)
|
||||
- [Docker Compose](docs/INSTALL.md#docker-compose)
|
||||
- [Kubernetes and Helm](docs/KUBERNETES.md)
|
||||
|
||||
The GitHub installer installs the Pulse server. Install and upgrade agents with
|
||||
the per-host command generated under **Settings → Infrastructure → Install on a
|
||||
host**.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> GitHub release assets and `rcourtman/pulse` images are Community builds.
|
||||
> Relay, Pro, and eligible legacy customers should use the private image or
|
||||
> Linux archive provided by the [Pulse download portal](https://pulserelay.pro/download.html).
|
||||
> Replacing a private Pro runtime with a public Community build removes its
|
||||
> private runtime hooks.
|
||||
|
||||
## Editions
|
||||
|
||||
- **Community** — self-hosted monitoring, seven days of metric history, core
|
||||
SSO, update alerts, and Patrol with your own provider or local model.
|
||||
- **Relay** — Community plus secure remote web access, Pulse Mobile pairing,
|
||||
push notifications, and fourteen days of history.
|
||||
- **Pro** — Relay plus Patrol investigation, governed fixes, ninety days of
|
||||
history, centralized agent profiles, RBAC, audit logging, and reporting.
|
||||
|
||||
Core self-hosted monitoring is not gated by monitored-system or child-resource
|
||||
volume. See the [runtime-aligned capability reference](docs/PULSE_PRO.md) and
|
||||
[current plans](https://pulserelay.pro) for details.
|
||||
|
||||
## Documentation
|
||||
|
||||
- [Install and deployment](docs/INSTALL.md)
|
||||
- [Upgrade from Pulse v5](docs/UPGRADE_v6.md)
|
||||
- [Configuration](docs/CONFIGURATION.md)
|
||||
- [Platform and agent guides](docs/README.md#platforms-and-agents)
|
||||
- [Pulse Intelligence](docs/AI.md)
|
||||
- [Security](SECURITY.md) and [privacy](docs/PRIVACY.md)
|
||||
- [Troubleshooting](docs/TROUBLESHOOTING.md)
|
||||
- [API reference](docs/API.md) and [architecture](ARCHITECTURE.md)
|
||||
|
||||
Localized getting started guides are available in
|
||||
[German](docs/i18n/de/README.md) and [Spanish](docs/i18n/es/README.md).
|
||||
|
||||
## Development
|
||||
|
||||
Pulse uses Go 1.26 and a SolidJS/TypeScript frontend. The managed development
|
||||
runtime starts the frontend at `http://127.0.0.1:5173` and proxies API and
|
||||
WebSocket traffic to the backend on port `7655`.
|
||||
|
||||
```bash
|
||||
npm ci
|
||||
npm --prefix frontend-modern ci
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Open `http://127.0.0.1:5173` in the browser. `5173` is the frontend dev shell,
|
||||
and it proxies `/api` and `/ws` to the backend on `7655`. `7655` is the backend
|
||||
dependency for API and websocket traffic, not the primary browser URL for local
|
||||
frontend development.
|
||||
Useful checks:
|
||||
|
||||
The managed dev runtime resets its local login to `admin` / `adminadminadmin`
|
||||
on startup unless you override it with `HOT_DEV_AUTH_USER` and
|
||||
`HOT_DEV_AUTH_PASS`.
|
||||
```bash
|
||||
go test ./...
|
||||
npm --prefix frontend-modern test
|
||||
npm --prefix frontend-modern run type-check
|
||||
python3 scripts/check_public_docs.py
|
||||
```
|
||||
|
||||
Canonical local dev commands:
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) before investing in a code change. Pulse
|
||||
uses an issue-first contribution process and does not normally accept
|
||||
unsolicited pull requests.
|
||||
|
||||
- `npm run dev` — start the managed runtime and reclaim the canonical dev ports if an older unmanaged session is still using them
|
||||
- `npm run dev:lab` — start the managed runtime in lab-agent mode, with the frontend/backend exposed on the LAN and Proxmox LXC Docker inventory enabled for installed lab agents
|
||||
- `npm run dev:status` — show frontend shell health, proxied API health, direct backend health, and listener ownership
|
||||
- `npm run dev:status:lab` — show status using the same LAN-bound lab-agent defaults used by `dev:lab`
|
||||
- `npm run dev:verify` — run the managed browser proof pack against the live dev runtime, including runtime recovery, the Patrol blocked-runtime page contract, and the desktop Recovery layout guard while the launcher suppresses unrelated backend rebuild churn for the duration of the proof pack
|
||||
- `npm run dev:verify:lab` — run the managed proof pack after applying lab-agent runtime defaults
|
||||
- `npm run dev:logs` — tail the managed runtime log
|
||||
- `npm run dev:backend-restart` — bounce only the managed backend through the launcher contract
|
||||
- `npm run dev:stop` — stop the managed runtime
|
||||
- `npm run dev:foreground` — run the foreground hot-reload launcher intentionally if you need an attached shell
|
||||
- `npm run dev:foreground:lab` — run the foreground hot-reload launcher with lab-agent defaults for troubleshooting
|
||||
## Community and support
|
||||
|
||||
If `npm run dev:verify` passes, the managed dev shell, proxy path, backend
|
||||
health endpoint, browser recovery path, Patrol blocked-runtime page behavior,
|
||||
and Recovery desktop history-table layout are all aligned.
|
||||
- Ask questions in [GitHub Discussions](https://github.com/rcourtman/Pulse/discussions).
|
||||
- Report reproducible bugs through [GitHub Issues](https://github.com/rcourtman/Pulse/issues).
|
||||
- Home Assistant users can use the community-maintained
|
||||
[Pulse add-ons](https://github.com/Kosztyk/homeassistant-addons).
|
||||
- If Pulse is useful to you, support its development through
|
||||
[GitHub Sponsors](https://github.com/sponsors/rcourtman) or
|
||||
[Ko-fi](https://ko-fi.com/rcourtman).
|
||||
|
||||
## 📚 Documentation
|
||||
## License
|
||||
|
||||
- **[Installation Guide](docs/INSTALL.md)**: Detailed instructions for Docker, Kubernetes, and bare metal.
|
||||
- **[Upgrade to v6](docs/UPGRADE_v6.md)**: Migration guide for upgrading from v5 to v6.
|
||||
- **[Configuration](docs/CONFIGURATION.md)**: Setup authentication, notifications, and advanced settings.
|
||||
- **[Security](SECURITY.md)**: Learn about Pulse's security model and best practices.
|
||||
- **[API Reference](docs/API.md)**: Integrate Pulse with your own tools.
|
||||
- **[Architecture](ARCHITECTURE.md)**: High-level system design and data flow.
|
||||
- **[AI Features](docs/AI.md)**: Pulse Assistant (Chat), Pulse Patrol, and the Pulse MCP external-agent adapter.
|
||||
- **[AI-Assisted Development](docs/AI_TRANSPARENCY.md)**: How AI tools are used to build and maintain Pulse itself.
|
||||
- **[Multi-Tenant](docs/MULTI_TENANT.md)**: Enterprise/internal multi-organization setup and configuration.
|
||||
- **[Troubleshooting](docs/TROUBLESHOOTING.md)**: Solutions to common issues.
|
||||
- **[Agent Security](docs/AGENT_SECURITY.md)**: Agent privilege model, Proxmox API-only choices, and checksum/signature verification.
|
||||
- **[Code Signing Policy](docs/CODE_SIGNING_POLICY.md)**: Build provenance, signing scope, approvals, and Windows publisher trust.
|
||||
- **[Docker Monitoring](docs/DOCKER.md)**: Setup and management of Docker agents.
|
||||
|
||||
## 🌐 Community Integrations
|
||||
|
||||
Community-maintained integrations and addons:
|
||||
|
||||
- **[Home Assistant Addons](https://github.com/Kosztyk/homeassistant-addons)** - Run Pulse Agent and Pulse Server as Home Assistant addons.
|
||||
|
||||
## 💳 Plans (Community / Relay / Pro / Cloud)
|
||||
|
||||
Pulse is full-featured for core monitoring in every self-hosted tier. Self-hosted
|
||||
pricing no longer sells more room for monitoring volume; paid value comes from
|
||||
convenience, history, AI operations, and advanced administration. Cloud remains
|
||||
the hosted Pulse path. MSP is request-assisted provider hosting, with one
|
||||
isolated Pulse runtime per client.
|
||||
|
||||
Self-hosted tiers:
|
||||
|
||||
| Plan | Price | Core monitoring | Metric history | Main value |
|
||||
|---|---:|---|---:|---|
|
||||
| Community | Free | Included | 7 days | Full self-hosted monitoring |
|
||||
| Relay | $39/yr or $4.99/mo | Included | 14 days | Remote web access, mobile app pairing, and push notifications |
|
||||
| Pro | $79/yr or $8.99/mo | Included | 90 days | Hands-on Patrol modes, issue investigation, verified fixes, and operations tooling |
|
||||
|
||||
Pulse still counts top-level monitored systems once no matter how they are
|
||||
collected. VMs, containers, pods, disks, backups, and other child resources
|
||||
under that system are included rather than counted separately, but that count is
|
||||
no longer the self-hosted paid gate.
|
||||
|
||||
Community keeps Patrol available with your own provider or local model. Relay
|
||||
remains the convenience tier, and Pro is the paid operations tier.
|
||||
|
||||
Runtime-aligned capability summary:
|
||||
|
||||
| Capability | Community | Relay | Pro | Cloud |
|
||||
|---|:---:|:---:|:---:|:---:|
|
||||
| Pulse Patrol (Background Health Checks) | ✅ | ✅ | ✅ | ✅ |
|
||||
| Remote Access / Mobile / Push | — | ✅ | ✅ | ✅ |
|
||||
| Patrol Investigates Issues and Explains the Root Cause | — | — | ✅ | ✅ |
|
||||
| Patrol Applies Safe Fixes and Verifies the Result | — | — | ✅ | ✅ |
|
||||
| Centralized Agent Profiles | — | — | ✅ | ✅ |
|
||||
| Update Alerts (Container/Package Updates) | ✅ | ✅ | ✅ | ✅ |
|
||||
| SSO (OIDC/SAML/Multi-Provider) | ✅ | ✅ | ✅ | ✅ |
|
||||
| Role-Based Access Control (RBAC) | — | — | ✅ | ✅ |
|
||||
| Enterprise Audit Logging | — | — | ✅ | ✅ |
|
||||
| Advanced Infrastructure Reporting (PDF/CSV) | — | — | ✅ | ✅ |
|
||||
| Extended Metric History | 7 days | 14 days | 90 days | 90 days |
|
||||
|
||||
Pulse Patrol runs on your schedule (every 10 minutes to every 7 days, default 6 hours) and finds:
|
||||
- ZFS pools approaching capacity
|
||||
- Backup jobs that silently failed
|
||||
- VMs stuck in restart loops
|
||||
- Clock drift across cluster nodes
|
||||
- Container health check failures
|
||||
|
||||
On self-hosted installs, Pulse Patrol uses the provider you configure from your
|
||||
Pulse server. That can be a commercial API key or a local model endpoint. Chat
|
||||
Assistant follows the same self-managed provider model.
|
||||
|
||||
Technical highlights:
|
||||
- Cross-system context (nodes, VMs, backups, containers, and metrics history)
|
||||
- LLM analysis with your provider plus alert-triggered root-cause investigations (Pro / hosted Cloud)
|
||||
- Optional safe remediation execution with command safety policies and audit trail
|
||||
- Centralized agent profiles for consistent fleet settings
|
||||
|
||||
**[Try the live demo →](https://demo.pulserelay.pro)** or **[learn more at pulserelay.pro](https://pulserelay.pro)**
|
||||
|
||||
Pulse plan technical details: [docs/PULSE_PRO.md](docs/PULSE_PRO.md)
|
||||
|
||||
## ❤️ Support Pulse Development
|
||||
|
||||
Pulse is maintained by one person. Sponsorships help cover the costs of the demo server, development tools, and domains. If Pulse saves you time, please consider supporting the project!
|
||||
|
||||
[](https://github.com/sponsors/rcourtman)
|
||||
[](https://ko-fi.com/rcourtman)
|
||||
|
||||
## 📄 License
|
||||
|
||||
MIT © [Richard Courtman](https://github.com/rcourtman). Use of Pulse Pro is subject to the [Terms of Service](TERMS.md).
|
||||
Pulse Community is available under the [MIT License](LICENSE). Pulse Pro is
|
||||
subject to the [Terms of Service](TERMS.md).
|
||||
|
|
|
|||
|
|
@ -1,5 +0,0 @@
|
|||
# Artifact Hub repository metadata file
|
||||
repositoryID: 01234567-89ab-cdef-0123-456789abcdef
|
||||
owners:
|
||||
- name: rcourtman
|
||||
email: pulse@rcourtman.dev
|
||||
|
|
@ -1,59 +0,0 @@
|
|||
# Security Audit Report
|
||||
|
||||
## Executive Summary
|
||||
A comprehensive security audit of the Pulse codebase was conducted, focusing on Remote Code Execution (RCE), Server-Side Request Forgery (SSRF), and Authentication mechanisms. Critical vulnerabilities identified in previous scans (Apprise RCE, Webhook SSRF) have been verified as fixed. No new critical vulnerabilities were found during this final review.
|
||||
|
||||
## Audit Findings
|
||||
|
||||
### 1. Apprise RCE (Fixed)
|
||||
- **Problem**: The `CLIPath` parameter in Apprise configuration was user-controllable and passed directly to `exec.Command`, allowing arbitrary command execution.
|
||||
- **Fix**: The `CLIPath` is now hardcoded to `"apprise"` in `NormalizeAppriseConfig` (`internal/notifications/notifications.go`), preventing users from injecting malicious paths.
|
||||
- **Verification**: Code review confirms `CLIPath` is sanitized before use.
|
||||
|
||||
### 2. Webhook SSRF & DNS Rebinding (Fixed)
|
||||
- **Problem**: Webhook URL validation checked the initial IP but was vulnerable to Time-of-Check Time-of-Use (TOCTOU) DNS rebinding attacks.
|
||||
- **Fix**: A custom `http.Transport` was implemented in `createSecureWebhookClient` (`internal/notifications/notifications.go`) that pins the DNS resolution to the validated IP address. Redirects are also re-validated.
|
||||
- **Verification**: The `DialContext` ensures the connection is made to the specific IP address that passed validation.
|
||||
|
||||
### 3. Agent Execution Security
|
||||
- **Analysis**: The `agentexec` WebSocket endpoint (`/api/agent/ws`) allows connections from any origin (`CheckOrigin: true`).
|
||||
- **Risk Assessment**: **Low**. Authentication is performed via the initial `agent_register` message payload containing the token. Browser-based attacks (CSWSH) are not effective because they cannot inject the token into the WebSocket message payload.
|
||||
- **Recommendations**: No immediate action required.
|
||||
|
||||
### 4. Admin Test Connection SSRF
|
||||
- **Analysis**: The `HandleTestConnection` endpoint allows admins to connect to arbitrary hosts (Proxmox/PBS/PMG) to verify configuration.
|
||||
- **Risk Assessment**: **Accepted Risk**. This is an intended feature for administrators. While it allows an authenticated admin to probe internal network ports, it is necessary for the application's function.
|
||||
- **Recommendations**: Ensure `PULSE_TRUSTED_PROXY_CIDRS` is configured if running in a sensitive environment to prevent IP spoofing, although unrelated to this specific feature.
|
||||
|
||||
### 5. Debug Endpoints
|
||||
- **Analysis**: Checked for exposure of `pprof` or other debug handlers.
|
||||
- **Findings**: No debug endpoints are exposed in the production router.
|
||||
|
||||
### 6. Authentication Bypass
|
||||
- **Analysis**: Reviewed `adminBypassEnabled` logic.
|
||||
- **Findings**: Bypass is strictly limited to development mode (`PULSE_DEV=true` or `NODE_ENV=development`) AND explicit opt-in (`ALLOW_ADMIN_BYPASS=1`). It cannot be accidentally enabled in production.
|
||||
|
||||
## Conclusion
|
||||
The application security posture has been significantly improved with the remediation of the RCE and SSRF vulnerabilities. The remaining identified risks are low or accepted features. The application is ready for release from a security perspective.
|
||||
|
||||
## Alert System Reliability Audit
|
||||
|
||||
### Executive Summary
|
||||
A focused audit of the Alert System was conducted to identify reliability issues such as stale alerts and incorrect clearing logic. Critical bugs causing "zombie interrupts" (stale alerts that never clear) were identified and fixed.
|
||||
|
||||
### Findings & Fixes
|
||||
|
||||
### 1. Stale Alerts on Node/Host Offline
|
||||
- **Problem**: When a Proxmox Node or Pulse Host Agent went offline, the system correctly raised a connectivity alert but failed to clear existing resource alerts (High CPU/Memory/Disk). This resulted in contradictory states (e.g., "Node Offline" and "High CPU" simultaneously).
|
||||
- **Fix**: Updated `CheckNode` and `HandleHostOffline` to explicitly clear all resource metric alerts when an offline state is confirmed.
|
||||
|
||||
### 2. Stale Alerts on Disabled Thresholds
|
||||
- **Problem**: For optional metrics (Guest Disk I/O, Network I/O, Node/Host Temperature, Disk Usage with Overrides), the system skipped the evaluation logic entirely if the threshold was disabled or nil. This prevented the clean-up logic from running, causing existing alerts to persist indefinitely after a rule was disabled.
|
||||
- **Fix**: Refactored the checking logic in `CheckGuest`, `CheckNode`, and `CheckHost` to execute unconditionally. The underlying `checkMetric` function now properly handles disabled thresholds by clearing any corresponding active alerts.
|
||||
|
||||
### 3. Missing Clear Logic for Global Disable
|
||||
- **Problem**: Disabling global alert settings (e.g., "Disable all Host alerts") sometimes left specific metric alerts active if they were not explicitly cleared during the state transition.
|
||||
- **Fix**: Verified and reinforced clearing mechanisms. Specifically, `CheckHost` disk monitoring was updated to ensure alerts are cleared even when specific disk overrides disable monitoring.
|
||||
|
||||
### Conclusion
|
||||
The reliability of the alert system has been significantly improved. Alerts will now correctly reflect the current state of resources, and disabling rules will reliably clear associated alerts.
|
||||
|
|
@ -652,7 +652,7 @@ For unattended displays (wall monitors, dashboards), use a kiosk token to avoid
|
|||
|
||||
---
|
||||
|
||||
## TrueNAS Integration {#truenas}
|
||||
## TrueNAS
|
||||
|
||||
Pulse v6 supports first-class TrueNAS SCALE and CORE monitoring.
|
||||
|
||||
|
|
@ -687,7 +687,7 @@ TrueNAS connections are stored encrypted in `truenas.enc`.
|
|||
|
||||
---
|
||||
|
||||
## Relay / Mobile Remote Access (Relay and Above) {#relay}
|
||||
## Relay
|
||||
|
||||
The relay protocol provides end-to-end encrypted remote access foundations for Pulse mobile connectivity.
|
||||
|
||||
|
|
|
|||
28
docs/FAQ.md
28
docs/FAQ.md
|
|
@ -58,16 +58,26 @@ See [VM Disk Monitoring](VM_DISK_MONITORING.md) for details.
|
|||
Yes! If Pulse detects Ceph storage, it automatically queries cluster health, OSD status, and pool usage. No extra config needed.
|
||||
|
||||
### Does Pulse monitor TrueNAS?
|
||||
Yes. Pulse v6 includes first-class TrueNAS SCALE/CORE integration. Add your TrueNAS server in **Settings → TrueNAS** with the URL and API key. Pulse monitors the appliance, native VMs, apps, pools, datasets, disks, ZFS snapshots, replication tasks, and alerts. TrueNAS resources appear in the TrueNAS, Infrastructure, Storage, and Recovery views.
|
||||
Yes. Pulse includes first-class TrueNAS SCALE/CORE integration. Add your
|
||||
TrueNAS server under **Settings → Infrastructure → Platform connections** with
|
||||
the URL and API key. Pulse monitors the appliance, native VMs, apps, pools,
|
||||
datasets, disks, ZFS snapshots, replication tasks, and alerts. Those resources
|
||||
appear on the dedicated TrueNAS page.
|
||||
|
||||
### Where did my pages go? (Unified Navigation)
|
||||
Pulse v6 organises the UI by **task** instead of **platform**:
|
||||
- **Infrastructure** → all hosts (Proxmox, Docker, K8s, TrueNAS)
|
||||
- **Workloads** → VMs, LXCs, containers, pods
|
||||
- **Storage** → all storage pools
|
||||
- **Recovery** → backups, snapshots, replication
|
||||
### How is navigation organised in Pulse v6?
|
||||
Pulse uses platform-shaped top-level pages:
|
||||
|
||||
Legacy URLs (`/proxmox`, `/docker`, `/kubernetes`, `/hosts`, `/services`) redirect automatically. See [Migration Guide](MIGRATION_UNIFIED_NAV.md) for the full mapping.
|
||||
- **Proxmox**, **Docker**, **Kubernetes**, **TrueNAS**, **vSphere**, and
|
||||
**Machines** keep platform-specific inventory and workflows together.
|
||||
- Storage, snapshots, backups, and replication appear inside the platform page
|
||||
they belong to.
|
||||
- **Alerts**, **Actions**, and **Patrol** provide cross-platform operational
|
||||
views.
|
||||
|
||||
The short-lived unified `/workloads`, `/storage`, and `/recovery` top-level
|
||||
navigation was retired during the v6 prerelease cycle. See the
|
||||
[historical migration note](MIGRATION_UNIFIED_NAV.md) if you are comparing an
|
||||
older release candidate.
|
||||
|
||||
### Can I disable alerts for specific metrics?
|
||||
Yes. Go to **Alerts → Thresholds** and use the On/Off toggle next to any metric while editing, or set the value to `-1`. You can do this globally or per-resource (VM/Node).
|
||||
|
|
@ -111,7 +121,7 @@ pct exec <ctid> -- pulse bootstrap-token
|
|||
If you only missed the token during a fresh install (no password set yet), skip the first two commands and just read it back with the last one.
|
||||
|
||||
### How do I enable HTTPS?
|
||||
Set `HTTPS_ENABLED=true` and provide `TLS_CERT_FILE` and `TLS_KEY_FILE` environment variables. See [Configuration](CONFIGURATION.md#https--tls).
|
||||
Set `HTTPS_ENABLED=true` and provide `TLS_CERT_FILE` and `TLS_KEY_FILE` environment variables. See [Configuration](CONFIGURATION.md#-https--tls).
|
||||
|
||||
### Can I use Single Sign-On (SSO)?
|
||||
Yes. Pulse supports **OIDC** and **SAML** SSO providers, with multi-provider support (multiple IdPs active simultaneously). Configure in **Settings → Security → SSO Providers**. Pulse also supports Proxy Auth (Authentik, Authelia, Cloudflare). See [Proxy Auth Guide](PROXY_AUTH.md).
|
||||
|
|
|
|||
163
docs/README.md
163
docs/README.md
|
|
@ -1,106 +1,103 @@
|
|||
# 📚 Pulse Documentation
|
||||
# Pulse documentation
|
||||
|
||||
Welcome to the Pulse documentation portal. Here you'll find everything you need to install, configure, and master Pulse.
|
||||
Start here for installation, platform setup, security, operations, and Pulse
|
||||
Intelligence. Commands, configuration keys, image names, API fields, and
|
||||
product identifiers remain untranslated in localized guides.
|
||||
|
||||
---
|
||||
## Start here
|
||||
|
||||
## 🚀 Getting Started
|
||||
- [Install Pulse](INSTALL.md) — signed Proxmox/Linux installation, Docker,
|
||||
Docker Compose, Kubernetes, and first-run setup.
|
||||
- [Upgrade from Pulse v5](UPGRADE_v6.md) — migration prerequisites, rollback,
|
||||
agent continuity, and post-upgrade checks.
|
||||
- [Configure Pulse](CONFIGURATION.md) — authentication, notifications,
|
||||
discovery, retention, and system settings.
|
||||
- [Deployment models](DEPLOYMENT_MODELS.md) — data locations, lifecycle, and
|
||||
differences between supported deployment paths.
|
||||
- [Troubleshooting](TROUBLESHOOTING.md) and [FAQ](FAQ.md) — common failures,
|
||||
diagnostics, and operator questions.
|
||||
|
||||
- **Localized getting started**:
|
||||
[Deutsch](i18n/de/README.md) • [Español](i18n/es/README.md).
|
||||
These first-wave pages cover the public install path and preserve commands,
|
||||
config keys, image names, activation keys, and product identifiers exactly.
|
||||
- **[Installation Guide](INSTALL.md)**
|
||||
Step-by-step guides for Docker, Kubernetes, and bare metal.
|
||||
- **[Configuration](CONFIGURATION.md)**
|
||||
Learn how to configure authentication, notifications (Email, Discord, etc.), and system settings.
|
||||
- **[Deployment Models](DEPLOYMENT_MODELS.md)**
|
||||
Where config lives, how updates work, and what differs per deployment.
|
||||
- **[Migration Guide](MIGRATION.md)**
|
||||
Moving to a new server? Here's how to export and import your data safely.
|
||||
- **[Upgrade to v6](UPGRADE_v6.md)**
|
||||
Practical upgrade guidance and post-upgrade checks for Pulse v6.
|
||||
- **[FAQ](FAQ.md)**
|
||||
Common questions and quick answers.
|
||||
Localized getting started guides: [Deutsch](i18n/de/README.md) ·
|
||||
[Español](i18n/es/README.md)
|
||||
|
||||
## 🛠️ Deployment & Operations
|
||||
## Platforms and agents
|
||||
|
||||
- **[Docker Guide](DOCKER.md)** – Advanced Docker & Compose configurations.
|
||||
- **[Kubernetes](KUBERNETES.md)** – Helm charts, ingress, and HA setups.
|
||||
- **[Reverse Proxy](REVERSE_PROXY.md)** – Nginx, Caddy, Traefik, and Cloudflare Tunnel recipes.
|
||||
- **[Troubleshooting](TROUBLESHOOTING.md)** – Deep dive into common issues and logs.
|
||||
- [Proxmox Backup Server](PBS.md)
|
||||
- [Proxmox Mail Gateway](MAIL_GATEWAY.md)
|
||||
- [Docker and Podman](DOCKER.md)
|
||||
- [Kubernetes and Helm](KUBERNETES.md)
|
||||
- [TrueNAS SCALE and CORE](TRUENAS.md)
|
||||
- [Unified Agent](UNIFIED_AGENT.md)
|
||||
- [Agent security](AGENT_SECURITY.md)
|
||||
- [VM disk monitoring](VM_DISK_MONITORING.md)
|
||||
- [ZFS monitoring](ZFS_MONITORING.md)
|
||||
- [Temperature monitoring](TEMPERATURE_MONITORING.md)
|
||||
|
||||
## 🔐 Security
|
||||
VMware vSphere support is early access. Current builds expose dedicated
|
||||
vSphere inventory and recovery context, but operators should validate the
|
||||
integration against their own vCenter before production use.
|
||||
|
||||
- **[Security Policy](../SECURITY.md)** – The core security model (Encryption, Auth, API Scopes).
|
||||
- **[Privacy](PRIVACY.md)** – What leaves your network (and what doesn’t).
|
||||
- **[OIDC / SSO](OIDC.md)** – OIDC Single Sign-On configuration (Authentik, Keycloak, Azure AD, etc.).
|
||||
- **[Proxy Auth](PROXY_AUTH.md)** – Authentik/Authelia/Cloudflare proxy authentication configuration.
|
||||
- **[Agent Security](AGENT_SECURITY.md)** – Agent privilege model, Proxmox API-only choices, and self-update verification.
|
||||
## Monitoring and operations
|
||||
|
||||
## 📖 Advanced Topics (Relay / Pro / legacy Pro+ / Cloud)
|
||||
- [Metrics history](METRICS_HISTORY.md)
|
||||
- [Recovery data](RECOVERY.md)
|
||||
- [Webhooks](WEBHOOKS.md)
|
||||
- [Automatic updates](AUTO_UPDATE.md)
|
||||
- [Centralized agent management](CENTRALIZED_MANAGEMENT.md) (Pro)
|
||||
- [Operational trust model](OPERATIONAL_TRUST.md)
|
||||
- [Current product screenshots](SCREENSHOTS.md)
|
||||
|
||||
- **[AI Modes & Safety](AI_AUTONOMY.md)** – Configure Patrol mode, assistant control levels, investigation tuning, and safety guardrails.
|
||||
- **[Role-Based Access Control (RBAC)](RBAC.md)** – Define custom roles, assign permissions, and integrate with OIDC group mapping.
|
||||
- **[Audit Logging](AUDIT_LOGGING.md)** – Tamper-evident event logging for compliance, with query, export, and signature verification.
|
||||
## Pulse Intelligence
|
||||
|
||||
## ✨ New in 6.0
|
||||
- [Assistant, Patrol, and external-agent overview](AI.md)
|
||||
- [Patrol modes and safety](AI_AUTONOMY.md)
|
||||
- [Assistant safety model](ASSISTANT_SAFETY.md)
|
||||
- [External agent HTTP and MCP substrate](AGENT_SUBSTRATE.md)
|
||||
|
||||
- **[Unified Resource Model](UNIFIED_RESOURCES.md)** – How all platforms merge into one model with task-based navigation.
|
||||
- **[Unified Navigation Migration](MIGRATION_UNIFIED_NAV.md)** – Upgrading from platform-specific tabs to v6 navigation.
|
||||
- **[TrueNAS Integration](TRUENAS.md)** – First-class TrueNAS SCALE/CORE monitoring (pools, datasets, disks, snapshots, replication).
|
||||
- **[Relay / Pulse Mobile Handoff](RELAY.md)** – End-to-end encrypted relay for supported Pulse Mobile clients (Relay and above).
|
||||
- **[Recovery Central](RECOVERY.md)** – Unified backup, snapshot, and replication view across all providers.
|
||||
- **[Pulse Cloud (Hosted)](CLOUD.md)** – Fully managed hosting with automatic updates and backups.
|
||||
- **[Pulse Intelligence](AI.md)** – Pulse Assistant, Patrol findings, alert analysis, governed actions, and forecasts.
|
||||
- **[Metrics History](METRICS_HISTORY.md)** – Persistent metrics storage with configurable retention.
|
||||
- **[Mail Gateway](MAIL_GATEWAY.md)** – Proxmox Mail Gateway (PMG) monitoring.
|
||||
- **[Auto Updates](AUTO_UPDATE.md)** – One-click updates for supported deployments.
|
||||
- **[Multi-Tenant Organizations](MULTI_TENANT.md)** – Isolate infrastructure by organization (Enterprise, opt-in).
|
||||
- **[Pulse for MSPs](MSP.md)** – Provider operations guide: per-client isolation, split ingress, alert routing, branded reports.
|
||||
- **[Entitlements Overhaul](PULSE_PRO.md)** – Capability-key-based feature gating across Community/Relay/Pro/Cloud, with legacy Pro+ continuity still supported.
|
||||
Patrol watch-only analysis is available on Community with a local model or the
|
||||
operator's own provider. Investigation and governed fixes require the relevant
|
||||
Pulse Pro capabilities.
|
||||
|
||||
## 💳 Plans (Community / Relay / Pro / Cloud)
|
||||
## Security, privacy, and access
|
||||
|
||||
Pulse is available in three self-hosted tiers plus hosted Cloud:
|
||||
- [Security guide](../SECURITY.md)
|
||||
- [Privacy and telemetry disclosure](PRIVACY.md)
|
||||
- [OIDC and SSO](OIDC.md)
|
||||
- [Proxy authentication](PROXY_AUTH.md)
|
||||
- [Role-based access control](RBAC.md) (Pro)
|
||||
- [Audit logging](AUDIT_LOGGING.md) (Pro)
|
||||
- [Reverse proxy configuration](REVERSE_PROXY.md)
|
||||
- [Code-signing policy](CODE_SIGNING_POLICY.md)
|
||||
|
||||
- **Community**: Free self-hosted monitoring with core monitoring included and 7-day history.
|
||||
- **Relay**: Adds secure remote access to the Pulse web UI, Pulse Mobile pairing for handoff, push notifications, and 14-day history.
|
||||
- **Pro**: Adds hands-on Patrol modes, issue investigation, governed fixes, verified outcomes, operations tooling, governance features, and 90-day history.
|
||||
- **Cloud**: Hosted Pulse with Pro-level capabilities; hosted pricing is unchanged by the self-hosted model lock.
|
||||
## Plans and managed access
|
||||
|
||||
- **[Learn more at pulserelay.pro](https://pulserelay.pro)**
|
||||
- **[Plans and entitlements](PULSE_PRO.md)** (includes the Community/Relay/Pro/Cloud matrix)
|
||||
- **[AI deep dive](AI.md)**
|
||||
- **[Multi-Tenant Organizations (Enterprise)](MULTI_TENANT.md)** — Isolate infrastructure by organization for MSPs and multi-datacenter deployments.
|
||||
- [Community, Relay, and Pro capabilities](PULSE_PRO.md)
|
||||
- [Relay and Pulse Mobile handoff](RELAY.md)
|
||||
- [Multi-tenant organizations](MULTI_TENANT.md) (Enterprise/custom)
|
||||
- [Provider-hosted MSP operations](MSP.md) (request-assisted)
|
||||
|
||||
## 📡 Monitoring & Agents
|
||||
Pulse Cloud is not generally available. Ordinary self-hosted Pulse remains the
|
||||
primary installation path; MSP and Enterprise access are explicit commercial
|
||||
paths rather than defaults in self-hosted setup.
|
||||
|
||||
- **[Unified Agent](UNIFIED_AGENT.md)** – Single binary for host, Docker, and Kubernetes monitoring.
|
||||
- **[Centralized Agent Management (Pro/Cloud)](CENTRALIZED_MANAGEMENT.md)** – Agent profiles and remote config.
|
||||
- **[Proxmox Backup Server](PBS.md)** – PBS integration, direct API vs PVE passthrough, token setup.
|
||||
- **[TrueNAS](TRUENAS.md)** – TrueNAS SCALE/CORE integration.
|
||||
- **[ZFS Monitoring](ZFS_MONITORING.md)** – Proxmox-native ZFS pool monitoring.
|
||||
- **[Storage Architecture](STORAGE_ARCHITECTURE.md)** – Proposed canonical storage, disk, S.M.A.R.T., and topology model for making storage genuinely operator-useful.
|
||||
- **[VM Disk Monitoring](VM_DISK_MONITORING.md)** – Enabling QEMU Guest Agent for disk stats.
|
||||
- **[Temperature Monitoring](TEMPERATURE_MONITORING.md)** – Agent-based temperature monitoring (`pulse-agent --enable-proxmox`). Sensor proxy has been removed.
|
||||
- **[Webhooks](WEBHOOKS.md)** – Custom notification payloads.
|
||||
## Development and reference
|
||||
|
||||
## 💻 Development
|
||||
- [REST API](API.md)
|
||||
- [Architecture](../ARCHITECTURE.md)
|
||||
- [Contributing](../CONTRIBUTING.md)
|
||||
- [Release notes index](RELEASE_NOTES.md)
|
||||
- [Development transparency disclosure](AI_TRANSPARENCY.md)
|
||||
|
||||
- **[API Reference](API.md)** – Complete REST API documentation.
|
||||
- **[Architecture](../ARCHITECTURE.md)** – System design and component interaction.
|
||||
- **[Contributing](../CONTRIBUTING.md)** – How to contribute to Pulse.
|
||||
- **[AI-Assisted Development](AI_TRANSPARENCY.md)** – How AI tools are used to build and maintain Pulse, and where their output is labelled.
|
||||
Detailed design notes and dated migration specifications may remain in this
|
||||
directory for maintainers, but they are not operator setup guides unless they
|
||||
are linked from the sections above.
|
||||
|
||||
## 📁 Previous Versions
|
||||
## Previous versions and migrations
|
||||
|
||||
- **[Upgrade to v5](UPGRADE_v5.md)** – Upgrade guidance for v4 → v5 migrations.
|
||||
- **[v6 Release Promotion Policy](release-control/v6/internal/RELEASE_PROMOTION_POLICY.md)** – Canonical stable-vs-prerelease promotion rules and rollback expectations.
|
||||
- **[v6 Prerelease Runbook](releases/V6_PRERELEASE_RUNBOOK.md)** – Internal release operations used during the v6 prerelease period.
|
||||
- [Upgrade from v4 to v5](UPGRADE_v5.md)
|
||||
- [Retired unified-navigation migration](MIGRATION_UNIFIED_NAV.md) — historical
|
||||
context only; current Pulse uses platform-shaped navigation.
|
||||
- [Move a Pulse installation](MIGRATION.md)
|
||||
|
||||
---
|
||||
|
||||
Found a bug or have a suggestion?
|
||||
|
||||
[](https://github.com/rcourtman/Pulse/issues)
|
||||
Found a bug? Use the [issue forms](https://github.com/rcourtman/Pulse/issues/new/choose).
|
||||
For setup questions, use [GitHub Discussions](https://github.com/rcourtman/Pulse/discussions).
|
||||
|
|
|
|||
|
|
@ -123,5 +123,5 @@ Pulse Mobile can pair with multiple Pulse instances. Each pairing has its own en
|
|||
## See Also
|
||||
|
||||
- [Configuration Guide](CONFIGURATION.md#relay) — environment variables
|
||||
- [Security](../SECURITY.md#relay-security-pro) — relay security details
|
||||
- [Security](../SECURITY.md#relay-security-relay-and-above) — relay security details
|
||||
- [Plans & Entitlements](PULSE_PRO.md) — feature availability by plan
|
||||
|
|
|
|||
|
|
@ -1,35 +1,24 @@
|
|||
# Pulse Screenshots
|
||||
# Pulse screenshots
|
||||
|
||||
> **Note:** Screenshots below show the Pulse v6 interface with unified, task-based navigation. Your dashboard may look different from these examples depending on your infrastructure and configuration.
|
||||
These captures come from the public read-only demo and show the current
|
||||
platform-shaped Pulse interface. Explore the same mock environment at
|
||||
[demo.pulserelay.pro](https://demo.pulserelay.pro) with `demo` / `demo`.
|
||||
|
||||
## Dashboard Overview (Dark Mode)
|
||||
|
||||
*Real-time monitoring dashboard with summary panels showing aggregate CPU, memory, and storage usage across your entire fleet. The dashboard adapts its layout to the number of connected nodes and resources. Professional dark theme optimized for 24/7 monitoring setups.*
|
||||
## Proxmox workspace
|
||||
|
||||
## Infrastructure
|
||||
|
||||
*Unified Infrastructure page showing all hosts across Proxmox VE, Docker, Kubernetes, and TrueNAS in a single table. Hosts from multiple data sources are identity-matched and merged automatically. Filter by source, status, or search by name.*
|
||||
|
||||
|
||||
## Storage Management
|
||||
|
||||
*Comprehensive storage view displaying all storage pools across Proxmox nodes and TrueNAS systems with usage percentages, allocated vs used space, and visual indicators. Monitors local, ZFS, LVM, Ceph, and network storage types in a unified interface.*
|
||||
The Proxmox page keeps node health, guests, storage, backup freshness, Ceph,
|
||||
replication, and mail-gateway context together. Docker, Kubernetes, TrueNAS,
|
||||
vSphere, and Machines use the same platform-page pattern.
|
||||
|
||||
## Recovery Central
|
||||
|
||||
*Centralized recovery management showing backups, snapshots, and replication points from PBS and TrueNAS in one place. Track outcomes, sizes, retention, and quickly identify failed or missing recovery points across your entire infrastructure. Time-range buttons (24h/7d/30d/custom) and the synchronized bar chart make it easy to focus on exactly the window you care about.*
|
||||
## Patrol attention queue
|
||||
|
||||
## Alerts & Configuration
|
||||
|
||||
*Unified alerts view showing active alerts and configuration settings. Monitor current system alerts with severity indicators, affected resources, and acknowledgment status. Configure thresholds, notification settings, quiet hours, and alert grouping. Bulk actions allow managing multiple alerts simultaneously.*
|
||||
|
||||
|
||||
## Alert History & Analytics
|
||||
|
||||
*Comprehensive alert history with frequency visualization. Filter by severity (warnings, critical, info), search specific resources, and track resolution times. Visual timeline helps identify patterns and recurring issues.*
|
||||
Patrol turns cross-platform checks into a plain operational queue. Watch-only
|
||||
mode reports findings without starting changes; higher-autonomy modes remain
|
||||
subject to the configured plan, policy, approval, and verification boundaries.
|
||||
|
||||
## Settings & Node Management
|
||||
|
||||
*Manage Proxmox nodes, agent connections, and TrueNAS instances through the UI. Add/remove nodes, configure credentials securely (encrypted at rest), set polling intervals, and manage authentication settings. Quick health check shows connection status for all nodes.*
|
||||
|
||||
## Mobile Responsive Design
|
||||
|
||||
*Fully responsive mobile interface with a dedicated bottom tab bar for touch navigation. Supports mobile remote access through Pulse Relay for secure monitoring on the go. Touch-optimized controls, adaptive layouts, and the command palette ensure full functionality on smartphones and tablets.*
|
||||
Screenshots use generated demo data. Names, metrics, alerts, and infrastructure
|
||||
state shown here do not represent a real deployment.
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 458 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 308 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 261 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 118 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 244 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 146 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 85 KiB |
BIN
docs/images/pulse-patrol.png
Normal file
BIN
docs/images/pulse-patrol.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 289 KiB |
BIN
docs/images/pulse-workspace.png
Normal file
BIN
docs/images/pulse-workspace.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 380 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 410 KiB After Width: | Height: | Size: 830 KiB |
168
scripts/check_public_docs.py
Normal file
168
scripts/check_public_docs.py
Normal file
|
|
@ -0,0 +1,168 @@
|
|||
#!/usr/bin/env python3
|
||||
"""Validate the repository's public documentation surface."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from urllib.parse import unquote
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
|
||||
ROOT_DOCS = (
|
||||
"README.md",
|
||||
"CONTRIBUTING.md",
|
||||
"CHANGELOG.md",
|
||||
"ARCHITECTURE.md",
|
||||
"SECURITY.md",
|
||||
"TERMS.md",
|
||||
)
|
||||
|
||||
CURRENT_PRODUCT_DOCS = (
|
||||
"README.md",
|
||||
"ARCHITECTURE.md",
|
||||
"docs/README.md",
|
||||
"docs/FAQ.md",
|
||||
"docs/SCREENSHOTS.md",
|
||||
)
|
||||
|
||||
MARKDOWN_LINK = re.compile(r"!?\[[^\]]*\]\(([^)]+)\)")
|
||||
HTML_ASSET = re.compile(r"(?:src|href)=[\"']([^\"']+)[\"']")
|
||||
HEADING = re.compile(r"^#{1,6}\s+(.+?)\s*#*\s*$", re.MULTILINE)
|
||||
|
||||
|
||||
def public_markdown_files() -> list[Path]:
|
||||
files = [ROOT / name for name in ROOT_DOCS if (ROOT / name).exists()]
|
||||
files.extend(sorted((ROOT / "docs").glob("*.md")))
|
||||
files.extend(sorted((ROOT / "docs" / "i18n").glob("**/*.md")))
|
||||
files.extend(sorted((ROOT / ".github" / "ISSUE_TEMPLATE").glob("*.md")))
|
||||
return files
|
||||
|
||||
|
||||
def split_target(raw_target: str) -> tuple[str, str]:
|
||||
target = raw_target.strip().strip("<>")
|
||||
if " " in target and not target.startswith("#"):
|
||||
target = target.split(" ", 1)[0]
|
||||
path, separator, anchor = target.partition("#")
|
||||
return unquote(path), unquote(anchor) if separator else ""
|
||||
|
||||
|
||||
def heading_slug(value: str) -> str:
|
||||
value = re.sub(r"<[^>]+>", "", value)
|
||||
value = re.sub(r"[`*_~]", "", value).lower()
|
||||
value = re.sub(r"[^\w\s-]", "", value, flags=re.UNICODE)
|
||||
return re.sub(r"\s", "-", value).strip("-")
|
||||
|
||||
|
||||
def anchors_for(path: Path) -> set[str]:
|
||||
text = path.read_text(encoding="utf-8", errors="replace")
|
||||
anchors: set[str] = set()
|
||||
counts: dict[str, int] = {}
|
||||
for heading in HEADING.findall(text):
|
||||
base = heading_slug(heading)
|
||||
if not base:
|
||||
continue
|
||||
count = counts.get(base, 0)
|
||||
anchors.add(base if count == 0 else f"{base}-{count}")
|
||||
counts[base] = count + 1
|
||||
return anchors
|
||||
|
||||
|
||||
def check_links(files: list[Path]) -> list[str]:
|
||||
errors: list[str] = []
|
||||
anchor_cache: dict[Path, set[str]] = {}
|
||||
|
||||
for source in files:
|
||||
text = source.read_text(encoding="utf-8", errors="replace")
|
||||
targets = [match.group(1) for match in MARKDOWN_LINK.finditer(text)]
|
||||
targets.extend(match.group(1) for match in HTML_ASSET.finditer(text))
|
||||
|
||||
for raw_target in targets:
|
||||
if raw_target.startswith(("http://", "https://", "mailto:", "data:")):
|
||||
continue
|
||||
target_path, anchor = split_target(raw_target)
|
||||
resolved = source if not target_path else (source.parent / target_path).resolve()
|
||||
display_source = source.relative_to(ROOT)
|
||||
|
||||
if not resolved.exists():
|
||||
errors.append(f"{display_source}: missing local target {raw_target}")
|
||||
continue
|
||||
|
||||
# GitHub retains some emoji variation selectors in generated
|
||||
# anchors. Those anchors are stable in the rendered document but
|
||||
# are not practical to reproduce with the standard library, so
|
||||
# validate ordinary text anchors and still verify the target file
|
||||
# for emoji-prefixed anchors.
|
||||
if (
|
||||
anchor
|
||||
and resolved.suffix.lower() == ".md"
|
||||
and not anchor.startswith(("-", "\ufe0f"))
|
||||
):
|
||||
anchors = anchor_cache.setdefault(resolved, anchors_for(resolved))
|
||||
if anchor.lower() not in anchors:
|
||||
errors.append(
|
||||
f"{display_source}: missing anchor #{anchor} in "
|
||||
f"{resolved.relative_to(ROOT)}"
|
||||
)
|
||||
|
||||
return errors
|
||||
|
||||
|
||||
def check_current_claims() -> list[str]:
|
||||
errors: list[str] = []
|
||||
retired_patterns = {
|
||||
r"organis(?:e|z)(?:s|ed)\s+the\s+ui\s+by\s+task":
|
||||
"retired task-based navigation claim",
|
||||
r"unified,\s*task-based navigation":
|
||||
"retired unified-navigation screenshot claim",
|
||||
r"canonical v6 task surfaces":
|
||||
"retired canonical task-surface claim",
|
||||
}
|
||||
|
||||
for relative_path in CURRENT_PRODUCT_DOCS:
|
||||
path = ROOT / relative_path
|
||||
text = path.read_text(encoding="utf-8", errors="replace")
|
||||
for pattern, label in retired_patterns.items():
|
||||
if re.search(pattern, text, flags=re.IGNORECASE):
|
||||
errors.append(f"{relative_path}: {label}")
|
||||
|
||||
readme_lines = (ROOT / "README.md").read_text(encoding="utf-8").splitlines()
|
||||
if len(readme_lines) > 220:
|
||||
errors.append(
|
||||
f"README.md: {len(readme_lines)} lines exceeds the 220-line landing-page budget"
|
||||
)
|
||||
|
||||
issue_config = (ROOT / ".github" / "ISSUE_TEMPLATE" / "config.yml").read_text(
|
||||
encoding="utf-8"
|
||||
)
|
||||
if "github.com/rcourtman/Pulse/wiki" in issue_config:
|
||||
errors.append(".github/ISSUE_TEMPLATE/config.yml: documentation link points at the retired wiki")
|
||||
|
||||
artifact_hub = ROOT / "artifacthub-repo.yml"
|
||||
if artifact_hub.exists() and "01234567-89ab-cdef-0123-456789abcdef" in artifact_hub.read_text(
|
||||
encoding="utf-8"
|
||||
):
|
||||
errors.append("artifacthub-repo.yml: placeholder repository ID is not publishable metadata")
|
||||
|
||||
return errors
|
||||
|
||||
|
||||
def main() -> int:
|
||||
files = public_markdown_files()
|
||||
errors = check_links(files)
|
||||
errors.extend(check_current_claims())
|
||||
|
||||
if errors:
|
||||
print("Public documentation check failed:", file=sys.stderr)
|
||||
for error in errors:
|
||||
print(f"- {error}", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
print(f"Public documentation check passed ({len(files)} Markdown files).")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
Loading…
Add table
Add a link
Reference in a new issue