85 lines
2.1 KiB
Markdown
85 lines
2.1 KiB
Markdown
---
|
|
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]]
|