Docker و Compose

سرویس را در image بسته‌بندی کن، با Compose چند سرویس را با شبکه، healthcheck و volume اجرا کن و داده را از ماندن یا گم‌شدن در container جدا کن.

بعد از این درس می‌توانی

  • تفاوت image، container و volume را توضیح دهد و بداند کدام داده با حذف container از بین می‌رود.
  • برای یک سرویس Python یک Dockerfile با کاربر بدون دسترسی ریشه، healthcheck و .dockerignore بنویسد.
  • با Compose دو سرویس را با شبکه داخلی، شرط سالم‌بودن و volume نام‌دار اجرا و عیب‌یابی کند.
  • پورت را فقط روی نشانی لازم منتشر کند و راز را از image و فایل Compose بیرون نگه دارد.

چرا این درس مهم است

دستیار ایمیل پروژه ۴ روی لپ‌تاپ سازنده‌اش کار می‌کرد. روی سرور برگ سبز اجرا نشد چون نسخه Python فرق داشت؛ بعد اجرا شد ولی هر بار که دوباره راه‌اندازی می‌شد، دفتر پردازش خالی بود و همه ایمیل‌ها را از نو پردازش می‌کرد؛ و یک هفته بعد معلوم شد پورت API آزمایشی برای کل اینترنت باز بوده است.

Docker این مشکل‌ها را با یک قرارداد ساده حل می‌کند: هر چیزی که سرویس برای اجرا لازم دارد در یک image بسته‌بندی می‌شود، داده‌ای که باید بماند در volume جدا نگه داشته می‌شود، و Compose همه سرویس‌ها و ارتباطشان را در یک فایل قابل بازبینی می‌نویسد. n8n در دوره بعد، و ایجنت‌ها و سرویس‌های خودت، همه همین‌طور اجرا می‌شوند.

مفاهیم کلیدی

یادآوری: نسخه‌بندی با Git و .gitignore را در درس قبل ساختی.

  • Image (تصویر): بسته تغییرناپذیر فایل‌ها، کتابخانه‌ها و تنظیماتی که یک سرویس برای اجرا لازم دارد.
  • Container (کانتینر): یک فرایند ایزوله که از روی image اجرا می‌شود و یک لایه نوشتنی موقت دارد.
  • Volume (حجم داده): فضای ذخیره‌ای که Docker مدیریت می‌کند و پس از حذف container باقی می‌ماند.
  • Healthcheck (بررسی سلامت): فرمانی که Docker دوره‌ای اجرا می‌کند تا بداند سرویس واقعاً آماده است، نه فقط روشن.
  • Compose File (فایل Compose): فایل YAML که چند سرویس، شبکه، volume و پیکربندی‌شان را یک‌جا تعریف می‌کند.

مدل ذهنی

image را مثل دستور پخت و مواد بسته‌بندی‌شده ببین و container را مثل یک بار پختن آن. هر بار می‌توانی دوباره بپزی و نتیجه یکسان است؛ ولی چیزی که روی میز آشپزخانه همان بار ماند (لایه نوشتنی container) با جمع‌کردن میز دور ریخته می‌شود. چیزی که باید بماند، مثل دفتر حساب رستوران، در کمد جدا (volume) نگه داشته می‌شود. Compose برنامه آشپزخانه است: کدام غذا، به چه ترتیب، کدام کمد مال کدام آشپز.

image، container، volume و شبکه در Compose: Dockerfile با docker build به image تبدیل می‌شود؛ از روی یک image دو container اجرا می‌شود؛ container دستیار به volume نام‌دار وصل است که پس از حذف container می‌ماند؛ دو container در شبکه Compose با نام سرویس به هم دسترسی دارند؛ پورت API فقط روی 127.0.0.1 میزبان منتشر شده است.

image، container، volume و شبکه در Compose

این تشبیه کجا غلط است؟ دستور پخت را آشپز همیشه با مواد تازه می‌پزد، ولی image وقتی ساخته شد عوض نمی‌شود: اگر کتابخانه‌ای در آن آسیب‌پذیر شد، image قدیمی همچنان آسیب‌پذیر است تا دوباره بسازی. و کمد آشپزخانه قفل دارد، ولی پورتی که منتشر می‌کنی ممکن است بی‌آنکه بدانی برای همه باز باشد.

