Docker debugger

Skill OneWave-AI/claude-skills/docker-debugger

172 production-ready Claude Code skills for sales, marketing, design, engineering, and AI agent architecture. Built and maintained by OneWave AI.

Install

npx -y skills add OneWave-AI/claude-skills --skill docker-debugger

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

What its author says it does

Copied from the file, not written here

Debug Docker containers, fix Dockerfile issues, optimize images, and troubleshoot docker-compose. Use when having Docker problems, container issues, or optimizing Docker builds.

SKILL.md

3.1 KB, as published. Nobody here has run it

Docker Debugger

Instructions

When debugging Docker issues:

Identify the problem type: Build, runtime, networking, or performance
Gather information using diagnostic commands
Analyze logs and errors
Apply fixes

Diagnostic Commands

# Check running containers
docker ps -a

# View container logs
docker logs <container_id> --tail 100 -f

# Inspect container
docker inspect <container_id>

# Check resource usage
docker stats

# View container processes
docker top <container_id>

# Execute shell in running container
docker exec -it <container_id> /bin/sh

# Check Docker disk usage
docker system df

# View build history
docker history <image_name>

Common Issues & Solutions

1. Container exits immediately

# Check exit code
docker inspect <container_id> --format='{{.State.ExitCode}}'

# View last logs
docker logs <container_id>

Fixes:

Ensure CMD/ENTRYPOINT runs a foreground process
Check for missing dependencies
Verify environment variables

2. Build fails

# Use multi-stage builds for smaller images
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["node", "dist/index.js"]

3. Networking issues

# List networks
docker network ls

# Inspect network
docker network inspect <network_name>

# Check container IP
docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' <container>

4. Volume permission issues

# Create non-root user
RUN addgroup -g 1001 -S appgroup && \
    adduser -u 1001 -S appuser -G appgroup

# Set ownership
COPY --chown=appuser:appgroup . .

USER appuser

Dockerfile Best Practices

# 1. Use specific tags, not :latest
FROM node:20.10-alpine

# 2. Set working directory
WORKDIR /app

# 3. Copy dependency files first (better caching)
COPY package*.json ./
RUN npm ci --only=production

# 4. Copy source after dependencies
COPY . .

# 5. Use non-root user
USER node

# 6. Set proper labels
LABEL maintainer="[email protected]"
LABEL version="1.0"

# 7. Use HEALTHCHECK
HEALTHCHECK --interval=30s --timeout=3s \
  CMD wget -q --spider http://localhost:3000/health || exit 1

# 8. Expose ports
EXPOSE 3000

# 9. Use exec form for CMD
CMD ["node", "server.js"]

docker-compose Debugging

# docker-compose.yml
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    # Add for debugging
    stdin_open: true
    tty: true
    # Override command for debugging
    command: /bin/sh
    volumes:
      - .:/app
    environment:
      - DEBUG=true

# Rebuild without cache
docker-compose build --no-cache

# View logs
docker-compose logs -f app

# Restart single service
docker-compose restart app