---
name: choutos/debug-docker-service
source: https://app.decimal.ai/s/choutos-debug-docker-service@1/SKILL.md
source_sha256: deddbbbfb572
---

# Debug Docker Service

## Diagnosis Flow

1. **Check container status:**
   ```bash
   docker compose ps
   ```

2. **If container is restarting:**
   ```bash
   docker compose logs --tail=50 <service>
   ```
   Common causes: missing env vars, port conflicts, OOM kills.

3. **If container is stopped:**
   ```bash
   docker compose up -d <service>
   docker compose logs -f <service>  # watch startup
   ```

4. **If container is running but service unresponsive:**
   ```bash
   docker compose exec <service> sh  # get a shell
   # Check if process is running inside
   # Check if port is listening
   netstat -tlnp || ss -tlnp
   ```

5. **Resource issues:**
   ```bash
   docker stats --no-stream
   df -h  # disk full?
   ```

## Common Fixes

| Symptom | Fix |
|---------|-----|
| OOM killed | Increase memory limit in compose file |
| Port conflict | Check `docker compose ps` for port bindings, stop conflicting service |
| Volume mount error | Verify host path exists: `ls -la <path>` |
| Image not found | `docker compose pull <service>` |
| Config changed | `docker compose up -d --force-recreate <service>` |

## After Fixing

Always verify the service is healthy:
```bash
docker compose ps  # status should be "Up"
curl -s http://localhost:<port>/health  # if applicable
```