گام‌به‌گام

گام ۱: سه چیز را جدا ببین

image تغییرناپذیر است؛ برای تغییر، image تازه می‌سازی یا لایه‌ای رویش اضافه می‌کنیsrc-docker-what-is-image. هر چیزی که در لایه نوشتنی container نوشته شود با حذف container از بین می‌رود؛ volume را Docker مدیریت می‌کند و پس از حذف containerها هم داده را نگه می‌دارد. bind mount یک مسیر مشخص از میزبان را به container وصل می‌کند و هر دو طرف می‌توانند آن را تغییر دهندsrc-docker-storage. قاعده عملی:

دادهکجا
کد و کتابخانه‌هاداخل image
دفتر پردازش، پایگاه داده، فایل‌های کاربرvolume نام‌دار
فایلی که از میزبان ویرایش می‌کنی (مثل پیکربندی پراکسی)bind mount
رازنه image، نه فایل Compose؛ درس پیکربندی

گام ۲: Dockerfile خوب

فایل assets/Dockerfile را باز کن؛ هر خط یک تصمیم است:

FROM python:3.12-slim
WORKDIR /app
COPY barg-sabz-mock-api.py email_assistant.py ./
RUN mkdir -p /data && chown 10001:10001 /data
USER 10001
EXPOSE 8787
HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=3 \
  CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8787/health', timeout=2)"]
CMD ["python", "barg-sabz-mock-api.py", "--host", "0.0.0.0", "--port", "8787"]

راهنمای رسمی Docker چند اصل دارد که این فایل رعایت کرده: پایه کوچک و معتمد، نصب‌نکردن بسته اضافه، یک دغدغه در هر container، و .dockerignore برای بیرون نگه داشتن فایل‌های نامربوط از buildsrc-docker-build-best-practices. همان راهنما توصیه می‌کند نسخه image پایه را سنجاق کنی چون برچسب‌ها تغییرپذیرندsrc-docker-build-best-practices؛ در تولید به‌جای python:3.12-slim از digest آن استفاده کن. .dockerignore اینجا مهم‌تر از سرعت است: فایلی که وارد build نشود، نمی‌تواند در لایه image جا بماند.

USER 10001 یعنی سرویس با کاربر بدون دسترسی ریشه اجرا می‌شود. خط chown برای همین است: در اجرای واقعی این درس، بدون آن، دستیار با خطای unable to open database file متوقف شد چون volume تازه مال root بود (assets/docker-session.txt نسخه اصلاح‌شده را نشان می‌دهد).

گام ۳: Compose

