# 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:

```bash
sudo apt install fzf
pip3 install rich
```

---

## Installation

### 1 — Copy scripts to PATH

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

### 2 — Make them executable

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

### 3 — Create the log directory

```bash
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:

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

### 4 — Verify

```bash
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

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