🐳 Docker Setup Overview

Quick Navigation

Choose your Docker journey:

🚀 Get Started Fast

• Development Setup - Local development with Docker Compose
• Production Deployment - Production-grade Docker setup
• Configuration Strategy - YAML + env vars configuration

🔧 Advanced Topics

• Build Optimization - Critical lessons for multi-stage builds
• Troubleshooting - Common issues and quick fixes

Overview

Django-CFG’s Docker setup provides a complete containerized environment:

Architecture Components

Infrastructure Layer

• Traefik - Reverse proxy with automatic routing
• PostgreSQL + pgvector - Database with vector extension for AI/embeddings
• Redis - Caching and task queue management

Backend Services

• Django API - Main application server (port 8300)
• Django ReArq - Background task workers
• WebSocket RPC - Real-time communication (port 9065)

Frontend Services

• Demo App - Next.js demo application (port 3300)
• Documentation - Nuxt.js documentation site (port 3301)

Quick Start

Prerequisites

1. Start All Services

cd docker
docker compose up -d

2. Check Status

docker compose ps

All services should show healthy status:

NAME               STATUS              PORTS
djangocfg_traefik  Up (healthy)        380/tcp, 743/tcp, 8390/tcp
djangocfg_postgres Up (healthy)        5432/tcp
djangocfg_redis    Up (healthy)        6379/tcp
django             Up (healthy)        8300/tcp
django-rearq       Up (healthy)        -
websocket          Up (healthy)        9065/tcp, 9066/tcp
frontend-demo      Up (healthy)        3300/tcp
frontend-web       Up (healthy)        3301/tcp

3. Access Services

docker exec -it django python manage.py createsuperuser

Configuration Approaches

Django-CFG uses a modern hybrid configuration system combining YAML structure with environment variable overrides:

Universal __ Notation (Recommended)

Best for: All environments - no rebuilds needed for credential changes

# docker/.env.secrets (git-ignored!)
EMAIL__HOST=mail.example.com
EMAIL__PORT=465
EMAIL__PASSWORD=your-password-here
 
# Nested sections
API_KEYS__OPENAI=sk-proj-your-key-here
API_KEYS__CLOUDFLARE=your-cloudflare-key
 
TELEGRAM__BOT_TOKEN=123456789:ABC...
TELEGRAM__CHAT_ID=-123456

Benefits:

• ✅ No secrets in git
• ✅ Just restart (no rebuild) to apply changes
• ✅ Works with any config value
• ✅ Automatic type conversion

Configuration Priority

Settings load in this order (highest priority first):

1. Environment variables - SECTION__FIELD notation (e.g., EMAIL__HOST)
2. .env.secrets file - Sensitive credentials (git-ignored)
3. config.*.docker.yaml - Docker-specific configs (git-ignored)
4. config.*.yaml - Base templates (in git)
5. Built-in defaults - Pydantic model defaults

Learn Complete Configuration Strategy →

Quick Example: Add New API Key

# Add to .env.secrets
echo "API_KEYS__NEW_SERVICE=your-key-here" >> docker/.env.secrets
 
# Restart (no rebuild!)
docker compose restart django

# Old way (slow): Rebuild entire image
docker compose build django --no-cache  # ❌ 5+ minutes
 
# New way (fast): Just restart
docker compose restart django  # ✅ 10 seconds

Docker Compose Structure

docker/
├── docker-compose.yaml              # Main compose file
├── .env                            # Base environment variables (in git)
├── .env.secrets                    # Sensitive credentials (git-ignored!)
├── .dockerignore                   # Build exclusions (includes poetry.lock)
├── services/
│   ├── django/
│   │   ├── Dockerfile              # Django app image
│   │   └── entrypoint.sh          # Container startup script
│   ├── demo/Dockerfile            # Next.js demo
│   ├── websocket/Dockerfile       # WebSocket RPC
│   ├── web/Dockerfile             # Documentation site
│   └── postgres/init.sql          # Database initialization
├── volumes/                        # Persistent data (git-ignored)
│   ├── postgres/                  # Database files
│   ├── django/
│   │   ├── media/                # User uploads
│   │   └── logs/                 # Application logs
│   └── .gitkeep
└── @docs/                          # Docker documentation
    ├── README.md                   # Complete guide
    ├── CONFIG_STRATEGY.md         # Universal __ notation + YAML
    ├── NETWORK_TRAEFIK.md         # Networking & routing
    ├── CHANGELOG.md               # Recent changes & migration
    ├── DOCKER_BUILD_LESSONS.md    # Build optimization
    └── QUICK_REFERENCE.md         # Common commands

