Pulse Automatic Update Runbook

Automatic updates are handled by three systemd units that live on host-mode installations:

Component	Purpose	File
`pulse-update.timer`	Schedules daily checks (02:00 + 0‑4 h jitter)	`/etc/systemd/system/pulse-update.timer`
`pulse-update.service`	Runs a single update cycle when triggered	`/etc/systemd/system/pulse-update.service`
`scripts/pulse-auto-update.sh`	Fetches release metadata, downloads binaries, restarts Pulse	`/opt/pulse/scripts/pulse-auto-update.sh`

Docker and Kubernetes deployments do not use this flow—manage upgrades via your orchestrator.

Prerequisites

autoUpdateEnabled must be true in /var/lib/pulse/system.json (or toggled in Settings → System → Updates → Automatic Updates).
pulse.service must be healthy—the update service short-circuits if Pulse is not running.
Host needs outbound HTTPS access to github.com and objects.githubusercontent.com.

Enable or Disable

From the UI

Navigate to Settings → System → Updates.
Toggle Automatic Updates on. The backend persists autoUpdateEnabled:true and surfaces a reminder to enable the timer.

On the host, run:

sudo systemctl enable --now pulse-update.timer
sudo systemctl status pulse-update.timer --no-pager

To disable later, toggle the UI switch off and run sudo systemctl disable --now pulse-update.timer.

From the CLI only

# Opt in
sudo jq '.autoUpdateEnabled=true' /var/lib/pulse/system.json | sudo tee /var/lib/pulse/system.json >/dev/null
sudo systemctl daemon-reload
sudo systemctl enable --now pulse-update.timer

# Opt out
sudo jq '.autoUpdateEnabled=false' /var/lib/pulse/system.json | sudo tee /var/lib/pulse/system.json >/dev/null
sudo systemctl disable --now pulse-update.timer

Editing system.json while Pulse is running is safe, but prefer the UI so validation rules stay in place.

Trigger a Manual Run

Use this when testing new releases or after changing firewall rules:

sudo systemctl start pulse-update.service
sudo journalctl -u pulse-update -n 50

The oneshot service exits when the script finishes. A successful run logs the new version and writes an entry to update-history.jsonl.

Observability Checklist

Timer status: systemctl list-timers pulse-update
History API: curl -s http://localhost:7655/api/updates/history | jq '.entries[0]'
Raw log: /var/log/pulse/update-*.log (referenced inside the history entry’s log_path field)
Journal: journalctl -u pulse-update -f
Backups: The script records backup_path in history (defaults to /etc/pulse.backup.<timestamp>). Ensure the path exists before acknowledging the rollout.

Failure Handling & Rollback

Inspect the failing history entry:

curl -s http://localhost:7655/api/updates/history?limit=1 | jq '.entries[0]'

Common statuses: failed, rolled_back, succeeded.

Review /var/log/pulse/update-YYYYMMDDHHMMSS.log for the stack trace.
To revert, redeploy the previous release:
```
sudo /opt/pulse/install.sh --version v4.30.0
```
or use the main installer command from the update history output. The installer restores the backup_path recorded earlier when you choose Rollback in the UI.
Confirm Pulse is healthy (systemctl status pulse.service) and that /api/updates/history now contains a rolled_back entry referencing the same event_id.

Troubleshooting

Symptom	Resolution
`Auto-updates disabled in configuration` in journal	Set `autoUpdateEnabled:true` (UI or edit `system.json`) and restart the timer.
`pulse-update.timer` immediately exits	Ensure `systemd` knows about the units (`sudo systemctl daemon-reload`) and that `pulse.service` exists (installer may not have run with `--enable-auto-updates`).
`github.com` errors / rate limit	The script retries via the release redirect. For proxied environments set `https_proxy` before the service runs.
Update succeeds but Pulse stays on previous version	Check `journalctl -u pulse-update` for `restart failed`; Pulse only switches after the service restarts successfully.
Timer enabled but no history entries	Verify time has passed since enablement (timer includes random delay) or start the service manually to seed the first run.

Document each run (success or rollback) in your change journal with the event_id from /api/updates/history so you can cross-reference audit trails.

4.5 KiB Raw Blame History Unescape Escape