GitHubEmailContact
Skip to main content

Docker Troubleshooting

📚 Part of: Docker Guide - Return to Docker overview

Quick solutions for common Docker issues with Django-CFG.

Quick Fixes​

❌ "Package not found" with turbo prune​

Problem: turbo prune demo --docker fails

Solution: Use FULL package name from package.json

# Check actual package name
grep '"name"' apps/demo/package.json

# Use full scoped name
RUN npx turbo@^2 prune @djangocfg/demo --docker  # ✅
RUN npx turbo@^2 prune demo --docker             # ❌

❌ 2GB+ context transfer​

Problem: Docker build taking 10+ minutes to transfer context

Solution: Create or update .dockerignore

**/node_modules/
**/.next/
**/dist/
**/.turbo/
**/build/
*.log
.git

Verify:

docker build . 2>&1 | grep "transferring context"
# Should be <1MB, not 2GB

❌ "ERR_PNPM_NO_GLOBAL_BIN_DIR"​

Problem: pnpm install -g failing in Alpine

Solution: Use npx instead of global install

# ❌ Don't use global install
RUN pnpm install -g turbo@^2

# ✅ Use npx instead
RUN npx turbo@^2 prune ...

❌ Next.js "server.js not found"​

Problem: Cannot find module '/app/server.js'

Solution: Next.js standalone places server.js in root

# Correct standalone output structure
COPY --from=builder /app/apps/demo/.next/standalone ./
CMD node server.js  # Root level, not apps/demo/server.js

❌ Poetry local path dependencies​

Problem: poetry install failing with path dependencies

Solution: Remove local groups before lock

RUN python3 -c "import re; \
    content = open('pyproject.toml').read(); \
    content = re.sub(r'\[tool\.poetry\.group\.local[^\]]*\][^\[]*', '', content, flags=re.DOTALL); \
    open('pyproject.toml', 'w').write(content)" \
    && poetry lock

❌ Docker image 4.84GB (should be ~300MB)​

Problem: Next.js image too large

Solution: Copy ONLY standalone output, not entire /app

# ❌ WRONG - copies everything
COPY --chown=nextjs:nodejs /app .

# ✅ CORRECT - copy only standalone
COPY --from=installer --chown=nextjs:nodejs /app/apps/demo/.next/standalone ./
COPY --from=installer --chown=nextjs:nodejs /app/apps/demo/.next/static ./apps/demo/.next/static
COPY --from=installer --chown=nextjs:nodejs /app/apps/demo/public ./apps/demo/public

Verify:

docker images | grep djangocfg-demo
# Should be ~300MB, not 4.84GB

Build Issues​

Build Failing - Check Context Size​

# Check what's being copied
docker build --no-cache . 2>&1 | grep "transferring context"

# If large (>10MB), update .dockerignore
echo "**/node_modules/" >> .dockerignore
echo "**/.next/" >> .dockerignore

Build Cache Issues​

# Full rebuild without cache
docker compose build --no-cache

# Remove all build cache
docker builder prune -af

Out of Disk Space​

# Check disk usage
docker system df

# Clean up
docker system prune -af --volumes

Service Issues​

Services Won't Start​

Check status:

docker compose ps
docker compose logs service-name

Common causes:

  • Port already in use
  • Configuration error
  • Health check failing
  • Dependency not ready

Service Keeps Restarting​

Check logs:

docker compose logs -f --tail=100 service-name

Common issues:

  • Failed health check
  • Incorrect CMD
  • Missing environment variable
  • Database not ready

Health Check Failing​

Check health status:

docker inspect container-name | grep -A 10 Health

Test health endpoint manually:

docker exec container-name curl -f http://localhost:8000/cfg/health/

Configuration Issues​

Configuration Not Loading​

Check which config is loaded:

docker exec django python -c "from api.environment.loader import env; print(env)"

Verify file exists:

docker exec django ls -la /app/api/environment/

Check environment mode:

docker exec django python -c "from api.environment.loader import env; print(env.env.env_mode)"

Environment Variables Not Applied​

Check variable is set:

docker exec django env | grep DATABASE_URL

Verify docker-compose.yaml:

environment:
  DATABASE_URL: postgresql://...  # Make sure it's here

Or check .env file:

cat docker/.env | grep DATABASE_URL

Database Issues​

Cannot Connect to Database​

Check PostgreSQL is running:

docker compose ps djangocfg_postgres
docker exec djangocfg_postgres pg_isready -U postgres

Test connection from Django:

docker exec django python manage.py check --database default

Check DATABASE_URL:

docker exec django env | grep DATABASE_URL