projects/django/api/environment/
├── config.dev.yaml                 # Development template (in git)
├── config.dev.docker.yaml          # Docker dev config (git-ignored!)
├── config.prod.yaml                # Production template (in git)
└── config.prod.docker.yaml         # Docker prod config (git-ignored!)

Explore Development Setup →

Development Workflow

Common Tasks

# View logs
docker compose logs -f django
 
# Run migrations
docker exec django python manage.py migrate
 
# Create superuser
docker exec -it django python manage.py createsuperuser
 
# Django shell
docker exec -it django python manage.py shell
 
# Restart service
docker compose restart django
 
# Rebuild after changes
docker compose up -d --build django

See all commands in Quick Reference →

Database Operations

# Access PostgreSQL
docker exec -it djangocfg_postgres psql -U postgres -d djangocfg
 
# Backup database
docker exec djangocfg_postgres pg_dump -U postgres djangocfg > backup.sql
 
# Restore database
docker exec -i djangocfg_postgres psql -U postgres djangocfg < backup.sql

Production Deployment

For production-ready deployment with SSL/TLS, health monitoring, and scaling:

Complete Production Setup Guide →

Key features:

• ✅ Multi-stage builds for minimal image sizes
• ✅ Health checks for all services
• ✅ Automated database initialization
• ✅ Environment-based configuration
• ✅ Logging and monitoring
• ✅ Horizontal scaling support

Performance Optimization

Build Performance

Django-CFG Docker setup uses advanced techniques to minimize build times:

• .dockerignore - Excludes node_modules, .next, build artifacts
• Multi-stage builds - Separate dependency installation from runtime
• Layer caching - Optimized layer ordering for maximum cache hits
• Turborepo pruning - Only builds required packages in monorepo

Before optimization: 2.13GB context, 380s transfer time ❌ After optimization: 280KB context, 4s transfer time ✅

Learn Build Optimization Techniques →

Runtime Performance

• Connection pooling - PostgreSQL connection reuse
• Redis caching - Multi-tier caching strategy
• ReArq workers - Configurable processes and threads
• Nginx/Traefik - Reverse proxy with load balancing

Troubleshooting

Quick Fixes

Services won’t start?

docker compose logs service-name
docker compose ps

Port conflicts?

# Find process using port
lsof -i :8300
# Kill process
kill -9 <PID>

Configuration not loading?

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

Database connection issues?

docker exec djangocfg_postgres pg_isready -U postgres

Complete Troubleshooting Guide →

Learning Paths

🎓 Beginner Path

1. Docker Development Setup - Start here
2. Configuration Basics
3. First Django-CFG Project

🚀 Production Path

1. Production Docker Setup
2. Security Configuration
3. Monitoring Setup

🔧 Advanced Path

1. Build Optimization
2. Multi-Database Setup
3. Scaling Strategies

See Also

Docker Guides

• Development Setup - Local Docker environment
• Production Setup - Production deployment
• Configuration - YAML + env vars strategy
• Build Optimization - Critical Docker lessons
• Troubleshooting - Common issues solved

Deployment

• Deployment Overview - All deployment options
• Environment Setup - Environment variables
• Logging Configuration - Structured logging
• Security Settings - Production security

Configuration

• Database Configuration - PostgreSQL setup
• Cache Configuration - Redis caching
• Environment Detection - Multi-environment

Integrations

• ReArq Integration - Background tasks
• Background Task Commands - Manage workers via CLI
• Centrifugo WebSocket RPC - Real-time communication

Next Steps

Ready to get started? Choose your path:

Start Development → Set up local Docker environment

Deploy to Production → Production-ready Docker setup

Learn Configuration → Master YAML + env var strategy

TAGS: docker, deployment, docker-compose, containerization, production, development DEPENDS_ON: [docker, docker-compose, postgresql, redis] USED_BY: [deployment, production, development, ci-cd] %%PRIORITY:HIGH%%