assets/compose.yaml دو سرویس دارد که از یک image ساخته می‌شوند:

  • mock-api: پورت را فقط روی 127.0.0.1:8787 منتشر می‌کند؛ یعنی فقط همین کامپیوتر.
  • assistant: یک job است (با profiles که با up اجرا نشود)، به API با نام سرویس (http://mock-api:8787) وصل می‌شود، منتظر می‌ماند تا API سالم شود (condition: service_healthy) و دفتر پردازش را در volume نام‌دار assistant_data می‌نویسد.

مقدار MOCK_API_TOKEN با ${MOCK_API_TOKEN:?...} از فایل .env کنار Compose خوانده می‌شود و اگر نباشد، Compose با پیام روشن متوقف می‌شود. جایگزینی متغیر از .env یک قابلیت Compose CLI است و با قراردادن متغیر در container فرق داردsrc-docker-compose-env. مستندات Docker صریح می‌گوید از متغیر محیطی برای رساندن اطلاعات حساس مثل رمز استفاده نکن و به‌جایش از secrets استفاده کنsrc-docker-compose-env؛ چون متغیر محیطی برای همه فرایندها دیدنی است و ممکن است در لاگ بیایدsrc-docker-compose-secrets. مقدار این درس آزمایشی است؛ روش درست راز را در درس پیکربندی می‌سازی.

گام ۴: اجرا، دیدن، پاک‌کردن

docker compose up -d --build mock-api      # ساخت image و اجرای API در پس‌زمینه
docker compose ps                          # وضعیت و (healthy)
docker compose logs -f mock-api            # لاگ زنده
docker compose run --rm assistant poll     # اجرای یک‌باره job
docker compose down                        # حذف containerها و شبکه؛ volume می‌ماند
docker compose down -v                     # همراه volume؛ داده پاک می‌شود

در اجرای واقعی، پس از down و up دوباره، دستیار همان دفتر پردازش قبلی را دید: هفت پیام با همان وضعیت. این یعنی volume کار می‌کند. down -v را فقط وقتی بزن که واقعاً می‌خواهی داده پاک شود.

گام ۵: پورت و فایروال

پورت منتشرشده با "8787:8787" روی همه نشانی‌های میزبان باز است. مستندات Docker هشدار می‌دهد Docker و فایروال ufw با هم سازگار نیستند: ترافیک پورت منتشرشده پیش از رسیدن به قاعده‌های ufw مسیر دیگری می‌رود، پس «بستن پورت در ufw» آن را نمی‌بنددsrc-docker-packet-filtering. ساده‌ترین دفاع این است که پورت را فقط روی 127.0.0.1 منتشر کنی و دسترسی بیرونی را از پراکسی معکوس بدهی (درس بعد)، یا اگر سرویس فقط برای سرویس‌های دیگر Compose است، اصلاً پورت منتشر نکنی.

مثال‌ها

پیاده‌سازی عملی

ساخت image، اجرای دو سرویس و آزمون ماندگاری داده. حدود ۲۲ دقیقه.

  1. یک پوشه بساز و این فایل‌ها را کنار هم بگذار: assets/Dockerfile، assets/compose.yaml، assets/env.example، shared/barg-sabz-mock-api.py و email_assistant.py از پروژه ۴. فایل assets/dockerignore.txt را با نام .dockerignore و env.example را با نام .env کپی کن.
  2. یکی از مسیرهای پایین را برو.
  3. سه آزمون را اجرا یا پیش‌بینی کن و نتیجه را بنویس: (الف) down و up دوباره و report؛ (ب) down -v و report؛ (ج) خط chown را حذف کن، down -v و up --build و poll.
اجرای محلی

با Docker Engine یا Docker Desktop: فرمان‌های گام ۴ را به ترتیب اجرا کن. docker compose ps باید (healthy) و پورت 127.0.0.1:8787 را نشان دهد. با docker compose exec mock-api id ببین سرویس با کاربر غیرریشه اجرا می‌شود. اگر API آزمایشی را بیرون از Docker هم اجرا کرده‌ای، پیش از up آن را ببند چون پورت 8787 گرفته است.

بدون اجرا / شبیه‌ساز

بدون Docker: assets/docker-session.txt را بخوان؛ خروجی واقعی همین فرمان‌هاست. از روی آن بنویس: (۱) کدام خط نشان می‌دهد دستیار پیش از سالم‌شدن API اجرا نشد؛ (۲) کاربر داخل container کیست و چرا مهم است؛ (۳) کدام فرمان ثابت می‌کند volume پس از down مانده است؛ (۴) اگر ports را "8787:8787" می‌نوشتی، روی سرور چه کسانی به API دسترسی داشتند.

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

اشتباهنتیجهکار درست
داده در لایه containerبا هر به‌روزرسانی، داده از بین می‌رودvolume نام‌دار
ports: "8787:8787" روی سرورسرویس برای همه باز، حتی با ufw127.0.0.1: یا بدون انتشار
اجرای سرویس با rootآسیب‌پذیری در برنامه = دسترسی ریشه در containerUSER غیرریشه
نبود .dockerignore.env و .git در لایه imageفهرست صریح
برچسب latest در تولیدبه‌روزرسانی ناخواسته و غیرقابل تکرارنسخه یا digest سنجاق‌شده
depends_on بدون شرط سلامتjob پیش از آماده‌شدن API اجرا و شکست می‌خوردcondition: service_healthy
down -v برای «تمیزکاری»پاک‌شدن پایگاه دادهفقط down

اشکال‌زدایی

sqlite3.OperationalError: unable to open database file در container با کاربر غیرریشه.

volume نام‌دار تازه با مالکیت root ساخته شده و کاربر 10001 اجازه نوشتن ندارد.

docker compose run --rm --entrypoint sh assistant -c 'id; ls -ld /data'

پوشه را در Dockerfile بساز و مالکیتش را بده (RUN mkdir -p /data && chown 10001:10001 /data)، سپس down -v و up --build تا volume تازه با همان مالکیت ساخته شود.

job با خطای اتصال به mock-api شکست می‌خورد، گاهی بله گاهی نه.

container API روشن شده ولی هنوز آماده پاسخ نیست؛ depends_on ساده فقط شروع را صبر می‌کند.

docker compose ps وضعیت (health: starting) را نشان می‌دهد؛ زمان خطا را با لاگ API مقایسه کن.

healthcheck در image و condition: service_healthy در Compose؛ و در خود برنامه، تلاش دوباره کوتاه.

docker compose up بلافاصله با «set MOCK_API_TOKEN in .env» متوقف می‌شود.

فایل .env کنار compose.yaml نیست یا متغیر در آن تعریف نشده است.

docker compose config مقدارهای جایگزین‌شده را نشان می‌دهد؛ اول ببین فایل .env در همان پوشه است.

env.example را با نام .env کپی کن و مقدار بده؛ .env را هرگز commit نکن.

نکته‌های امنیتی

تمرین کوتاه

تمرین · 12 دقیقه

هدف: خواندن یک فایل Compose و پیدا کردن خطرها.

گام‌ها: این بخش از یک فایل Compose را بخوان و هر ایراد را با اصلاحش بنویس:

services:
  bot:
    image: my-bot:latest
    ports:
      - "5000:5000"
    environment:
      BOT_TOKEN: 123456:real-looking-token
    volumes:
      - ./:/app

معیار پذیرش: دست‌کم چهار ایراد: برچسب latest، پورت باز روی همه نشانی‌ها، راز در فایل، و bind mount کل پوشه پروژه.

راه‌حل نمونه

(۱) latest تغییرپذیر است؛ نسخه یا digest سنجاق کن. (۲) "5000:5000" روی همه نشانی‌ها باز است و ufw جلویش را نمی‌گیرد؛ "127.0.0.1:5000:5000" یا پشت پراکسی. (۳) توکن در فایل Compose است و با commit در Git می‌رود؛ آن را باطل و عوض کن و از .env بیرون از Git یا secrets بخوان. (۴) ./:/app کل پوشه پروژه (شاید با .env و .git) را در container در دسترس و قابل نوشتن می‌گذارد؛ کد را در image بگذار و فقط پوشه داده را volume کن. اگر سرویس با root اجرا می‌شود، این ریسک بیشتر است.

چالش

تمرین · 35 دقیقه

موقعیت: یکی از اسکریپت‌ها یا سرویس‌های کوچک خودت (یا API آزمایشی، اگر سرویسی نداری) را با Docker و Compose اجرا کن. داده آزمون را ساختگی یا ناشناس‌شده نگه دار.

  1. Dockerfile با کاربر غیرریشه، healthcheck (اگر سرویس شبکه‌ای است) و .dockerignore.
  2. فایل Compose با پورت محلی، volume برای داده‌ای که باید بماند و .env.example.
  3. آزمون ماندگاری: down، up و نشان‌دادن اینکه داده مانده است.
  4. فهرست هر داده و جایی که نگه داشته می‌شود (image، volume، bind mount یا هیچ‌جا).

خروجی مورد انتظار: Dockerfile، فایل Compose، .env.example، خروجی آزمون ماندگاری و جدول داده.

معیار پذیرش:

  • سرویس با کاربر غیرریشه اجرا می‌شود (خروجی id).
  • هیچ پورتی روی همه نشانی‌ها منتشر نشده است.
  • هیچ راز یا داده واقعی در image یا فایل Compose نیست.
  • داده لازم پس از down و up مانده است.

پرسش‌های سنجش

جمع‌بندی

  • image تغییرناپذیر است، container موقتی است و volume داده را نگه می‌دارد.
  • Dockerfile خوب: پایه کوچک و سنجاق‌شده، فقط فایل لازم، .dockerignore، کاربر غیرریشه و healthcheck.
  • با کاربر غیرریشه، پوشه volume را در image با مالکیت درست بساز.
  • در Compose سرویس‌ها با نام هم را پیدا می‌کنند؛ service_healthy منتظر آمادگی واقعی می‌ماند.
  • پورت را فقط روی 127.0.0.1 منتشر کن؛ ufw جلوی پورت منتشرشده Docker را نمی‌گیرد.
  • down امن است؛ down -v داده را پاک می‌کند.

پرسش‌های سنجش

سرویسی سه نوع داده دارد: (الف) کد Python و کتابخانه‌ها؛ (ب) فایل SQLite که وضعیت پیام‌های پردازش‌شده را نگه می‌دارد؛ (ج) فایل لاگ موقت که فقط برای اشکال‌زدایی همان اجراست. هرکدام کجا باشد و با docker compose down و سپس up دوباره، کدام می‌ماند؟

پاسخ نمونه و معیار ارزیابی

(الف) داخل image؛ با هر up از همان image دوباره می‌آید. (ب) volume نام‌دار؛ پس از down می‌ماند و فقط با down -v پاک می‌شود. (ج) لایه نوشتنی container یا خروجی استاندارد؛ با حذف container از بین می‌رود و این برای لاگ موقت اشکالی ندارد (لاگ ماندگار را با docker compose logs یا سامانه لاگ نگه دار).

  • کد در image (1 امتیاز)
  • SQLite در volume و ماندگار (1 امتیاز)
  • لاگ موقت در container و از بین رفتنش (1 امتیاز)
  • همه چیز در container می‌ماند ← down container را حذف می‌کند؛ فقط volume می‌ماند.

علت خطا چیست و اصلاح درست کدام است؟ چرا «اجرای container با root» اصلاح خوبی نیست؟

خروجی اجرای job:

$ docker compose run --rm worker
Traceback ...
  File "/app/worker.py", line 12, in <module>
    con = sqlite3.connect('/data/state.db')
sqlite3.OperationalError: unable to open database file
$ docker compose run --rm --entrypoint sh worker -c 'id; ls -ld /data'
uid=10001 gid=0(root)
drwxr-xr-x 2 root root 4096 Oct 21 09:10 /data
پاسخ نمونه و معیار ارزیابی

پوشه /data (volume تازه) مال root است و کاربر 10001 اجازه نوشتن ندارد. اصلاح: در Dockerfile پیش از USER، پوشه را بساز و مالکیت بده (RUN mkdir -p /data && chown 10001:10001 /data)، سپس volume را با down -v (اگر داده‌ای ندارد) دوباره بساز تا مالکیت از image بیاید. اجرای با root خطا را پنهان می‌کند ولی هر آسیب‌پذیری برنامه را به دسترسی ریشه در container تبدیل می‌کند.

  • مالکیت root روی volume (1 امتیاز)
  • mkdir و chown در Dockerfile و ساخت دوباره volume (1 امتیاز)
  • ریسک اجرای root (1 امتیاز)
  • chmod 777 ← به همه کاربران اجازه نوشتن می‌دهد؛ مالکیت درست، دقیق‌تر و امن‌تر است.

برای یک ربات Python که روی پورت 8080 گوش می‌دهد و endpoint سلامت /health دارد، Dockerfile کوتاه بنویس و برای هر خط مهم یک دلیل بیاور.

پاسخ نمونه و معیار ارزیابی

FROM python:3.12-slim (پایه کوچک؛ در تولید با digest)؛ WORKDIR /app؛ COPY requirements.txt . و RUN pip install --no-cache-dir -r requirements.txt (لایه وابستگی جدا برای استفاده از cache)؛ COPY bot.py . (فقط فایل لازم، همراه .dockerignore)؛ USER 10001 (غیرریشه)؛ EXPOSE 8080؛ HEALTHCHECK CMD python -c با urllib به /health (آمادگی واقعی)؛ CMD ["python", "bot.py"] به شکل آرایه.

  • پایه کوچک و نسخه مشخص (1 امتیاز)
  • فقط فایل لازم و .dockerignore (1 امتیاز)
  • کاربر غیرریشه (1 امتیاز)
  • healthcheck (1 امتیاز)
  • COPY . . ← بدون .dockerignore، .env و .git هم وارد image می‌شوند.

روی سرور ufw فقط پورت‌های 22، 80 و 443 را باز گذاشته است. در Compose یک سرویس با ports: "5678:5678" منتشر شده. طبق مستندات Docker چه اتفاقی می‌افتد؟

  • ufw پورت 5678 را می‌بندد چون در فهرست مجاز نیست.
  • پورت 5678 از بیرون در دسترس است، چون ترافیک پورت منتشرشده Docker پیش از قاعده‌های ufw مسیر دیگری می‌رود.
  • Docker پیش از انتشار، از ufw اجازه می‌گیرد.
  • پورت فقط برای containerهای دیگر باز است.
پاسخ نمونه و معیار ارزیابی
  • a ← مستندات Docker می‌گوید Docker و ufw ناسازگارند و قاعده‌های ufw برای پورت منتشرشده اثر ندارند.
  • c ← Docker قاعده‌های خودش را مستقیم اضافه می‌کند.
  • d ← این حالت «منتشرنکردن» است؛ ports یعنی انتشار روی میزبان.

همکار می‌خواهد کلید API را با environment در compose.yaml بگذارد «چون ساده است». موازنه این کار با .env بیرون از Git و با secrets در Compose را بنویس.

پاسخ نمونه و معیار ارزیابی

در compose.yaml: ساده‌ترین، ولی با فایل وارد Git می‌شود و هر کس فایل را ببیند کلید را دارد؛ رد. .env بیرون از Git با جایگزینی متغیر: کلید از مخزن بیرون است ولی در محیط container قرار می‌گیرد، برای همه فرایندها دیدنی است و ممکن است در لاگ یا docker inspect بیاید. secrets در Compose: فایل در /run/secrets/<نام> سوار می‌شود و فقط سرویس‌هایی که اجازه دارند آن را می‌بینند؛ مستندات Docker برای اطلاعات حساس همین را توصیه می‌کند، ولی برنامه باید از فایل بخواند. تصمیم: secrets یا مدیر راز برای کلید واقعی؛ .env فقط برای مقدار غیرحساس یا آزمایشی.

  • رد قراردادن کلید در فایل Compose (1 امتیاز)
  • ضعف متغیر محیطی (دیدنی برای فرایندها و لاگ) (1 امتیاز)
  • secrets و نیاز برنامه به خواندن از فایل (1 امتیاز)
  • .env کاملاً امن است ← .env کلید را از Git بیرون نگه می‌دارد، ولی در container به متغیر محیطی تبدیل می‌شود.

فایل‌های درس

image مشترک API آزمایشی و دستیار ایمیل با کاربر غیرریشه و healthcheck

Dockerfile

دو سرویس با شبکه داخلی، شرط سالم‌بودن، volume نام‌دار و پورت محلی

compose.yaml

قالب .dockerignore

dockerignore.txt

نمونه .env با مقدار آزمایشی

env.example

خروجی واقعی اجرای فرمان‌های درس

docker-session.txt

API آزمایشی که در image قرار می‌گیرد

barg-sabz-mock-api.py

ابزارها و جایگزین‌ها

  • Docker Engine با Compose v2 — ساخت و اجرای image — Docker Desktop با رعایت مجوز — مسیر بدون نصب با خروجی نمونه

منابع

What is an image? Docker Docs Docker Docs, 2026-10

Storage (volumes, bind mounts, tmpfs) Docker Docs Docker Docs, 2026-10

Building best practices Docker Docs Docker Docs, 2026-10

Set environment variables within your container's environment Docker Docs Docker Docs, 2026-10

Manage secrets securely in Docker Compose Docker Docs Docker Docs, 2026-10

Packet filtering and firewalls Docker Docs Docker Docs, 2026-10

Docker Desktop license agreement Docker Docker Docs, 2026-10

دوره

زیرساخت پایه برای سازندگان