---
title: Diagnose Failed Docker Service
type: runbook
status: active
created: 2026-07-22
updated: 2026-07-22
verified_on: 2026-07-22
last_tested: 2026-07-22
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

## 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 <container-name>
```

### 4. If using compose, check compose state
```bash
cd /home/hermes/<project>/docker-compose
docker compose ps
docker compose logs --tail 100 <service-name>
```

### 5. Restart the failed container only
```bash
docker restart <container-name>
```

### 6. If restart fails, investigate restart policy and image
```bash
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]]