Docker Compose برای Django، PostgreSQL و Redis با healthcheck


چرا Docker Compose برای توسعهٔ Django؟ #

یک پروژهٔ Django واقعی تقریباً هیچ‌وقت فقط Django نیست. معمولاً به PostgreSQL برای دیتابیس، Redis برای cache و صف پیام، یک worker مثل Celery برای کارهای پس‌زمینه و شاید Nginx نیاز دارید. نصب و نگهداری همهٔ این‌ها روی سیستم هر توسعه‌دهنده یعنی جملهٔ معروف «روی سیستم من کار می‌کنه».

Docker Compose اجازه می‌دهد کل این مجموعه را در یک فایل YAML تعریف کنید و با یک دستور بالا بیاورید. در این راهنما یک محیط کامل Django + PostgreSQL + Redis + Celery می‌سازیم و روی نکته‌ای تمرکز می‌کنیم که بیشتر آموزش‌ها نادیده می‌گیرند: ترتیب درست راه‌اندازی سرویس‌ها با healthcheck.

سرویس‌های web، db، redis و worker که در یک شبکهٔ Compose به هم متصل‌اند

ساختار پروژه #

myproject/
├── compose.yaml
├── Dockerfile
├── .env
├── pyproject.toml
├── uv.lock
├── manage.py
└── config/
    ├── settings.py
    ├── celery.py
    └── ...

یادداشت

نام پیش‌فرض و توصیه‌شدهٔ فایل در نسخه‌های جدید Compose، compose.yaml است. فایل docker-compose.yml هنوز پشتیبانی می‌شود، و کلید version: در ابتدای فایل دیگر لازم نیست.

Dockerfile #

از یک Dockerfile مبتنی بر uv استفاده می‌کنیم. اگر می‌خواهید نسخهٔ production با multi-stage و ایمیج کوچک بسازید، مطلب Docker چندمرحله‌ای برای پایتون با uv را ببینید. برای توسعه یک نسخهٔ ساده‌تر کافی است:

Dockerfiledockerfile
FROM python:3.14-slim

COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

ENV PYTHONUNBUFFERED=1 \
    UV_COMPILE_BYTECODE=1 \
    UV_LINK_MODE=copy

WORKDIR /app

COPY pyproject.toml uv.lock ./
RUN uv sync --locked --no-install-project

COPY . .
RUN uv sync --locked

ENV PATH="/app/.venv/bin:$PATH"

CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]

کپی کردن pyproject.toml و uv.lock قبل از بقیهٔ کد باعث می‌شود لایهٔ نصب وابستگی‌ها cache شود و با هر تغییر کد دوباره ساخته نشود؛ روشی که راهنمای رسمی uv برای Docker هم توصیه می‌کند.

فایل محیطی #

.envbash
POSTGRES_DB=myproject
POSTGRES_USER=myproject
POSTGRES_PASSWORD=change-me-in-production
DJANGO_SECRET_KEY=dev-only-insecure-key
DJANGO_DEBUG=1
DATABASE_URL=postgres://myproject:change-me-in-production@db:5432/myproject
REDIS_URL=redis://redis:6379/0

هشدار

فایل .env را به .gitignore اضافه کنید و هرگز رمزهای واقعی production را commit نکنید. یک فایل .env.example بدون مقادیر حساس در مخزن نگه دارید.

فایل compose.yaml کامل #

compose.yamlyaml
services:
  db:
    image: postgres:18
    env_file: .env
    volumes:
      - pgdata:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 10
      start_period: 10s

  redis:
    image: redis:8-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 10

  migrate:
    build: .
    env_file: .env
    command: python manage.py migrate --noinput
    depends_on:
      db:
        condition: service_healthy

  web:
    build: .
    env_file: .env
    ports:
      - "8000:8000"
    volumes:
      - .:/app
      - /app/.venv
    depends_on:
      db:
        condition: service_healthy
        restart: true
      redis:
        condition: service_healthy
      migrate:
        condition: service_completed_successfully

  worker:
    build: .
    env_file: .env
    command: celery -A config worker -l info
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
      migrate:
        condition: service_completed_successfully

volumes:
  pgdata:

بیایید بخش‌های مهم را بررسی کنیم.

depends_on و healthcheck: قلب ماجرا #

سرویس‌ها فقط بعد از سالم شدن دیتابیس اجرا می‌شوند

مشکل کلاسیک: Django بالا می‌آید، به دیتابیس وصل می‌شود و خطای connection refused می‌گیرد؛ چون کانتینر PostgreSQL روشن شده اما هنوز آمادهٔ پذیرش اتصال نیست. depends_on ساده فقط تضمین می‌کند کانتینر شروع شده، نه اینکه سرویس آماده است.

طبق مستندات Docker دربارهٔ ترتیب راه‌اندازی، depends_on سه شرط دارد:

شرط معنی
service_started کانتینر شروع شده باشد (رفتار پیش‌فرض)
service_healthy healthcheck سرویس وابسته «سالم» گزارش داده باشد
service_completed_successfully سرویس وابسته اجرا شده و با کد صفر خارج شده باشد

