Skip to content

Plan: Update Checker — Remaining Polish

Status

State: Active Started: 2026-05-14

Context

The check-updates.py script from the shuttle branch is now installed and working. It generates reports with registry queries, risk classification, and markdown output. Several polish items remain to make it production-ready for automated use.

Shuttle has this as backlog/docker-auto-updates.md.

Goals

  • [ ] Schedule weekly automatic scans
  • [ ] Implement post-update health check verification
  • [ ] Set up report retention (prune old reports)
  • [ ] Add release notes URL resolution
  • [ ] Add grouping logic for batch updates

Steps

Step 1: Weekly Scan Scheduling

Set up a cron job (via Ansible setup_crontab.yml or Herbes cron job) for weekly scanning:

Option A — Ansible cron: Add to /ansible/sepia/setup_crontab.yml:

- name: weekly container update scan
  hour: '8'
  weekday: '0'
  job: cd /opt && python3 /opt/scripts/container-updates/check-updates.py report

Option B — Hermes cron job:

cronjob action=create name="weekly container update report" schedule="0 8 * * 0" prompt="Run check-updates.py report in /opt and summarize any critical updates"
  • Verification: Report appears weekly in REFERENCE/container-updates/

Step 2: Report Retention

Add logic to prune reports older than 8 weeks:

find /opt/docs/REFERENCE/container-updates/ -name "*.md" -mtime +56 -delete

Add to crontab or HEARTBEAT.md as a periodic task.

  • Verification: Old reports are removed, last 8 weeks preserved

Step 3: Post-Update Health Verification

Currently the apply subcommand (if implemented) updates the image and restarts but doesn't verify the container passes its health check.

Target behavior:

check-updates.py apply --service grafana
  1. Pull new image
  2. docker compose up -d grafana
  3. Wait up to 60s for health check to pass
  4. If unhealthy → roll back, log failure
  5. If healthy → log success, update report

This requires adding a docker_health_check(service_name, timeout=60) function to the script.

  • Verification: Simulate with a failing health check — script rolls back correctly

Resolve release notes URLs from registry API responses where available. Docker Hub returns GitHub URLs for some images. Add a release_notes field to the report:

Service Current Latest Release Notes
grafana 11.4.0 11.6.14 link
  • Verification: Report includes clickable release notes URLs

Step 5: Grouping Logic

Add summary grouping to the report, e.g.:

## Grouped by Image Source
LinuxServer.io: 3 updates
Docker Hub official: 4 updates
GHCR: 2 updates
  • Verification: Report footer includes grouped summary

Not Planned

  • Automatic apply: Too risky for a home server with unscheduled maintenance windows. Manual review before apply is preferred.
  • Gitea integration: Sepia doesn't use Gitea for issue tracking.
  • PLANS/active/container-updates-may-2026.md (initial batch of updates)
  • scripts/container-updates/check-updates.py
  • REFERENCE/container-updates/ (report directory)

Created: 2026-05-14