Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
Keep source-build update help off live executables
pulse-triage[bot]5f9962409fed
diff --git a/docs/AUTO_UPDATE.md b/docs/AUTO_UPDATE.mdindex 3cae6988f7..38dbff640e 100644--- a/docs/AUTO_UPDATE.md+++ b/docs/AUTO_UPDATE.md@@ -21,7 +21,7 @@ For v5, PVE, disabled, or failed agent updates, use **Agent Doctor** at| **ProxmoxVE LXC** | ✅ Yes | In-app update button || **Systemd Service** | ✅ Yes | In-app update button || **Docker** | ❌ Manual | Pull new image |-| **Source Build** | ❌ Manual | Git pull + rebuild |+| **Source Build** | ❌ Manual | Build, then install through the existing deployment procedure |## Using One-Click Updates@@ -62,7 +62,12 @@ In **Settings → System → Updates**:| Setting | Description ||---------|-------------|| **Update Channel** | Stable (recommended for production) or Pre-release (opt-in preview) |-| **Auto-Check** | Enable or disable automatic updates |+| **Automatic Stable Updates** | Allow unattended stable updates on supported host installations with an installed update timer |++The update timer must already be installed and enabled for unattended updates.+Saving the UI preference does not provision or start a missing timer. Check the+existing deployment rather than editing `system.json` or creating another+update service to make the preference take effect.### Stored Settings (system.json)@@ -112,12 +117,37 @@ sudo /bin/update### Source Build-```bash-cd /path/to/pulse-git pull-make build-sudo systemctl restart pulse-```+`make build` writes a `pulse` binary in the source checkout. It does not install+that binary into the running service's executable path. Restarting the service+after a build can therefore restart the old installed binary; if the service+runs directly from the checkout, building there can instead overwrite its live+executable. Do not build in the active installation directory.++For a production update, prefer the exact signed release and the+[existing-installation update procedure](INSTALL.md#-updates).+Keep private Pro installations on their private runtime; a public source build+is not a replacement for it.++If you intentionally maintain a source-built deployment:++1. Select the intended source tag or commit explicitly in a separate build+ checkout, preserving local changes. A moving `main` branch is development+ source, not the latest published stable release.+2. Use that checkout's declared toolchain and locked dependencies. Build and+ check the resulting binary's version before stopping the running service;+ a successful build alone is not an installed update.+3. Install through your existing deployment procedure, preserving its service+ identity, executable path, configuration, credentials and data. Stage the+ replacement separately; do not copy onto a running executable or remove+ the previous binary and recovery snapshots first. If the active executable+ path or recovery procedure is unknown, stop before changing the service.+4. Restore only a service that was active before the update, then confirm the+ running version, ordinary collection and notification delivery. Retain the+ previous binary and state backup until recovery is verified; a restart or+ version check alone does not establish healthy monitoring.++Do not pull, rebuild or restart just to reproduce an update failure. Follow+[update preparation and recovery limits](DEPLOYMENT_MODELS.md#updates-by-model) before another attempt.## Rollbackdiff --git a/docs/operations/AUTO_UPDATE.md b/docs/operations/AUTO_UPDATE.mdindex 778db69b6b..5b34bef86b 100644--- a/docs/operations/AUTO_UPDATE.md+++ b/docs/operations/AUTO_UPDATE.md@@ -1,51 +1,22 @@-# 🔄 Automatic Updates-Manage Pulse auto-updates on host-mode installations.--> **Note**: Docker/Kubernetes users should manage updates via their orchestrator.--## ⚙️ Components--| File | Purpose |-| :--- | :--- |-| `pulse-update.timer` | Daily check (02:00 + jitter). |-| `pulse-update.service` | Runs the update script. |-| `pulse-auto-update.sh` | Fetches release & restarts Pulse (`/opt/pulse/scripts/pulse-auto-update.sh`). |--**Release channel note:** the systemd timer script tracks GitHub `releases/latest` (stable). The internal `rc` channel only affects manual and in-app pre-release selection. `stable` is the only recommended channel for paid or production environments.--## 🚀 Enable/Disable--### Via UI (Recommended)-**Settings → System → Updates**.--### Via CLI-```bash-# Enable-sudo jq '.autoUpdateEnabled=true' /etc/pulse/system.json > /tmp/system.json && sudo mv /tmp/system.json /etc/pulse/system.json-sudo systemctl enable --now pulse-update.timer--# Disable-sudo jq '.autoUpdateEnabled=false' /etc/pulse/system.json > /tmp/system.json && sudo mv /tmp/system.json /etc/pulse/system.json-sudo systemctl disable --now pulse-update.timer-```--## 🧪 Manual Run-Test the update process:-```bash-sudo systemctl start pulse-update.service-journalctl -u pulse-update -f-```--## 🔍 Observability-* **History**: in-app updates are tracked via `GET /api/updates/history` (admin auth required) and stored in `update-history.jsonl` under `/etc/pulse` or `/data`. The systemd timer script does not record update history entries.-* **Logs**: `journalctl -u pulse-update -f` or `journalctl -t pulse-auto-update -f` for timer runs. In-app updates write detailed logs to `/var/log/pulse/update-<timestamp>.log`.--## ↩️ Rollback-If an update fails:-1. Check logs: `journalctl -u pulse-update -f` or `journalctl -t pulse-auto-update -f`.-2. The timer script keeps a temporary backup under `/tmp/pulse-backup-<timestamp>` during the update; failures auto-restore from that backup and then clean it up.-3. If you need to pin a specific version, re-run the installer with a version:- ```bash- sudo /bin/update --version vX.Y.Z- ```- `/bin/update` is installed by the supported Pulse server installer. If your host does not have it yet, use the signed server-installer flow in [INSTALL.md](../INSTALL.md). Agent updates still use the `/install.sh` command generated in **Settings → Infrastructure → Install on a host**.+# Automatic updates on installed servers++Use the [Pulse Server Automatic Updates guide](../AUTO_UPDATE.md) for the+current server update, timer, manual-update and recovery procedures. Server+updates and Pulse Agent updates are separate jobs.++Saving **Automatic Stable Updates** does not provision or start a missing+systemd update timer. Timer scheduling belongs to the installed deployment;+check its existing service and timer before changing automation. Source-built+servers do not use unattended release updates, and Docker/Kubernetes servers+are updated through their existing deployment manager.++Do not rewrite `system.json` through a shared temporary file to change update+preferences: that can expose configuration and replace its ownership or+permissions. Use the current guide and preserve the existing deployment's+configuration, credentials and data.++A failed update does not prove that the old version is still running or that+automatic rollback restored all state. Check the running version and service+health before retrying or restoring, keep the original failure evidence and+recovery snapshots, and follow the guide's qualified rollback procedure.+Do not start an update service just to test a reported failure.diff --git a/frontend-modern/public/docs/AUTO_UPDATE.md b/frontend-modern/public/docs/AUTO_UPDATE.mdindex 3cae6988f7..38dbff640e 100644--- a/frontend-modern/public/docs/AUTO_UPDATE.md+++ b/frontend-modern/public/docs/AUTO_UPDATE.md@@ -21,7 +21,7 @@ For v5, PVE, disabled, or failed agent updates, use **Agent Doctor** at| **ProxmoxVE LXC** | ✅ Yes | In-app update button || **Systemd Service** | ✅ Yes | In-app update button || **Docker** | ❌ Manual | Pull new image |-| **Source Build** | ❌ Manual | Git pull + rebuild |+| **Source Build** | ❌ Manual | Build, then install through the existing deployment procedure |## Using One-Click Updates@@ -62,7 +62,12 @@ In **Settings → System → Updates**:| Setting | Description ||---------|-------------|| **Update Channel** | Stable (recommended for production) or Pre-release (opt-in preview) |-| **Auto-Check** | Enable or disable automatic updates |+| **Automatic Stable Updates** | Allow unattended stable updates on supported host installations with an installed update timer |++The update timer must already be installed and enabled for unattended updates.+Saving the UI preference does not provision or start a missing timer. Check the+existing deployment rather than editing `system.json` or creating another+update service to make the preference take effect.### Stored Settings (system.json)@@ -112,12 +117,37 @@ sudo /bin/update### Source Build-```bash-cd /path/to/pulse-git pull-make build-sudo systemctl restart pulse-```+`make build` writes a `pulse` binary in the source checkout. It does not install+that binary into the running service's executable path. Restarting the service+after a build can therefore restart the old installed binary; if the service+runs directly from the checkout, building there can instead overwrite its live+executable. Do not build in the active installation directory.++For a production update, prefer the exact signed release and the+[existing-installation update procedure](INSTALL.md#-updates).+Keep private Pro installations on their private runtime; a public source build+is not a replacement for it.++If you intentionally maintain a source-built deployment:++1. Select the intended source tag or commit explicitly in a separate build+ checkout, preserving local changes. A moving `main` branch is development+ source, not the latest published stable release.+2. Use that checkout's declared toolchain and locked dependencies. Build and+ check the resulting binary's version before stopping the running service;+ a successful build alone is not an installed update.+3. Install through your existing deployment procedure, preserving its service+ identity, executable path, configuration, credentials and data. Stage the+ replacement separately; do not copy onto a running executable or remove+ the previous binary and recovery snapshots first. If the active executable+ path or recovery procedure is unknown, stop before changing the service.+4. Restore only a service that was active before the update, then confirm the+ running version, ordinary collection and notification delivery. Retain the+ previous binary and state backup until recovery is verified; a restart or+ version check alone does not establish healthy monitoring.++Do not pull, rebuild or restart just to reproduce an update failure. Follow+[update preparation and recovery limits](DEPLOYMENT_MODELS.md#updates-by-model) before another attempt.## Rollbackdiff --git a/frontend-modern/src/features/docs/__tests__/sourceBuildUpdateGuide.test.ts b/frontend-modern/src/features/docs/__tests__/sourceBuildUpdateGuide.test.tsnew file mode 100644index 0000000000..058e94ba74--- /dev/null+++ b/frontend-modern/src/features/docs/__tests__/sourceBuildUpdateGuide.test.ts@@ -0,0 +1,113 @@+import { readFileSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';+import { describe, expect, it } from 'vitest';+import { UPDATES_PANEL_COPY } from '@/utils/updatesPresentation';+import { renderDocMarkdown } from '../docMarkdown';++const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../..');+const read = (name: string) => readFileSync(path.join(root, name), 'utf8');+const source = readFileSync(+ process.env.PULSE_SOURCE_UPDATE_GUIDE_TEST_INPUT ??+ path.join(root, 'frontend-modern/public/docs/AUTO_UPDATE.md'),+ 'utf8',+);+const legacy = readFileSync(+ process.env.PULSE_LEGACY_UPDATE_GUIDE_TEST_INPUT ??+ path.join(root, 'docs/operations/AUTO_UPDATE.md'),+ 'utf8',+);++function render(markdown: string, name = 'AUTO_UPDATE'): HTMLElement {+ const article = document.createElement('article');+ article.innerHTML = renderDocMarkdown(markdown, name);+ return article;+}++function section(id: string): HTMLElement {+ const heading = render(source).querySelector(`#${id}`);+ expect(heading).not.toBeNull();+ const result = document.createElement('section');+ for (let next = heading!.nextElementSibling; next; next = next.nextElementSibling) {+ if (/^H[1-6]$/.test(next.tagName)) break;+ result.appendChild(next.cloneNode(true));+ }+ return result;+}++const prose = (element: HTMLElement) => (element.textContent ?? '').replace(/\s+/g, ' ').trim();++describe('source-built server update help', () => {+ it('distinguishes checkout build output from the installed executable', () => {+ // Bind the explanation to the actual development Makefile, not a native update claim.+ const makefile = read('Makefile');+ expect(makefile).toContain('backend:\n\tgo build -o pulse ./cmd/pulse');+ expect(makefile).toContain('build: frontend backend');+ const element = section('source-build');+ const text = prose(element);+ expect(text).toContain('writes a pulse binary in the source checkout');+ expect(text).toContain("does not install that binary into the running service's executable path");+ expect(text).toContain('restart the old installed binary');+ expect(text).toContain('Do not build in the active installation directory');+ expect(element.querySelector('pre')).toBeNull();+ expect(source).not.toContain('git pull\nmake build\nsudo systemctl restart pulse');+ });++ it('requires deliberate source selection and safe admission before an outage', () => {+ const text = prose(section('source-build'));+ expect(text).toContain('source tag or commit explicitly in a separate build checkout');+ expect(text).toContain('preserving local changes');+ expect(text).toContain('main branch is development source, not the latest published stable');+ expect(text).toContain("checkout's declared toolchain and locked dependencies");+ expect(text).toContain("binary's version before stopping the running service");+ expect(text).toContain('do not copy onto a running executable');+ expect(text).toContain('recovery procedure is unknown, stop before changing the service');+ });++ it('preserves edition and persistent state and does not equate restart with recovery', () => {+ const text = prose(section('source-build'));+ expect(text).toContain('Keep private Pro installations on their private runtime');+ expect(text).toContain('service identity, executable path, configuration, credentials and data');+ expect(text).toContain('Restore only a service that was active before the update');+ expect(text).toContain('running version, ordinary collection and notification delivery');+ expect(text).toContain('previous binary and state backup until recovery is verified');+ expect(text).toContain('Do not pull, rebuild or restart just to reproduce');+ });++ it('routes preparation and recovery to real headings in the shipped docs', () => {+ const links = [...section('source-build').querySelectorAll('a[href]')];+ expect(links.map((link) => link.getAttribute('href'))).toEqual([+ '/docs/INSTALL#-updates',+ '/docs/DEPLOYMENT_MODELS#updates-by-model',+ ]);+ for (const link of links) {+ const [name, fragment] = link.getAttribute('href')!.slice('/docs/'.length).split('#');+ expect(render(read(`frontend-modern/public/docs/${name}.md`), name).querySelector(`#${fragment}`))+ .not.toBeNull();+ expect(link.hasAttribute('data-doc-link')).toBe(true);+ expect(link.hasAttribute('target')).toBe(false);+ }+ });++ it('retires shared temporary configuration writes and unconditional rollback advice', () => {+ const text = prose(render(legacy));+ expect(text).toContain('Do not rewrite system.json through a shared temporary file');+ expect(text).toContain('expose configuration and replace its ownership or permissions');+ expect(text).toContain('does not prove that the old version is still running');+ expect(text).toContain('automatic rollback restored all state');+ expect(text).toContain('keep the original failure evidence and recovery snapshots');+ expect(text).toContain('Do not start an update service just to test a reported failure');+ expect(render(legacy).querySelector('pre')).toBeNull();+ expect(legacy).not.toContain('/tmp/system.json');+ expect(legacy).not.toContain('failures auto-restore');+ });++ it('uses the current UI label without treating preference storage as timer installation', () => {+ const text = prose(render(source));+ expect(text).toContain(UPDATES_PANEL_COPY.autoUpdateTitle);+ expect(text).toContain('Saving the UI preference does not provision or start a missing timer');+ expect(text).toContain('systemd timer');+ expect(text).toContain('unattended systemd auto-updates remain stable-only');+ expect(read('frontend-modern/public/docs/AUTO_UPDATE.md')).toBe(read('docs/AUTO_UPDATE.md'));+ });+});