در فایل بالا:

  • db با pg_isready سلامتش را اعلام می‌کند. دقت کنید $$ لازم است تا متغیر توسط شل داخل کانتینر تفسیر شود، نه توسط خود Compose.
  • migrate یک سرویس یک‌باره است که فقط مایگریشن را اجرا می‌کند و خارج می‌شود.
  • web و worker فقط وقتی شروع می‌شوند که دیتابیس سالم، Redis سالم و مایگریشن با موفقیت تمام شده باشد.
  • restart: true روی وابستگی db یعنی اگر سرویس دیتابیس به‌صراحت با عملیات Compose ری‌استارت یا به‌روزرسانی شود، web هم ری‌استارت می‌شود.

نکته

جدا کردن مایگریشن در یک سرویس مستقل از اجرای هم‌زمان migrate توسط چند کانتینر (مثلاً web و worker) جلوگیری می‌کند و منطق startup را ساده نگه می‌دارد.

تنظیمات Django #

config/settings.pypython
import os
import dj_database_url

SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]
DEBUG = os.environ.get("DJANGO_DEBUG") == "1"
ALLOWED_HOSTS = ["localhost", "127.0.0.1"]

DATABASES = {
    "default": dj_database_url.parse(
        os.environ["DATABASE_URL"],
        conn_max_age=60,
        conn_health_checks=True,
    )
}

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": os.environ["REDIS_URL"],
    }
}

CELERY_BROKER_URL = os.environ["REDIS_URL"]

نکتهٔ مهم: داخل شبکهٔ Compose، هر سرویس با نام خودش قابل دسترسی است. به همین دلیل host دیتابیس db و host ردیس redis است، نه localhost.

دستورات روزمره #

bash
# ساخت و اجرای همه‌چیز
docker compose up --build

# اجرا در پس‌زمینه
docker compose up -d

# دیدن وضعیت و سلامت سرویس‌ها
docker compose ps

# لاگ‌های یک سرویس
docker compose logs -f web

# اجرای دستور manage.py
docker compose exec web python manage.py createsuperuser
docker compose exec web python manage.py shell

# ورود به psql
docker compose exec db psql -U myproject

# خاموش کردن (داده‌ها حفظ می‌شوند)
docker compose down

# خاموش کردن و پاک کردن volumeها (همهٔ داده‌ها پاک می‌شوند)
docker compose down -v

Hot reload با Compose Watch #

mount کردن کل پوشهٔ پروژه با volumes کار می‌کند، اما Compose قابلیت مدرن‌تری به نام watch هم دارد:

compose.yaml (بخش web)yaml
  web:
    build: .
    develop:
      watch:
        - action: sync
          path: .
          target: /app
          ignore:
            - .venv/
        - action: rebuild
          path: uv.lock

با docker compose watch، تغییرات کد به کانتینر sync می‌شوند و runserver خودکار reload می‌شود، و تغییر در uv.lock باعث بازسازی ایمیج می‌شود.

اشتباهات رایج #

  • استفاده از localhost برای اتصال به دیتابیس داخل کانتینر. داخل کانتینر، localhost خود همان کانتینر است.
  • نداشتن volume برای دیتابیس: با هر down همهٔ داده‌ها پاک می‌شوند.
  • mount کردن .venv میزبان روی کانتینر: پکیج‌های کامپایل‌شده برای سیستم‌عامل دیگر خراب می‌شوند. به همین دلیل در مثال بالا /app/.venv را جدا کردیم.
  • اجرای runserver در production: برای production از gunicorn یا uvicorn پشت یک reverse proxy استفاده کنید.
  • باز کردن پورت دیتابیس به بیرون بدون نیاز. اگر فقط web به db وصل می‌شود، بخش ports را برای db تعریف نکنید.

چک‌لیست #

  • compose.yaml بدون کلید version:
  • healthcheck برای db و redis
  • depends_on با condition: service_healthy
  • مایگریشن در سرویس جداگانه
  • volume نام‌دار برای دادهٔ PostgreSQL
  • فایل .env در .gitignore
  • استفاده از نام سرویس به‌جای localhost
چرا از wait-for-it.sh استفاده نکنیم؟

اسکریپت‌هایی مثل wait-for-it فقط باز بودن پورت را بررسی می‌کنند. healthcheck با pg_isready واقعاً آمادگی PostgreSQL را تست می‌کند و بدون اسکریپت اضافه، مستقیماً در خود Compose پشتیبانی می‌شود.

آیا همین فایل برای production مناسب است؟

به‌عنوان پایه بله، اما برای production یک فایل override جدا (مثلاً compose.prod.yaml) با ایمیج ساخته‌شده، gunicorn، بدون mount کد و با مدیریت secret بسازید و با docker compose -f compose.yaml -f compose.prod.yaml up -d اجرا کنید.

جمع‌بندی #

با یک فایل compose.yaml درست، کل محیط توسعهٔ Django (دیتابیس، cache، worker و مایگریشن) با یک دستور و به ترتیب صحیح بالا می‌آید. کلید ماجرا استفاده از healthcheck و condition: service_healthy به‌جای depends_on ساده است. اگر بعد از راه‌اندازی دیدید کوئری‌هایتان کند است، مطلب مشکل N+1 در Django نقطهٔ شروع خوبی برای بهینه‌سازی است.

این پست چطور بود؟

پست‌های مرتبط