mirror of
https://github.com/rcourtman/Pulse.git
synced 2026-02-18 00:17:39 +01:00
105 lines
4.5 KiB
Markdown
105 lines
4.5 KiB
Markdown
# 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
|
||
1. Navigate to **Settings → System → Updates**.
|
||
2. Toggle **Automatic Updates** on. The backend persists `autoUpdateEnabled:true`
|
||
and surfaces a reminder to enable the timer.
|
||
3. On the host, run:
|
||
```bash
|
||
sudo systemctl enable --now pulse-update.timer
|
||
sudo systemctl status pulse-update.timer --no-pager
|
||
```
|
||
4. To disable later, toggle the UI switch off **and** run
|
||
`sudo systemctl disable --now pulse-update.timer`.
|
||
|
||
### From the CLI only
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
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
|
||
|
||
1. Inspect the failing history entry:
|
||
```bash
|
||
curl -s http://localhost:7655/api/updates/history?limit=1 | jq '.entries[0]'
|
||
```
|
||
Common statuses: `failed`, `rolled_back`, `succeeded`.
|
||
2. Review `/var/log/pulse/update-YYYYMMDDHHMMSS.log` for the stack trace.
|
||
3. To revert, redeploy the previous release:
|
||
```bash
|
||
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.
|
||
4. 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.
|