agent-estate-wiki/runbooks/diagnose-docker.md

title, type, status, created, updated, verified_on, last_tested, confidence, tags, sources

title	type	status	created	updated	verified_on	last_tested	confidence	tags	sources
Diagnose Failed Docker Service	runbook	active	2026-07-22	2026-07-22	2026-07-22	2026-07-22	medium	runbook docker homelab

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

Procedure

1. Check Docker daemon state

systemctl status docker

2. List containers

docker ps -a --format "table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}"

3. Inspect logs for the failing container

docker logs --tail 100 <container-name>

4. If using compose, check compose state

cd /home/hermes/<project>/docker-compose
docker compose ps
docker compose logs --tail 100 <service-name>

5. Restart the failed container only

docker restart <container-name>

6. If restart fails, investigate restart policy and image

docker inspect --format "{{.HostConfig.RestartPolicy}}" <container-name>
docker inspect --format "{{.Config.Image}}" <container-name>

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