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.

ساختار پروژه #
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 را ببینید. برای توسعه یک نسخهٔ سادهتر کافی است:
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 هم توصیه میکند.
فایل محیطی #
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 کامل #
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 #
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.
دستورات روزمره #
# ساخت و اجرای همهچیز
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 هم دارد:
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 نقطهٔ شروع خوبی برای بهینهسازی است.