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 update-failure help read-only before recovery

pulse-triage[bot]f4ca9855dff5
diff --git a/docs/AUTO_UPDATE.md b/docs/AUTO_UPDATE.md
index 88b9128373..3cae6988f7 100644
--- a/docs/AUTO_UPDATE.md
+++ b/docs/AUTO_UPDATE.md
@@ -247,12 +247,52 @@ Systemd/LXC update runs write detailed logs to `/var/log/pulse/update-<timestamp
3. Ensure you have the latest frontend loaded (hard refresh)
### Update failed
-1. Check the error message in the progress modal
-2. Review logs: `journalctl -u pulse -n 100` or `/var/log/pulse/update-<timestamp>.log`
-3. Verify disk space is available for both the extracted release payload and a rollback snapshot of your current install
-4. Check network connectivity to GitHub
+
+First identify what was updated: this guide covers the **Pulse server**.
+An installed agent has its [own update path](UNIFIED_AGENT.md#auto-update).
+For a monitored Docker workload, use the [failed or pending workload checks](DOCKER.md#check-a-failed-or-pending-workload-update)
+on that workload's host, not inside Pulse.
+
+Keep the original target version, attempt time, last displayed step and redacted
+error from the progress modal or updater log. If Pulse still opens, check
+**Settings → System → Updates** for its running version and retain the existing
+**Update History** entry when available. Check the ordinary UI and monitoring
+freshness too. A failed updater exit, disconnected progress stream or stuck
+modal does not establish which version is running or whether rollback succeeded.
+Do not rerun an update, restart or reinstall merely to obtain evidence.
+
+For server logs, use the [bounded Pulse log readers](TROUBLESHOOTING.md#inspect-notification-logs)
+for the actual deployment. Run them on the Pulse host, or inside the Pulse LXC,
+not on a monitored guest. They have a deadline as well as time and record limits;
+do not substitute a log-follow command or an unbounded reader if they fail.
+Inspect the relevant part of the original `/var/log/pulse/update-<timestamp>.log`
+privately when that systemd/LXC update produced one; a server journal alone may
+not contain the installer failure. Missing logs are unavailable evidence, not
+proof that no change occurred. Do not enable Debug or repeat the failing action.
+
+If the error names disk space, check headroom on the actual staging, installation
+and data filesystems before planning another attempt; the release payload and
+rollback snapshot both need space. Do not delete configuration backups, keys or
+history to clear the error. A download error needs its original HTTP, connectivity
+or certificate evidence; do not disable TLS verification or switch a paid Pro
+installation to the public Community runtime as a workaround.
+
+Share only the relevant times, versions, failed step and redacted error. Keep
+full logs, service environments, configuration, credentials and private backup
+paths out of public reports.
### Service won't restart after update
-1. Check systemd status: `systemctl status pulse`
-2. View recent logs: `journalctl -u pulse -f`
-3. Manually restore from backup if needed
+
+Distinguish the **Pulse service** from the separate updater service: a failed
+`pulse-update.service` is not proof that `pulse` is stopped. Use the read-only
+service discovery in [Manual Rollback](#manual-rollback), substituting the actual
+service name (`pulse-backend` on some older installs), and the bounded log readers
+above. For Docker, use the [current container-state and image checks](DOCKER.md#check-a-failed-or-pending-workload-update)
+with the Pulse server's container name. A running process or container alone is
+not proof that the UI, saved connections and history are healthy.
+
+If recovery is needed, follow [Manual Rollback](#manual-rollback): preserve the
+failed state, verify the intended backup's version and complete scope, and use
+the stopped-service recovery procedure. An absent or partial backup is a reason
+to stop, not to overwrite live data, create an empty data directory or retry the
+update. Do not restore a guessed snapshot just because the progress modal failed.
diff --git a/docs/DOCKER.md b/docs/DOCKER.md
index 313d0f229e..7d435a312e 100644
--- a/docs/DOCKER.md
+++ b/docs/DOCKER.md
@@ -429,9 +429,12 @@ Pulse can start, stop, and restart Docker / Podman containers directly from the
not just a restart. SSO accounts and temporary lockouts have separate paths.
- **Logs**
- ```bash
- docker logs -f pulse
- ```
+ Use the [bounded Docker log reader](TROUBLESHOOTING.md#inspect-notification-logs)
+ on the host running the Pulse server, with its actual container name. It reads
+ both output streams with a deadline, time window and record limit; a failed
+ read is not an empty log. Review the excerpt privately and share only the
+ relevant redacted error, not credentials, private host details or the full log.
+ Do not follow logs indefinitely or repeat a failed update to collect evidence.
- **Shell Access**
```bash
diff --git a/frontend-modern/public/docs/AUTO_UPDATE.md b/frontend-modern/public/docs/AUTO_UPDATE.md
index 88b9128373..3cae6988f7 100644
--- a/frontend-modern/public/docs/AUTO_UPDATE.md
+++ b/frontend-modern/public/docs/AUTO_UPDATE.md
@@ -247,12 +247,52 @@ Systemd/LXC update runs write detailed logs to `/var/log/pulse/update-<timestamp
3. Ensure you have the latest frontend loaded (hard refresh)
### Update failed
-1. Check the error message in the progress modal
-2. Review logs: `journalctl -u pulse -n 100` or `/var/log/pulse/update-<timestamp>.log`
-3. Verify disk space is available for both the extracted release payload and a rollback snapshot of your current install
-4. Check network connectivity to GitHub
+
+First identify what was updated: this guide covers the **Pulse server**.
+An installed agent has its [own update path](UNIFIED_AGENT.md#auto-update).
+For a monitored Docker workload, use the [failed or pending workload checks](DOCKER.md#check-a-failed-or-pending-workload-update)
+on that workload's host, not inside Pulse.
+
+Keep the original target version, attempt time, last displayed step and redacted
+error from the progress modal or updater log. If Pulse still opens, check
+**Settings → System → Updates** for its running version and retain the existing
+**Update History** entry when available. Check the ordinary UI and monitoring
+freshness too. A failed updater exit, disconnected progress stream or stuck
+modal does not establish which version is running or whether rollback succeeded.
+Do not rerun an update, restart or reinstall merely to obtain evidence.
+
+For server logs, use the [bounded Pulse log readers](TROUBLESHOOTING.md#inspect-notification-logs)
+for the actual deployment. Run them on the Pulse host, or inside the Pulse LXC,
+not on a monitored guest. They have a deadline as well as time and record limits;
+do not substitute a log-follow command or an unbounded reader if they fail.
+Inspect the relevant part of the original `/var/log/pulse/update-<timestamp>.log`
+privately when that systemd/LXC update produced one; a server journal alone may
+not contain the installer failure. Missing logs are unavailable evidence, not
+proof that no change occurred. Do not enable Debug or repeat the failing action.
+
+If the error names disk space, check headroom on the actual staging, installation
+and data filesystems before planning another attempt; the release payload and
+rollback snapshot both need space. Do not delete configuration backups, keys or
+history to clear the error. A download error needs its original HTTP, connectivity
+or certificate evidence; do not disable TLS verification or switch a paid Pro
+installation to the public Community runtime as a workaround.
+
+Share only the relevant times, versions, failed step and redacted error. Keep
+full logs, service environments, configuration, credentials and private backup
+paths out of public reports.
### Service won't restart after update
-1. Check systemd status: `systemctl status pulse`
-2. View recent logs: `journalctl -u pulse -f`
-3. Manually restore from backup if needed
+
+Distinguish the **Pulse service** from the separate updater service: a failed
+`pulse-update.service` is not proof that `pulse` is stopped. Use the read-only
+service discovery in [Manual Rollback](#manual-rollback), substituting the actual
+service name (`pulse-backend` on some older installs), and the bounded log readers
+above. For Docker, use the [current container-state and image checks](DOCKER.md#check-a-failed-or-pending-workload-update)
+with the Pulse server's container name. A running process or container alone is
+not proof that the UI, saved connections and history are healthy.
+
+If recovery is needed, follow [Manual Rollback](#manual-rollback): preserve the
+failed state, verify the intended backup's version and complete scope, and use
+the stopped-service recovery procedure. An absent or partial backup is a reason
+to stop, not to overwrite live data, create an empty data directory or retry the
+update. Do not restore a guessed snapshot just because the progress modal failed.
diff --git a/frontend-modern/public/docs/DOCKER.md b/frontend-modern/public/docs/DOCKER.md
index 313d0f229e..7d435a312e 100644
--- a/frontend-modern/public/docs/DOCKER.md
+++ b/frontend-modern/public/docs/DOCKER.md
@@ -429,9 +429,12 @@ Pulse can start, stop, and restart Docker / Podman containers directly from the
not just a restart. SSO accounts and temporary lockouts have separate paths.
- **Logs**
- ```bash
- docker logs -f pulse
- ```
+ Use the [bounded Docker log reader](TROUBLESHOOTING.md#inspect-notification-logs)
+ on the host running the Pulse server, with its actual container name. It reads
+ both output streams with a deadline, time window and record limit; a failed
+ read is not an empty log. Review the excerpt privately and share only the
+ relevant redacted error, not credentials, private host details or the full log.
+ Do not follow logs indefinitely or repeat a failed update to collect evidence.
- **Shell Access**
```bash
diff --git a/scripts/tests/test_update_recovery_docs.py b/scripts/tests/test_update_recovery_docs.py
index c7660bd559..bd5fabcfa3 100644
--- a/scripts/tests/test_update_recovery_docs.py
+++ b/scripts/tests/test_update_recovery_docs.py
@@ -245,6 +245,47 @@ class UpdateRecoveryDocsTest(unittest.TestCase):
self.assertIn("Check for receipt", ui)
self.assertIn("refreshReceipt()", ui)
+ def test_update_failure_entry_reuses_bounded_readers_before_any_recovery(self):
+ text = " ".join(section("AUTO_UPDATE", "Update failed", "###").split())
+ for phrase in ("**Pulse server**", "UNIFIED_AGENT.md#auto-update",
+ "DOCKER.md#check-a-failed-or-pending-workload-update",
+ "target version, attempt time, last displayed step",
+ "**Update History**", "running version", "monitoring freshness",
+ "TROUBLESHOOTING.md#inspect-notification-logs",
+ "deadline as well as time and record limits",
+ "Do not rerun an update, restart or reinstall",
+ "server journal alone may not contain the installer failure",
+ "not proof that no change occurred",
+ "Do not delete configuration backups, keys or history",
+ "do not disable TLS verification",
+ "public Community runtime", "out of public reports"):
+ self.assertIn(phrase, text)
+ self.assertNotRegex(text, r"journalctl\b|docker logs\b|```")
+
+ def test_restart_failure_entry_distinguishes_updater_and_requires_matched_backup(self):
+ text = " ".join(section("AUTO_UPDATE", "Service won't restart after update", "###").split())
+ for phrase in ("`pulse-update.service` is not proof that `pulse` is stopped",
+ "read-only service discovery", "[Manual Rollback](#manual-rollback)",
+ "actual service name", "Pulse server's container name",
+ "not proof that the UI, saved connections and history are healthy",
+ "preserve the failed state", "backup's version and complete scope",
+ "stopped-service recovery procedure", "absent or partial backup",
+ "not to overwrite live data", "Do not restore a guessed snapshot"):
+ self.assertIn(phrase, text)
+ self.assertNotRegex(text, r"journalctl\b|systemctl status\b|docker logs\b|```")
+
+ def test_docker_log_entry_reaches_the_same_deadline_bounded_server_reader(self):
+ text = section("DOCKER", "🛠️ Troubleshooting").split("- **Logs**\n", 1)[1].split(
+ "- **Shell Access**", 1)[0]
+ text = " ".join(text.split())
+ for phrase in ("TROUBLESHOOTING.md#inspect-notification-logs",
+ "host running the Pulse server", "actual container name",
+ "both output streams", "deadline, time window and record limit",
+ "failed read is not an empty log", "Review the excerpt privately",
+ "Do not follow logs indefinitely or repeat a failed update"):
+ self.assertIn(phrase, text)
+ self.assertNotRegex(text, r"docker logs\b|```")
+
if __name__ == "__main__":
unittest.main()