onewave-ai 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="you@example.com"
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