Docker Operations

The local development stack is managed by docker-compose.local.yml, based on the cookiecutter-django Docker workflow.

Architecture

Service	Container Name	Image	Port
Django	`backend_local_django`	`backend_local_django`	8000
PostgreSQL	`backend_local_postgres`	`pgvector/pgvector:pg17`	5432
Redis	`backend_local_redis`	`redis:6`	6379
Celery Worker	`backend_local_celeryworker`	`backend_local_celeryworker`	—
Celery Beat	`backend_local_celerybeat`	`backend_local_celerybeat`	—
Flower	`backend_local_flower`	`backend_local_flower`	5555
Mailpit	`backend_local_mailpit`	`axllent/mailpit:latest`	8025

Django, celeryworker, celerybeat, and flower share the same Docker image.

Building

# Build all services
docker compose -f docker-compose.local.yml build

# Build only Django (also rebuilds celery/flower)
docker compose -f docker-compose.local.yml build django

# Force rebuild without cache
docker compose -f docker-compose.local.yml build --no-cache django

Build notes

Python 3.12 base image (Docling requires ≤3.12)
The build installs cmake and g++ for Docling native compilation
PostgreSQL uses pgvector/pgvector:pg17 for vector search
Requirements chain: local.txt → production.txt → base.txt

Running

# Start all services (detached)
docker compose -f docker-compose.local.yml up -d

# Start specific services
docker compose -f docker-compose.local.yml up -d django postgres redis celeryworker

# Stop all services
docker compose -f docker-compose.local.yml down

# Stop and remove volumes (DESTROYS DATABASE)
docker compose -f docker-compose.local.yml down -v

After editing .envs/ files, recreate containers for changes to take effect:

docker compose -f docker-compose.local.yml up -d --force-recreate

Management Commands

# Run any manage.py command
docker exec backend_local_django python manage.py <command>

# Migrate database
docker exec backend_local_django python manage.py migrate

# Create superuser
docker exec -it backend_local_django python manage.py createsuperuser

# Open Django shell
docker exec -it backend_local_django python manage.py shell

# Make migrations
docker exec backend_local_django python manage.py makemigrations

Logs & Monitoring

# Follow all logs
docker compose -f docker-compose.local.yml logs -f

# Follow specific service
docker compose -f docker-compose.local.yml logs -f celeryworker

# Last N lines
docker logs --tail 50 backend_local_celeryworker

# Logs from last 5 minutes
docker logs --since 5m backend_local_django 2>&1

Dashboards

Django Admin: http://localhost:8000/admin/
Flower (Celery monitoring): http://localhost:5555
Mailpit (email testing): http://localhost:8025
API Docs (Swagger): http://localhost:8000/api/docs/

Health Checks

# All containers running?
docker compose -f docker-compose.local.yml ps

# Test PostgreSQL
docker exec backend_local_django python manage.py shell -c "
from django.db import connection
connection.ensure_connection()
print('PostgreSQL connected')
"

# Test Redis
docker exec backend_local_celeryworker python -c "
import redis
r = redis.from_url('redis://redis:6379/0')
r.ping()
print('Redis connected')
"

# Check Celery registered tasks
docker exec backend_local_celeryworker celery -A config.celery_app inspect registered 2>/dev/null | head -20

Disk Space

The Django + Docling image is large (~7 GB). Monitor and clean regularly:

docker system df                    # Check disk usage
docker builder prune -f             # Remove build cache
docker image prune -f               # Remove dangling images

Troubleshooting

Symptom	Cause	Fix
`No space left on device`	Docker disk full	`docker builder prune -f`, restart containers
Env changes not taking effect	Containers not recreated	`docker compose up -d --force-recreate`
`MISCONF` Redis error	Can't write RDB snapshots	Free disk space, restart redis
Docling hangs on CPU	ML model loading slow	Expected — 120s timeout, falls back to PyMuPDF
Document stuck at `processing`	Task failed silently	Check celeryworker logs

On this page