Docker Stack Ops

---
name: docker-stack-ops
description: >
  Troubleshoot and manage the Docker / Dockge stacks over SSH, especially the
  arr media stack. Use this whenever the user mentions a container, Docker, Dockge, a
  compose stack, or any specific app such as Jellyfin, qBittorrent, gluetun,
  Radarr, Sonarr, Prowlarr, Seerr, Immich, Seafile, SearXNG, or similar, and
  whenever the symptom is app-level: a container is down, restarting, unhealthy,
  downloads are stalled, requests are not processing, or a service is
  unreachable while its host is fine. Trigger this even if he just names an app
  and says it is broken.
---

# Docker stack ops

Reached over SSH to the docker host(s). Read `infra/docker-stacks.md` for host
aliases, the compose layout, and stack membership before acting. Docker needs
root: if the host connects as a non-root user (e.g. TrueNAS `truenas_admin`),
prefix `docker` / `docker compose` with `sudo -n` (works when that user has
passwordless sudo; see CLAUDE.md). Root hosts run it bare.

Where compose files live depends on the setup and is recorded in
`infra/docker-stacks.md`: it may be a single `/mnt/<pool>/docker/docker-compose.yml`
(the TrueNAS layout), per-stack `/opt/stacks/<stack>/compose.yaml` (Dockge), or
stacks defined in Portainer. This skill is for troubleshooting/operating existing
stacks; to stand up a NEW app or stack, use the deploy-app skill.

## Diagnose first

    hh run <dockerhost> "docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'"
    hh run <dockerhost> "docker ps -a --filter status=exited --format '{{.Names}}\t{{.Status}}'"
    hh run <dockerhost> "docker logs --tail 120 <container>"
    hh run <dockerhost> "docker inspect -f '{{.State.Health.Status}}' <container>"

## The gluetun rule (most common arr failure)

If downloads are dead but the rest of the stack is fine, suspect the VPN sidecar
before touching qBittorrent.

    hh run <dockerhost> "docker logs --tail 60 gluetun"
    hh run <dockerhost> "docker exec gluetun wget -qO- https://ipinfo.io/ip"

If that IP is the home IP or the call fails, the tunnel is down. Fix order:
restart gluetun, wait for healthy, confirm the egress IP is the VPN's, then
restart qBittorrent. Never let qBittorrent run with a leaked (home) IP.

## Common cases

- Container restart loop: read the tail of its logs for the fatal line; check a
  bad config volume, a missing dependency container, or a port clash.
- App reachable internally but not externally: this is usually network-diag
  territory (Cloudflare Tunnel or reverse proxy), not the container.
- Everything in a stack down after boot: order sensitivity. Bring up
  dependencies first (VPN, db), then the rest.

## State-changing (confirm first)

    # from the compose dir: Dockge => /opt/stacks/<stack>, single-file => /mnt/<pool>/docker
    hh run <dockerhost> "cd <composedir> && docker compose restart <service>"
    hh run <dockerhost> "cd <composedir> && docker compose up -d"
    hh run <dockerhost> "cd <composedir> && docker compose pull && docker compose up -d"

Do not `docker compose down -v` or prune volumes without an explicit go-ahead;
the `-v` and prune paths delete app data. Image pruning is fine, volume pruning
is not.