--- title: Diagnose Failed Docker Service type: runbook status: active created: 2026-07-22 updated: 2026-10-20 verified_on: 2026-10-20 last_tested: 2026-10-20 confidence: medium tags: [runbook, docker, homelab] sources: [] --- # Diagnose Failed Docker Service ## Purpose Diagnose container or compose issues on hosts where Docker is present. ## Symptoms that match this runbook - Service reports container exit/failed state - `docker ps` does not show an expected container - Compose stack reports unhealthy status ## Prerequisites - `docker` installed and accessible to the user - Docker daemon running - Compose file path known for the affected project > **Important scoping note, verified 2026-10-20: the `hermes` user is NOT in the `docker` group on > CT460.** `systemctl is-active docker` → `active`, but `docker ps` as `hermes` returns > **`permission denied while trying to connect to the docker API at unix:///var/run/docker.sock`**. > Most Docker services in this estate run on **other hosts** (runtipi CT201, cloudreve CT209, > LiteLLM CT500 on m93p, etc.) where the invoking account does have socket access. > So: on CT460, either use `sudo docker …` or SSH to the host that actually owns the container. > Note also that `systems/homepage-dashboard.md` now records the CT201 stack as **degraded** — > the main dashboard container is gone — which is exactly the symptom this runbook would be used for. ## Procedure ### 1. Check Docker daemon state ```bash systemctl status docker ``` ### 2. List containers ```bash docker ps -a --format "table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}" ``` ### 3. Inspect logs for the failing container ```bash docker logs --tail 100 ``` ### 4. If using compose, check compose state ```bash cd /home/hermes//docker-compose docker compose ps docker compose logs --tail 100 ``` ### 5. Restart the failed container only ```bash docker restart ``` ### 6. If restart fails, investigate restart policy and image ```bash docker inspect --format "{{.HostConfig.RestartPolicy}}" docker inspect --format "{{.Config.Image}}" ``` ## Verification - `docker ps` shows the container `Up` or `healthy` - Service or WebUI dependent on the container is reachable again - Logs show clean startup messages ## Rollback - Do not delete volumes unless confirmed not in use - If a container recreate is required, preserve volume mappings and env files - If uncertain, collect logs first and ask before replacement ## Notes - This runbook is generic. This current Hermes host does not have Docker installed as of 2026-07-22 - Docker-related paths must be confirmed before executing compose commands - Do not invent container names or project paths ## Last tested 2026-07-22 on system where Docker runtime is absent; read-only steps verified, restart steps not executed ## Related - [[docker-services]] - [[hosts]]