Skip to content

armgit / Pulse

Public Imported from GitHub
0

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.

Keep source-build update help off live executables

pulse-triage[bot]5f9962409fed
diff --git a/docs/AUTO_UPDATE.md b/docs/AUTO_UPDATE.md
index 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.
## Rollback
diff --git a/docs/operations/AUTO_UPDATE.md b/docs/operations/AUTO_UPDATE.md
index 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.md
index 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.
## Rollback
diff --git a/frontend-modern/src/features/docs/__tests__/sourceBuildUpdateGuide.test.ts b/frontend-modern/src/features/docs/__tests__/sourceBuildUpdateGuide.test.ts
new file mode 100644
index 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'));
+ });
+});