Database Extension Missing​

Problem: type "vector" does not exist

Solution: Check init script is mounted

postgres:
  volumes:
    - ./services/postgres/init.sql:/docker-entrypoint-initdb.d/init.sql:ro

Verify extensions:

docker exec djangocfg_postgres psql -U postgres -d djangocfg -c "\dx"

Network Issues​

Port Already in Use​

Find process using port:

lsof -i :8300

Kill process:

kill -9 <PID>

Or change port in docker-compose.yaml:

ports:
  - "8301:8000"  # Changed from 8300

Service Can't Reach Other Service​

Check networks:

docker network ls
docker network inspect dockerdjangonetwork

Verify service is in same network:

networks:
  - djangocfg-network  # Must be same

Test connection:

docker exec django ping postgres

Performance Issues​

Slow Build Times​

  1. Use .dockerignore - Exclude unnecessary files
  2. Enable BuildKit - export DOCKER_BUILDKIT=1
  3. Layer caching - Don't change Dockerfile often
  4. Multi-stage builds - Separate build/runtime stages

See Build Optimization Guide

Container Using Too Much Memory​

Check resource usage:

docker stats

Limit resources in docker-compose.yaml:

deploy:
  resources:
    limits:
      cpus: '2.0'
      memory: 4G
    reservations:
      memory: 512M

Essential Commands​

Service Management​

# Start all services
docker compose up -d

# Stop all services
docker compose stop

# Restart single service
docker compose restart django

# Remove all (keeps volumes)
docker compose down

# Remove all including volumes (⚠️ DELETES DATA)
docker compose down -v

View Logs​

# All services
docker compose logs -f

# Specific service
docker compose logs -f django

# Last 50 lines
docker compose logs --tail=50 django

# With timestamps
docker compose logs -f --timestamps

Execute Commands​

# Django management
docker exec django python manage.py migrate
docker exec -it django python manage.py shell

# Database access
docker exec -it djangocfg_postgres psql -U postgres -d djangocfg

# Shell into container
docker exec -it django bash

Check Status​

# Service status
docker compose ps

# Container details
docker inspect django

# Resource usage
docker stats

# Disk usage
docker system df

Clean Up Commands​

Remove Containers​

# Stop and remove all
docker compose down

# Remove specific service
docker compose rm -f django

Remove Images​

# Remove specific image
docker rmi djangocfg-django:latest

# Remove all project images
docker compose down --rmi all

# Remove unused images
docker image prune -a

Remove Volumes​

# Remove all volumes (⚠️ DELETES DATA)
docker compose down -v

# Remove specific volume
docker volume rm docker_postgres_data

# Remove unused volumes
docker volume prune

Complete Clean​

# Nuclear option - removes everything
docker system prune -af --volumes
Destructive Commands

Commands with -v or --volumes flags will permanently delete data:

  • Database files
  • Uploaded media
  • Application logs

Always backup before running!

# Backup database first
docker exec djangocfg_postgres pg_dump -U postgres djangocfg > backup.sql

Port Reference​

ServiceInternalExternalAccess
Django80008300http://localhost:8300
Demo30003300http://localhost:3300
Web30003301http://localhost:3301
WebSocket90659065ws://localhost:9065
Traefik80380http://localhost:380
Traefik HTTPS443743https://localhost:743
Traefik Dashboard80808390http://localhost:8390

Troubleshooting Checklist​

Build Failures​

  • Check .dockerignore exists
  • Verify package names in turbo prune
  • Use npx instead of global install
  • Check build context size
  • Try build with --no-cache

Service Won't Start​

  • Check logs: docker compose logs service
  • Verify ports not in use: lsof -i :port
  • Check environment variables set
  • Verify dependencies healthy
  • Test health endpoint

Configuration Issues​

  • Check config file exists in container
  • Verify environment mode (dev/prod)
  • Test config loading in shell
  • Check .env file values
  • Verify docker-compose environment

Database Problems​

  • PostgreSQL service healthy
  • DATABASE_URL correct
  • Extensions installed
  • Migrations run
  • Connection from Django works

Performance Issues​

  • Check .dockerignore configured
  • Verify multi-stage builds used
  • Monitor with docker stats
  • Check resource limits set
  • Review build cache strategy

Next Steps​

Build optimization: Build Optimization Guide →

Configuration deep dive: Configuration Strategy →

Production deployment: Production Setup →

See Also​

Docker Guides​

External Resources​

TAGS: docker, troubleshooting, debugging, quick-fixes DEPENDS_ON: [docker, docker-compose] USED_BY: [development, production, debugging]

Last updated on