docker-troubleshoot

# Docker Troubleshooting Skill

## Overview

This skill helps diagnose and resolve common Docker issues:
- Container startup failures
- Networking problems
- Permission errors
- Port conflicts
- Data persistence issues
- Health check failures

## Process

### 1. Consult Documentation

Read relevant documentation:
- `17-troubleshooting.md` for common issues
- `15-port-conflicts.md` for port problems
- `16-restart-strategies.md` for restart issues

### 2. Diagnose Issue

Gather information:
```bash
# Check container status
docker compose ps -a

# View logs
docker compose logs servicename

# Check configuration
docker compose config

# Inspect container
docker inspect containername
```

### 3. Apply Solution

## Common Issues and Solutions

### Container Won't Start

**Diagnosis:**
```bash
docker compose logs servicename
docker inspect --format='{{.State.ExitCode}}' containername
```

**Solutions:**
- Check logs for error messages
- Verify configuration syntax
- Check dependencies are running
- Verify image exists

### Port Already in Use

**Diagnosis:**
```bash
lsof -i :3000
# or
netstat -tulpn | grep 3000
```

**Solutions:**
```bash
# Kill process
kill $(lsof -t -i:3000)

# Or change port in compose
ports:
  - "3001:3000"
```

### Permission Denied

**Diagnosis:**
```bash
docker compose exec app ls -la /app/data
```

**Solutions:**
```yaml
# Fix in compose
services:
  app:
    user: "1000:1000"

# Or fix in container
docker compose exec -u root app chown -R appuser:appgroup /app/data
```

### Data Disappearing

**Diagnosis:**
```bash
docker volume ls
docker compose config | grep -A5 "volumes:"
```

**Solutions:**
```yaml
# Use named volumes instead of anonymous
volumes:
  - postgres_data:/var/lib/postgresql/data  # Named (persists)
  # NOT: - /var/lib/postgresql/data  # Anonymous (deleted)
```

### Container Can't Reach Other Container

**Diagnosis:**
```bash
docker network inspect networkname
docker compose exec app ping db
docker compose exec app nslookup db
```

*