Docker-Update/README.md

docker-update

Docker Compose stack manager for sammons-server (Ubuntu Server 24.04).

Discovers every Compose project on the host, updates it (git pull or registry pull as appropriate), logs results, and provides an interactive fzf browser for reviewing past runs and managing containers.

---

Commands

Command	What it does
docker-update	Update every Compose stack, save log
docker-update log	Browse past update logs in fzf
docker-update debug	Dry-run — shows what would happen, no changes

docker-update

Detects whether each project is tracked by a git repo or uses registry images, then runs the appropriate update chain:

Type	Steps
git repo	git pull → docker compose up -d --build
registry	docker compose down → docker compose pull → docker compose up -d

Pull failures are non-fatal — the service is restarted with its existing image and the run is marked ⚠ Failed to pull (restarted).
Stop failures abort the chain for that project.

Rich progress bars are shown when rich is installed; plain-text output is used as a fallback.

Logs are saved to /var/log/docker-update/docker-update-YYYY-MM-DD_HH-MM-SS.log with a companion .json sidecar used by the fzf browser.

At the end of every run the summary line is printed and a reminder to use docker-update log is shown.

docker-update log

Opens a two-level fzf menu:

1. Log file picker — lists past runs (newest first) with a preview of the log file on the right. Press Enter to open a run.

2. Project browser — shows every project from that run grouped by outcome, with live status dots (● running / ○ stopped). Hover over any project to see its live container logs in the preview pane. Press Enter to open the action menu.

3. Action menu — context-aware actions for the selected project:

   Action	Shown when
   ▶ Start	container is stopped
   ↺ Update	always
   ■ Stop	container is running

   After an action completes, press any key to return to the project browser (status dots refresh automatically).

Press Esc at any level to go back one level.

fzf and docker-update-fzf must both be in PATH. If either is missing, a plain-text fallback is used automatically after a warning.

docker-update debug

Discovers all projects and prints what would happen without making any changes. Optionally opens the fzf browser with a fake log (randomised outcomes) so you can test the interface. All Start / Update / Stop actions in debug mode print what they would run but do nothing.

---

Dependencies

Dependency	Notes
Python 3.8+	must be at /usr/bin/env python3
rich	optional — plain-text fallback if missing
fzf	optional — plain-text fallback if missing
Docker Compose v2 plugin	docker compose (not docker-compose)

Install optional dependencies on Ubuntu:

sudo apt install fzf
pip3 install rich

---

Installation

1 — Copy scripts to PATH

sudo cp docker-update     /usr/local/bin/docker-update
sudo cp docker-update-fzf /usr/local/bin/docker-update-fzf

2 — Make them executable

sudo chmod +x /usr/local/bin/docker-update
sudo chmod +x /usr/local/bin/docker-update-fzf

3 — Create the log directory

sudo mkdir -p /var/log/docker-update
sudo chmod 755 /var/log/docker-update

If you want a non-root user to run docker-update and write logs:

sudo chown YOUR_USER:YOUR_USER /var/log/docker-update

4 — Verify

docker-update debug

---

File layout after installation

/usr/local/bin/docker-update       ← Python main script
/usr/local/bin/docker-update-fzf   ← Bash fzf helper (called by docker-update)
/var/log/docker-update/            ← Log directory (created automatically)
  docker-update-YYYY-MM-DD_HH-MM-SS.log   ← human-readable run log
  docker-update-YYYY-MM-DD_HH-MM-SS.json  ← machine-readable sidecar (for fzf)

---

Uninstall

sudo rm /usr/local/bin/docker-update /usr/local/bin/docker-update-fzf
sudo rm -rf /var/log/docker-update   # optional — deletes all logs