الحاويات Containers وتنسيقها مع Kubernetes الأدلة التقنية

أفضل الممارسات Best Practices في ملفات Docker Compose

كيف تكتب ملف Compose يبدأ خدماته بالترتيب الصحيح ويحمي كلمات المرور ويضبط الذاكرة ويفصل التطوير عن الإنتاج، مع تجربة أظهرت أين يخدعك كل إعداد افتراضي.

أفضل الممارسات Best Practices في ملفات Docker Compose

لنفرض أن لديك تطبيقاً من أربع خدمات يعمل على جهازك بأمر واحد هو docker compose up: واجهة خلف nginx، وAPI صغير، وقاعدة بيانات PostgreSQL، وRedis بجانبها. ثم نقلت الملف نفسه إلى السيرفر، فبدأ كل شيء يعمل، إلا أن ال API يتوقف أحياناً بعد إعادة تشغيل السيرفر ويعود في المرة التالية، وكلمة مرور قاعدة البيانات تظهر لكل من يكتب docker inspect، ومنفذ قاعدة البيانات الذي فتحته يوماً لبرنامج على جهازك صار مفتوحاً على السيرفر أيضاً، وفي يوم مزدحم استهلك ال API ذاكرة السيرفر كلها حتى توقفت الخدمات الأخرى. والملف لم يتغير فيه حرف بين الجهاز والسيرفر، وهذه بالضبط المشكلة: الملف الذي «يعمل على جهازي» يعمل لأن جهازك يسامحه، والسيرفر لا يسامح.

وقد شرحنا في تثبيت Docker Engine وCompose على Ubuntu كيف تثبت Docker وتضبط تدوير السجلات، وفي شبكات Docker وأفضل الممارسات كيف تصل الخدمات إلى بعضها دون نشر المنافذ. وهذا المقال يكمل من هناك، فيأخذ ملف Compose نفسه ويمر على كل جزء فيه يتصرف بشكل مختلف عما يتوقعه أغلب الناس، مع تجربة كاملة شغلنا فيها التطبيق ذا الخدمات الأربع، وأعدنا إنتاج كل مشكلة قبل أن نصلحها، والمخرجات المعروضة كلها حقيقية من التجربة.

وسوف نناقش في هذا المقال ما يلي:

  • ترتيب البدء Startup Order: لماذا لا ينتظر depends_on ما تظنه، وكيف يكذب فحص الصحة الشائع لقاعدة PostgreSQL أثناء أول تشغيل.
  • فحوص الصحة Health Checks ومهام الترحيل التي تعمل مرة واحدة، والأمر docker compose up --wait.
  • المتغيرات Environment Variables والأسرار Secrets: الفرق بين ملف .env وenv_file وsecrets، ومن يرى كل واحد منها.
  • الخدمات الاختيارية Profiles، وال Volumes واسم المشروع، وعزل الشبكات بشبكة داخلية.
  • حدود الموارد Resource Limits ومفاجأة ال Swap، وسياسات إعادة التشغيل Restart Policies مع Container يعيد التشغيل بلا نهاية.
  • الأمر docker compose config، وملفات التطوير والإنتاج Overrides، ووضع المراقبة Compose Watch.

لماذا يحتاج ملف Compose إلى ممارسات خاصة؟

ملف Compose وصف للحالة التي تريدها، أي أنك لا تكتب فيه خطوات التشغيل وإنما تكتب ما يجب أن يكون موجوداً: هذه الخدمات، بهذه ال Images، على هذه الشبكات، مع هذه ال Volumes، ثم يقارن Compose ما كتبته بما يعمل فعلاً ويغير الفرق فقط. وهذا يجعل الملف أهم وثيقة في المشروع بعد الكود نفسه، فهو يقول ما الذي يعمل، وبأي إعدادات، ومن يتصل بمن. ولكن Compose في المقابل متسامح جداً: يقبل ملفاً ناقصاً ويكمله بالقيم الافتراضية، ويبدأ الخدمات حتى لو لم تكن جاهزة، ويعوض المتغير غير الموجود بنص فارغ مع تحذير صغير، والقيم الافتراضية مصممة لكي يعمل المثال الأول بسرعة على جهاز المطور، وليس لكي يصمد السيرفر.

لذلك لنبدأ بالمسودة الأولى التي يكتبها أغلب الناس، وهي ليست خاطئة بالمعنى المباشر، فقد عملت على الجهاز في أغلب المرات:

# First draft: works on the developer's laptop "most of the time".
services:
  web:
    image: nginx:1.29.8-alpine
    ports: ["8080:80"]
    volumes:
      - ./web/index.html:/usr/share/nginx/html/index.html:ro
      - ./web/default.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on: [api]
  api:
    build: ./api
    environment:
      DB_PASSWORD: s3cret-pass
    depends_on: [db, redis]
  db:
    image: postgres:18-alpine
    environment:
      POSTGRES_USER: shop
      POSTGRES_PASSWORD: s3cret-pass
    volumes:
      - pgdata:/var/lib/postgresql
  redis:
    image: redis:8-alpine
volumes:
  pgdata:

في الإعداد أعلاه لاحظ التالي، وكل نقطة منها سوف تظهر في التجربة كمشكلة حقيقية:

  • depends_on: [db, redis] بالصيغة المختصرة لا يعني «انتظر حتى تجهز قاعدة البيانات»، وإنما «ابدأ قاعدة البيانات قبلي» فقط.
  • كلمة المرور مكتوبة في الملف نفسه وفي متغيرات البيئة، فتصل إلى Git وإلى كل من يقرأ إعدادات ال Container.
  • لا يوجد أي فحص صحة Health Check، فلا يعرف Docker ولا Compose هل الخدمة تعمل فعلاً أم أن العملية بدأت فقط.
  • لا توجد حدود للذاكرة ولا سياسة إعادة تشغيل، وكل الخدمات على شبكة واحدة يصل فيها nginx إلى قاعدة البيانات مباشرة.
  • الوسوم postgres:18-alpine وredis:8-alpine تتحرك مع كل إصدار فرعي، فما يعمل اليوم ليس ما سيعمل بعد شهر.

التطبيق في التجربة: أربع خدمات ومهمة ترحيل

التطبيق بسيط عمداً لكي تبقى الملاحظة على Compose وليس على الكود. فال API برنامج Node.js صغير يعد الزيارات في جدول PostgreSQL وفي عداد Redis، ويتصل بالقاعدة مرة واحدة عند البدء دون أي إعادة محاولة Retry، كما تفعل تطبيقات حقيقية كثيرة، ويقرأ كلمة المرور من ملف إذا وجد المتغير DB_PASSWORD_FILE، ويتعامل مع إشارة SIGTERM لكي يتوقف بشكل نظيف كما شرحنا في الإيقاف النظيف Graceful Shutdown. وفيه مسار /api/hog يحجز 50 ميجابايت في كل طلب لكي نرى حد الذاكرة يعمل، ومسار /healthz لفحص الصحة. وبجانبه برنامج ترحيل migrate.js ينشئ الجدول ثم يخرج، وnginx يقدم صفحة ثابتة ويمرر /api/ إلى ال API. والملفات كاملة في مجلد lab مع المقال، وهذا جزء البدء من ال API لأنه سبب أول مشكلة:

const db = newClient();
const cache = createClient({ url: process.env.REDIS_URL || 'redis://redis:6379' });
const t0 = Date.now();
await db.connect();
await cache.connect();
console.log(`api: connected to postgres and redis in ${Date.now() - t0} ms, version ${process.env.APP_VERSION || 'dev'}`);

وال Dockerfile الخاص به قصير، لأن كتابة Dockerfile صحيح موضوع مقال مستقل في هذه المرحلة:

FROM node:24-alpine
WORKDIR /app
COPY package.json ./
RUN npm install --omit=dev --no-audit --no-fund
COPY *.js ./
USER node
CMD ["node", "server.js"]

وكل التجربة على Docker Engine 29.8.0 مع Docker Compose v5.5.1، وPostgreSQL 18.6 وRedis 8.10.3 وnginx 1.29.8 بصيغة Alpine، وNode.js 24.21.0.

ترتيب البدء Startup Order: depends_on لا ينتظر ما تظنه

أول ما يفعله أغلب الناس عندما يكون عندهم تطبيق يحتاج قاعدة بيانات هو أن يكتبوا depends_on ويطمئنوا. وهذا الخيار يفعل شيئاً واحداً بصيغته المختصرة، وهو ترتيب إنشاء ال Containers وتشغيلها، فيبدأ Compose قاعدة البيانات أولاً ثم ال API، ولكنه لا ينتظر أن تكون قاعدة البيانات قادرة على استقبال الاتصالات، لأنه لا يعرف أصلاً ماذا تعني «جاهزة» لبرنامج لا يعرفه. وتقول وثائق ترتيب البدء ذلك صراحة: Compose ينتظر أن يكون ال Container في حالة «يعمل» Running، وليس أن يكون جاهزاً Ready.

إعادة إنتاج سباق البدء Startup Race

شغلنا المسودة الأولى على Volume جديد فارغ، أي كما يحدث في أول تثبيت على سيرفر جديد، أو بعد أن يحذف أحدهم ال Volume ليبدأ من جديد:

docker compose -p ct2-c-first -f compose.first.yaml up -d
docker compose -p ct2-c-first -f compose.first.yaml ps -a
NAME                  IMAGE                 COMMAND                  SERVICE   CREATED          STATUS                     PORTS
ct2-c-first-api-1     ct2-c-first-api       "docker-entrypoint.s…"   api       15 seconds ago   Exited (1) 8 seconds ago
ct2-c-first-db-1      postgres:18-alpine    "docker-entrypoint.s…"   db        15 seconds ago   Up 12 seconds              5432/tcp
ct2-c-first-redis-1   redis:8-alpine        "docker-entrypoint.s…"   redis     15 seconds ago   Up 12 seconds              6379/tcp
ct2-c-first-web-1     nginx:1.29.8-alpine   "/docker-entrypoint.…"   web       14 seconds ago   Up 10 seconds              0.0.0.0:8080->80/tcp, [::]:8080->80/tcp

والأمر up -d نفسه خرج بنجاح وكتب Started لكل الخدمات الأربع، فلو لم ننظر إلى ps لظننا أن كل شيء يعمل. أما سجل ال API فيقول:

Error: connect ECONNREFUSED 172.21.0.3:5432
    at TCPConnectWrap.afterConnect [as oncomplete] (node:net:2021:16) {
  errno: -111,
  code: 'ECONNREFUSED',
  syscall: 'connect',
  address: '172.21.0.3',
  port: 5432
}

في المخرج أعلاه لاحظ التالي:

  • العنوان 172.21.0.3 صحيح، أي أن اسم db وجد طريقه عبر ال DNS الداخلي، فال Container يعمل وله عنوان، ولكن لا أحد يستمع على المنفذ 5432 بعد.
  • ECONNREFUSED تعني أن الطرف الآخر رد برفض فوري، وهذا يختلف عن انتهاء المهلة Timeout الذي يعني أن أحداً لم يرد أصلاً.
  • بدأ ال Container الخاص بقاعدة البيانات في الثانية 0، وبدأ ال API بعده بأقل من ثانية، وانهار في الثانية 3.6، بينما كتبت PostgreSQL أنها تستمع على المنفذ عبر الشبكة في الثانية 17.5.

والسبب في هذه السبع عشرة ثانية أن صورة PostgreSQL الرسمية تفعل في أول تشغيل عملاً كثيراً: تنشئ ملفات قاعدة البيانات بالأمر initdb، ثم تشغل خادماً مؤقتاً لتنشئ المستخدم وقاعدة البيانات وتنفذ سكربتات التهيئة، ثم توقفه وتبدأ الخادم الحقيقي. وعلى سيرفر بقرص سريع قد يأخذ هذا ثانيتين، وعلى قرص بطيء أو مشغول أخذ في تجربتنا أكثر من 17 ثانية، وفي مرة أخرى أخذت عملية الحفظ Checkpoint وحدها عند إيقاف الخادم المؤقت 9.6 ثانية. والمهم هنا أن الوقت يتغير من تشغيل لآخر ومن سيرفر لآخر، ولذلك يظهر الخطأ أحياناً ويختفي أحياناً، وهو أسوأ نوع من الأخطاء.

خط زمني من التجربة: db بدأت في الثانية 0 وبقيت تنشئ ملفات قاعدة البيانات حتى الثانية 15.9 ثم خادم مؤقت على Socket ثم الخادم الحقيقي على TCP في الثانية 17.5، بينما ال API بدأ في الثانية 0.7 وانهار برسالة ECONNREFUSED في الثانية 3.6
سباق البدء في التجربة: ال API انهار قبل أن تستمع قاعدة البيانات عبر الشبكة بأربع عشرة ثانية

وقد يتساءل البعض: لماذا لا أضيف restart: always فيعيد Docker تشغيل ال API حتى ينجح؟ والإجابة أن هذا يعمل في أغلب الأحيان، وسوف نستخدم سياسة إعادة التشغيل فعلاً، ولكنه حل لعرض المشكلة وليس لسببها. فال API سوف يعيد التشغيل عدة مرات، وكل مرة تكتب سجل خطأ كاملاً، ومن يقرأ السجلات بعد عطل حقيقي سيجد عشرات الأخطاء المتشابهة لا يعرف أيها المهم، والخدمات التي تعتمد على ال API تبدأ هي أيضاً قبل أن يكون جاهزاً. والحل الأنسب أن تخبر Compose ماذا تعني «جاهز» لكل خدمة، ثم تجعل الانتظار شرطاً.

شروط الانتظار: service_healthy وservice_completed_successfully

الصيغة الطويلة من depends_on تقبل ثلاثة شروط Conditions، كما في مرجع خيارات الخدمات:

  • service_started: السلوك الافتراضي نفسه، ينتظر أن يبدأ ال Container فقط.
  • service_healthy: ينتظر أن يصبح فحص الصحة الخاص بالخدمة الأخرى ناجحاً، وهذا يعني أن الخدمة الأخرى يجب أن يكون لها healthcheck.
  • service_completed_successfully: ينتظر أن تنتهي الخدمة الأخرى برمز خروج 0، وهذا مخصص للمهام التي تعمل مرة واحدة، مثل ترحيل قاعدة البيانات Migration أو تحميل بيانات أولية.

وهذا الجزء من الملف النهائي في التجربة:

  api:
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
      migrate:
        condition: service_completed_successfully

  migrate:
    image: ct2-c-shop-api:${APP_VERSION}
    command: ["node", "migrate.js"]
    depends_on:
      db:
        condition: service_healthy
    restart: "no"

  db:
    image: postgres:18.6-alpine
    healthcheck:
      test: ["CMD", "pg_isready", "-h", "127.0.0.1", "-U", "shop", "-d", "shop"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 60s
      start_interval: 1s

في الإعداد أعلاه لاحظ التالي:

  • مهمة الترحيل خدمة منفصلة تستخدم Image التطبيق نفسها بأمر مختلف، وسياستها restart: "no" لأنها يجب أن تعمل مرة وتنتهي، وال API لا يبدأ إلا بعد أن تنتهي بنجاح. وبهذا لا يحتاج كود ال API أن يعرف شيئاً عن إنشاء الجداول، ولا يتسابق عدة نسخ من ال API على الترحيل إذا شغلت أكثر من نسخة.
  • فحص قاعدة البيانات يحتوي على -h 127.0.0.1، وهذه التفصيلة الصغيرة هي موضوع القسم التالي.
  • start_period مهلة لا تحسب فيها الفحوص الفاشلة ضمن المحاولات retries، وstart_interval هو الفاصل بين الفحوص أثناء هذه المهلة. فقاعدة البيانات تفحص كل ثانية في أول دقيقة، ثم كل عشر ثوان بعد ذلك، فتعرف أنها جاهزة بسرعة دون أن يستهلك الفحص المعالج طوال اليوم.

عندما يقول الفحص «جاهز» قبل الأوان: pg_isready عبر ال Socket

الفحص الذي ستجده في أغلب الأمثلة على الإنترنت لقاعدة PostgreSQL هو pg_isready -U shop دون الخيار -h، ويبدو منطقياً. وأردنا أن نتأكد منه فشغلنا Container جديداً لقاعدة البيانات، وفحصناه من داخله كل 50 ميلي ثانية بطريقتين في الوقت نفسه: عبر ال Unix Socket كما يفعل الأمر دون -h، وعبر TCP على 127.0.0.1، وطبعنا كل تغير في النتيجة مع الوقت من بداية الفحص:

docker exec ct2-c-pgprobe sh -c 't0=$(cut -d" " -f1 /proc/uptime); p=""; for i in $(seq 1 400); do
  a=$(pg_isready -q -U shop; echo $?); b=$(pg_isready -q -U shop -h 127.0.0.1; echo $?)
  s="socket=$a tcp=$b"; if [ "$s" != "$p" ]; then echo "$(awk -v t0=$t0 "{printf \"%6.2f\", \$1-t0}" /proc/uptime)s $s"; p=$s; fi
  sleep 0.05; done'
  0.03s socket=2 tcp=2
  4.28s socket=1 tcp=2
  4.39s socket=0 tcp=2
  4.68s socket=1 tcp=2
  6.19s socket=2 tcp=2
  6.39s socket=1 tcp=1
  6.57s socket=0 tcp=0

ورموز الخروج من وثائق pg_isready: 0 يعني أن الخادم يقبل الاتصالات، و1 يعني أنه يرفضها، وغالباً لأنه يبدأ أو يتوقف، و2 يعني لا يوجد رد. والمخرج يقول إن الفحص عبر ال Socket أعطى 0، أي «جاهز»، في الثانية 4.39 لمدة ثلث ثانية تقريباً، بينما الفحص عبر TCP بقي 2 حتى الثانية 6.57. والسبب في سكربت التشغيل docker-entrypoint.sh نفسه، فالخادم المؤقت الذي يعمل أثناء التهيئة يبدأ بالخيار listen_addresses=''، أي أنه يستمع على ال Socket فقط ولا يستمع على أي عنوان شبكة، وذلك لكي لا يتصل به أحد من الخارج قبل أن تنتهي التهيئة. وال Socket داخل ال Container، فالفحص الذي يعمل داخل ال Container يراه، أما ال API الذي يتصل من Container آخر عبر الشبكة فلا يراه.

وثلث ثانية نافذة صغيرة، فهل هذه مشكلة حقيقية؟ تصبح كبيرة جداً عندما يكون عندك سكربت تهيئة في /docker-entrypoint-initdb.d، مثل ملف SQL يحمل بيانات أولية أو نسخة احتياطية، لأن هذه السكربتات تعمل كلها على الخادم المؤقت. لذلك أضفنا إلى التجربة سكربتاً يمثل تحميل نسخة احتياطية يأخذ ست ثوان:

-- Stands for loading a dump on first start: it takes a few seconds, and runs while the
-- entrypoint's temporary server listens on the Unix socket only.
SELECT pg_sleep(6);
CREATE TABLE IF NOT EXISTS seed_info (loaded_at timestamptz DEFAULT now());
INSERT INTO seed_info DEFAULT VALUES;

ثم شغلنا الملف النهائي مع ملف صغير يعيد الفحص إلى صيغته الشائعة دون -h، على Volume جديد:

docker compose -f compose.yaml -f compose.socketcheck.yaml up -d --wait
 Container ct2-c-shop-db-1 Started
 Container ct2-c-shop-db-1 Waiting
 Container ct2-c-shop-redis-1 Started
 Container ct2-c-shop-db-1 Healthy
 Container ct2-c-shop-migrate-1 Starting
 Container ct2-c-shop-migrate-1 Started
 Container ct2-c-shop-migrate-1 Error service "migrate" didn't complete successfully: exit 1
service "migrate" didn't complete successfully: exit 1

real	0m17.752s

أصبحت قاعدة البيانات Healthy، فبدأ الترحيل وانهار بالرسالة نفسها ECONNREFUSED، فلم يبدأ ال API أصلاً لأنه ينتظر الترحيل. وسجل الفحوص الذي يحفظه Docker لكل Container يبين ما حدث بالضبط:

docker inspect ct2-c-shop-db-1 --format '{{range .State.Health.Log}}{{.Start}} exit={{.ExitCode}} {{.Output}}{{end}}'
2026-11-18 15:57:29.931807576 +0000 UTC exit=2 /var/run/postgresql:5432 - no response
2026-11-18 15:57:31.370818912 +0000 UTC exit=2 /var/run/postgresql:5432 - no response
2026-11-18 15:57:32.634881227 +0000 UTC exit=2 /var/run/postgresql:5432 - no response
2026-11-18 15:57:33.817190374 +0000 UTC exit=0 /var/run/postgresql:5432 - accepting connections
2026-11-18 15:57:44.054260765 +0000 UTC exit=0 /var/run/postgresql:5432 - accepting connections

وسجل قاعدة البيانات يقول إنها بدأت تنفيذ سكربت التهيئة في 15:57:33.67، أي أن الفحص نجح في 15:57:33.82 أثناء السكربت، والفحص يكتب صراحة أنه يتحدث مع /var/run/postgresql:5432، وهو ال Socket. ثم بدأ الترحيل في 15:57:34.66 وانهار بعد ثانيتين، والخادم المؤقت ما زال يحمل البيانات ولا يستمع على الشبكة.

ثلاثة مسارات زمنية: مرحلة initdb ثم خادم مؤقت يستمع على Unix Socket فقط أثناء سكربت 01-seed.sql، والفحص عبر ال Socket ينجح أثناء السكربت، والفحص عبر 127.0.0.1 يبقى فاشلاً، وmigrate يبدأ بعد أن تصبح db سليمة وينهار برسالة ECONNREFUSED
الفحص الشائع نجح أثناء سكربت التهيئة لأن الخادم المؤقت يستمع على ال Socket فقط، فبدأ الترحيل وانهار

ثم أعدنا التشغيل على Volume جديد بالفحص الصحيح pg_isready -h 127.0.0.1 -U shop -d shop، فبقي الفحص يعطي 127.0.0.1:5432 - no response طوال السكربت، ولم ينجح إلا في 15:58:30.21، بعد أن كتبت قاعدة البيانات database system is ready to accept connections للخادم الحقيقي في 15:58:29.35، ثم بدأ الترحيل في 15:58:31.21 ونجح، ثم ال API، ثم web، وانتهى الأمر كله في 39.8 ثانية دون أي خطأ. والقاعدة من هذا القسم: افحص الخدمة بالطريقة نفسها التي يتصل بها من يعتمد عليها، فإذا كان ال API يتصل عبر TCP فالفحص يجب أن يكون عبر TCP، وإذا كان الفحص يمر بطريق مختصر لا يمر به المستخدم الحقيقي فهو يفحص شيئاً آخر.

⚠️
الشرط service_healthy يعمل عند البدء فقط. فإذا أعيد تشغيل قاعدة البيانات وحدها بعد ساعة، بسبب تحديث أو نفاد ذاكرة، فلن ينتظر ال API شيئاً، وسيفقد اتصاله ويحتاج أن يعيد الاتصال بنفسه. لذلك اكتب في التطبيق إعادة محاولة بفاصل متزايد Backoff عند فقد الاتصال، واعتبر شروط Compose طبقة إضافية لترتيب البدء وليست بديلاً عن ذلك.

كيف تكتب فحص صحة مفيداً؟

فحص الصحة أمر يشغله Docker داخل ال Container على فترات، فإذا خرج بالرمز 0 فالخدمة سليمة، وإذا فشل عدد retries مرات متتالية بعد انتهاء start_period أصبحت الخدمة Unhealthy. وهناك عدة أشياء تعلمناها من التجربة:

  • الأمر يجب أن يكون موجوداً داخل ال Image: Image من نوع Alpine فيها wget من BusyBox وليس فيها curl، لذلك استخدمنا wget -qO- في ال API وفي nginx. والفحص الذي يستدعي أمراً غير موجود يفشل دائماً، وتبقى الخدمة Unhealthy وأنت تبحث عن مشكلة في التطبيق.
  • الصيغة CMD وليس CMD-SHELL عندما لا تحتاج Shell: مع CMD يشغل Docker الأمر مباشرة، فلا تحتاج ال Image أن تحتوي على Shell، وهذا مهم في ال Images الصغيرة جداً.
  • الفحص يجب أن يفحص الاعتماديات المهمة: مسار /healthz في ال API ينفذ SELECT 1 على قاعدة البيانات، فإذا فقد ال API اتصاله بالقاعدة أصبح Unhealthy. ولا تجعله يفحص كل شيء، فإذا تعطلت خدمة خارجية ثانوية فلا يجب أن يعتبر ال API نفسه معطلاً.
  • بدون start_interval ينتظر الفحص الأول فترة كاملة: الخدمة web في التجربة ليس لها start_interval، ففحصها الأول كان بعد عشر ثوان من بدئها، وهذه عشر ثوان إضافية في كل نشر يضيعها الأمر up --wait في الانتظار.

ولاحظ أن Docker نفسه لا يفعل شيئاً عندما يصبح Container غير سليم، فلا يعيد تشغيله، وإنما يغير حالته فقط، والحالة تستخدمها أدوات أخرى: شروط depends_on، والأمر up --wait، وأدوات المراقبة. وقد رأينا في تحديث ال Containers بأمان كيف يعتبر Docker أي Container بدأ سليماً إذا لم يكن له فحص، فتعتبره أدوات التحديث ناجحاً وهو متوقف.

رسم لترتيب البدء: web ينتظر api بشرط service_healthy، وapi ينتظر redis وdb بشرط service_healthy وmigrate بشرط service_completed_successfully، وmigrate ينتظر db بشرط service_healthy، والأمر docker compose up -d --wait ينتظر السلسلة كلها
ترتيب البدء في الملف النهائي: كل سهم شرط، ولكل خدمة فحص يعرف ماذا تعني «جاهزة»

الأمر up --wait: انتظر حتى تعمل الخدمات فعلاً

الأمر docker compose up -d يعود بمجرد أن يبدأ ال Containers، كما رأينا في المسودة الأولى حين كتب Started لخدمة انهارت بعد ثلاث ثوان. أما الخيار --wait فيجعله ينتظر حتى تصبح كل الخدمات Running وHealthy، ويخرج برمز خطأ إذا لم يحدث ذلك، كما في وثائق docker compose up، ومعه --wait-timeout لتحديد المهلة. وهذا مخرج الأمر في أول تشغيل ناجح للملف النهائي، مختصراً:

 Container ct2-c-shop-db-1 Started
 Container ct2-c-shop-db-1 Waiting
 Container ct2-c-shop-db-1 Healthy
 Container ct2-c-shop-migrate-1 Starting
 Container ct2-c-shop-migrate-1 Started
 Container ct2-c-shop-redis-1 Healthy
 Container ct2-c-shop-migrate-1 Exited
 Container ct2-c-shop-api-1 Starting
 Container ct2-c-shop-api-1 Started
 Container ct2-c-shop-api-1 Waiting
 Container ct2-c-shop-api-1 Healthy
 Container ct2-c-shop-web-1 Starting
 Container ct2-c-shop-web-1 Started
 Container ct2-c-shop-web-1 Waiting
 Container ct2-c-shop-web-1 Healthy

real	1m10.712s

والترتيب في المخرج هو بالضبط الرسم أعلاه، ولاحظ السطر migrate-1 Exited، فالخروج هنا هو النجاح المطلوب. وفي خطوة النشر في خط CI هذا هو الأمر الذي تريده، لأن رمز خروجه يقول هل النشر نجح فعلاً، فتوقف الخط أو تتراجع إذا فشل، وقد رأينا في التجربة السابقة أنه خرج برمز 1 ورسالة واضحة عندما فشل الترحيل. أما الوقت فقد أخذ هذا التشغيل الأول 70 ثانية، والتشغيل التالي على قرص أقل انشغالاً 40 ثانية، لأن أول تهيئة لقاعدة البيانات تكتب ملفات كثيرة على القرص. وبعد أن تكون قاعدة البيانات مهيأة لا تتكرر هذه المرحلة، فيصبح التشغيل أسرع بكثير.

ثم تأكدنا أن التطبيق يعمل من خلال nginx:

curl -s localhost:8080/api/hits; curl -s localhost:8080/api/hits
{"db":1,"redis":1,"version":"1.0.0"}
{"db":2,"redis":2,"version":"1.0.0"}

المتغيرات والأسرار Environment Variables and Secrets

في ملف Compose ثلاثة أماكن مختلفة للقيم، وأسماؤها متشابهة، والخلط بينها من أكثر الأخطاء شيوعاً، لذلك نبدأ بالفرق بينها قبل أن نتحدث عن كلمات المرور.

ملف .env أم env_file؟

ملف .env في مجلد المشروع يقرؤه Compose نفسه لكي يعوض المتغيرات المكتوبة بالصيغة ${...} داخل ملف YAML، كما تشرح وثائق تعويض المتغيرات Interpolation، ولا يمرره إلى أي Container. أما env_file وenvironment في تعريف الخدمة فيضعان المتغيرات داخل ال Container، كما في وثائق ضبط متغيرات البيئة. وفي التجربة كان ملف .env كما يلي:

# Read by Compose itself for ${...} in the YAML; NOT passed into containers
APP_VERSION=1.0.0
WEB_PORT=8080

واستخدمناه في الملف لتحديد وسم ال Image والمنفذ:

    image: ct2-c-shop-api:${APP_VERSION:?set APP_VERSION in .env}
    ports:
      - "${WEB_PORT:-8080}:80"

ثم سألنا ال Container عن المتغير:

docker compose exec api sh -c 'echo WEB_PORT=[$WEB_PORT]'
WEB_PORT=[]

المتغير غير موجود داخل ال Container، لأن ملف .env للملف وليس للتطبيق. ولاحظ الصيغتين في الإعداد: ${WEB_PORT:-8080} تعني «استخدم 8080 إذا لم يكن المتغير موجوداً أو كان فارغاً»، و${APP_VERSION:?رسالة} تعني «توقف بهذه الرسالة إذا لم يكن موجوداً». والصيغة الثانية أفضل لكل قيمة لا يوجد لها افتراضي معقول، لأن البديل أن يكمل Compose بنص فارغ، كما سيأتي في قسم config.

وهناك ترتيب أولوية Precedence يفاجئ الناس: متغيرات ال Shell التي تشغل منها الأمر أقوى من ملف .env، كما في وثائق الأولوية. فإذا كان في جلستك على السيرفر متغير APP_VERSION قديم من تجربة سابقة، فسوف يستخدمه Compose ويتجاهل ما في الملف، وهذا ما رأيناه عندما شغلنا APP_VERSION=2.0.0 docker compose config، فظهر image: ct2-c-shop-api:2.0.0 رغم أن الملف يقول 1.0.0.

علامة $ في كلمة المرور

هذه مشكلة تصيب كثيرين مرة واحدة على الأقل. كلمة مرور قوية فيها رموز، ومنها علامة الدولار، وCompose يعتبر كل $ في الملف بداية متغير. فكتبنا ملفاً صغيراً فيه POSTGRES_PASSWORD: Xk9$tq2Lm وطلبنا من Compose أن يعرض ما فهمه:

level=warning msg="The \"tq2Lm\" variable is not set. Defaulting to a blank string."
      POSTGRES_PASSWORD: Xk9

كلمة المرور الفعلية أصبحت Xk9، ثلاثة أحرف، والتحذير سطر واحد بين عشرات الأسطر عند التشغيل لا ينتبه له أحد. والأسوأ أن قاعدة البيانات سوف تهيأ بهذه الكلمة القصيرة في أول تشغيل وتبقى بها. والحل أن تكتب $$ عندما تريد علامة دولار حرفية، أو الأفضل أن تخرج كلمات المرور من الملف كلياً إلى Secrets، فملفات ال Secrets لا يعوض Compose ما بداخلها.

الأسرار Secrets بدل متغيرات البيئة

في المسودة الأولى كانت كلمة المرور في متغيرات البيئة، وهذا ما يراه أي شخص أو برنامج يستطيع أن يسأل Docker عن ال Container:

docker inspect ct2-c-first-db-1 --format '{{range .Config.Env}}{{println .}}{{end}}' | grep POSTGRES
POSTGRES_USER=shop
POSTGRES_PASSWORD=s3cret-pass

ومتغيرات البيئة تتسرب من أماكن كثيرة: صفحات الأخطاء في بعض أطر العمل تعرضها، وأدوات المراقبة وتقارير الأعطال ترسلها، وكل عملية فرعية يشغلها التطبيق ترثها، وأي شخص له صلاحية على مقبس Docker أو يستخدم أداة إدارة مثل Portainer يقرؤها. أما Secrets في Compose فهي ملفات تقرأ منها الخدمة القيمة، كما في وثائق استخدام الأسرار:

services:
  api:
    environment:
      DB_PASSWORD_FILE: /run/secrets/db_password
    secrets: [db_password]
  db:
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets: [db_password]

secrets:
  db_password:
    file: ./secrets/db_password.txt

وصورة PostgreSQL الرسمية تدعم الصيغة _FILE لكل متغيراتها المهمة، كما في صفحتها على Docker Hub، وكثير من ال Images الرسمية تفعل الشيء نفسه، وتطبيقك يحتاج سطرين يقرآن الملف. وهذا ما يراه docker inspect الآن في ال API:

DB_HOST=db
DB_USER=shop
DB_NAME=shop
REDIS_URL=redis://redis:6379
DB_PASSWORD_FILE=/run/secrets/db_password
APP_VERSION=1.0.0
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
NODE_VERSION=24.21.0
YARN_VERSION=1.22.22

bind …\secrets\db_password.txt -> /run/secrets/db_password false

في المخرج أعلاه لاحظ التالي:

  • المتغيرات الأربعة الأولى من ملف api.env عبر env_file، وهي إعدادات وليست أسراراً، ولا مشكلة أن تظهر.
  • كلمة المرور لا تظهر، ويظهر فقط مسار الملف.
  • السطر الأخير من قائمة ال Mounts: ال Secret في Compose دون Swarm هو في الحقيقة Bind Mount لملف من السيرفر، والكلمة false تعني أنه للقراءة فقط داخل ال Container.

وهنا يجب أن نكون صريحين في حدود هذه الطريقة: هي لا تشفر شيئاً، فكلمة المرور في ملف نصي على السيرفر، ومن يدخل ال Container يقرؤها من /run/secrets. وما تكسبه هو أنها لا تظهر في docker inspect ولا في متغيرات البيئة الموروثة ولا في ملف Compose الذي يذهب إلى Git. لذلك ضع مجلد secrets/ في .gitignore، واجعل صلاحيات الملف على السيرفر لصاحبه فقط، وأنشئ القيمة عشوائياً بدل أن تكتبها بيدك:

mkdir -p secrets && openssl rand -base64 24 > secrets/db_password.txt && chmod 600 secrets/db_password.txt

ولاحظ أن ال Container يقرأ الملف بالمستخدم الذي يعمل به، وnode في حالة ال API، فعلى سيرفر Linux يجب أن تسمح صلاحيات الملف لهذا المستخدم بالقراءة، أو تعطي الملف لمعرف المستخدم نفسه. وإذا أردت أن تعرف كيف تكتشف كلمة مرور وصلت إلى Git رغم كل هذا فقد شرحنا ذلك في اكتشاف الأسرار المسربة.

ثلاثة أعمدة: ملف .env يقرؤه Compose فقط ولا يدخل ال Container، وenv_file وenvironment تدخل ال Container وتظهر في docker inspect، وsecrets ملف للقراءة فقط في /run/secrets يظهر مساره فقط في inspect
كل مكان للقيم له جمهور مختلف، وكلمات المرور مكانها العمود الأيسر

الخدمات الاختيارية Profiles

في أغلب المشاريع خدمات لا تريدها أن تعمل دائماً: أداة لإدارة قاعدة البيانات، أو Container لتشغيل أوامر psql، أو خدمة تحاكي البريد في التطوير، أو مهمة تحميل بيانات تجريبية. والطريقة القديمة كانت ملفاً ثانياً أو تعليق الخدمة بعلامة #، والطريقة الأنظف هي الملفات الشخصية Profiles، كما في وثائق Profiles: الخدمة التي لها profiles لا تبدأ مع docker compose up إلا إذا فعلت الملف الشخصي الخاص بها. وفي التجربة أضفنا خدمة psql في الملف الشخصي tools:

  psql:
    image: postgres:18.6-alpine
    profiles: [tools]
    environment:
      PGHOST: db
      PGUSER: shop
      PGDATABASE: shop
    secrets: [db_password]
    networks: [backend]
    entrypoint: ["sh", "-c", "PGPASSWORD=\"$$(cat /run/secrets/db_password)\" exec psql \"$$@\"", "psql"]

ومع أن الملف فيه خمس خدمات وخدمة سادسة اختيارية، فهذا ما يعرضه Compose عند التشغيل العادي:

docker compose ps --services
api
db
redis
web

ولم تظهر psql لأنها في ملف شخصي غير مفعل، ولم يظهر migrate لأنه انتهى، وps يعرض العامل فقط إلا مع الخيار -a. ثم شغلناها مرة واحدة:

docker compose run --rm -T psql -c 'select count(*) from visits'
 count
-------
     0
(1 row)

ولاحظ أننا لم نكتب --profile tools، لأن docker compose run على خدمة بالاسم يفعل ملفها الشخصي تلقائياً، أما up فيحتاج --profile tools أو المتغير COMPOSE_PROFILES=tools. والجدول فارغ لأن هذا كان بعد تشغيل جديد على Volume جديد.

وفي هذه الخدمة واجهنا مشكلة حقيقية. فالمحاولة الأولى استخدمت ملف كلمات المرور الخاص ب PostgreSQL، وهو ملف pgpass، في Secret إضافي، وهي الطريقة الموثقة لإعطاء psql كلمة مرور دون متغيرات، فكانت النتيجة:

WARNING: password file "/run/secrets/pgpass" has group or world access; permissions should be u=rw (0600) or less
Password for user shop:
psql: error: connection to server at "db" (172.24.0.2), port 5432 failed: fe_sendauth: no password supplied

تقول وثائق ملف pgpass إن مكتبة libpq تتجاهل هذا الملف إذا كانت صلاحياته تسمح للمجموعة أو للآخرين بالقراءة، وال Secret في Compose يأتي بصلاحيات الملف الأصلي على السيرفر، وكانت في تجربتنا -rwxrwxrwx لأن الملف على قرص Windows، فتجاهل psql الملف وطلب كلمة المرور من لوحة المفاتيح، ولا توجد لوحة مفاتيح، فانتظر ثم فشل. وعلى سيرفر Linux بصلاحية 600 كان سيعمل، ولكن ذلك يجعل الخدمة تعمل على سيرفر وتفشل على آخر بسبب صلاحيات ملف. لذلك غيرنا الطريقة إلى ما تراه في الإعداد أعلاه: نقطة دخول Entrypoint صغيرة تقرأ ال Secret وتضعه في المتغير PGPASSWORD لعملية psql وحدها ثم تشغلها بالأمر exec، والمتغير لا يظهر في docker inspect لأنه لم يكن في تعريف ال Container. ولاحظ $$ في الإعداد، فهي علامة دولار حرفية تصل إلى ال Shell داخل ال Container، ولو كتبناها $ لعوضها Compose بنص فارغ كما رأينا قبل قليل.

البيانات في Named Volumes، واسم المشروع

قاعدة البيانات وRedis يحفظان بياناتهما في Named Volumes، وهي Volumes يديرها Docker ولها اسم، وتعيش أطول من ال Containers. وقد خصصنا لموضوع ال Volumes وال Bind Mounts والنسخ الاحتياطي مقالاً مستقلاً في هذه المرحلة، لذلك نكتفي هنا بما يخص ملف Compose. فالأمر docker compose down يحذف ال Containers والشبكات ويبقي ال Volumes، وdown -v يحذف ال Volumes أيضاً، وهذا الفرق بين حرفين هو الفرق بين إعادة تشغيل عادية وفقد قاعدة البيانات كلها. وفي التجربة:

curl -s localhost:8080/api/hits
docker compose down
docker volume ls --filter label=com.docker.compose.project=ct2-c-shop
docker compose up -d --wait
curl -s localhost:8080/api/hits
{"db":5,"redis":5,"version":"1.0.0"}
DRIVER    VOLUME NAME
local     ct2-c-shop_pgdata
local     ct2-c-shop_redisdata
{"db":6,"redis":6,"version":"1.0.0"}

العدادان أكملا من 5 إلى 6 بعد down ثم up، لأن ال Volumes بقيت. ولاحظ اسم كل Volume: ct2-c-shop_pgdata، أي اسم المشروع ثم شرطة سفلية ثم الاسم في الملف. واسم المشروع يأتي من المفتاح name: في أول الملف إذا وجد، وإلا من اسم المجلد، ويغيره الخيار -p، كما في وثائق اسم المشروع. فماذا يحدث إذا شغل أحدهم الملف نفسه باسم مشروع آخر؟ سألنا Compose:

docker compose -p ct2-c-shop2 config
volumes:
  pgdata:
    name: ct2-c-shop2_pgdata
  redisdata:
    name: ct2-c-shop2_redisdata

Volumes جديدة فارغة، أي قاعدة بيانات جديدة فارغة، وتطبيق يعمل وكأنه أول يوم، وبياناتك الحقيقية في Volume آخر لا يستخدمه أحد. وهذا يحدث فعلاً عندما ينقل أحدهم مجلد المشروع إلى اسم آخر على السيرفر ولا يوجد name: في الملف. لذلك اكتب name: في أول كل ملف Compose يعمل على سيرفر، ولا تستخدم -p على السيرفر إلا إذا كنت تعرف لماذا. وإذا أردت أن تنقل المشروع كله إلى سيرفر آخر مع بياناته فقد شرحنا ذلك في نقل Containers إلى خادم جديد.

عزل الشبكات Network Isolation

شرحنا أنواع الشبكات وكيف يربط Compose الخدمات ومتى تنشر منفذاً في شبكات Docker وأفضل الممارسات، فلن نعيد ذلك هنا، وإنما نطبق قاعدة واحدة منه: كل خدمة على الشبكات التي تحتاجها فقط. والملف النهائي فيه شبكتان: frontend عليها nginx وال API، وbackend عليها ال API وقاعدة البيانات وRedis ومهمة الترحيل، وbackend داخلية بالخيار internal: true، أي أنها لا تتصل بالإنترنت أصلاً، كما في مرجع الشبكات في Compose:

networks:
  frontend:
  backend:
    internal: true

ثم اختبرنا العزل من داخل ال Containers:

docker compose exec web nc -zv -w 2 db 5432
docker compose exec api nc -zv -w 2 db 5432
docker compose exec redis wget -q -T 3 -O /dev/null https://deb.debian.org/
docker compose exec api wget -q -T 5 -O /dev/null https://deb.debian.org/
--- web -> db
nc: bad address 'db'
exit=1
--- api -> db
db (172.24.0.2:5432) open
exit=0
--- redis -> internet
wget: bad address 'deb.debian.org'
exit=1
--- api -> internet
exit=0

في المخرج أعلاه لاحظ التالي:

  • nginx لا يعرف حتى اسم db، لأن ال DNS الداخلي يجيب فقط عن الخدمات على الشبكات المشتركة. فإذا وجد أحدهم ثغرة في nginx فلن يصل منه إلى قاعدة البيانات مباشرة.
  • Redis لا يستطيع الوصول إلى الإنترنت، فلو اخترقت خدمة على الشبكة الداخلية فلن ترسل البيانات إلى الخارج ولن تنزل أدوات، وهذا قيد حقيقي على المهاجم.
  • ال API يصل إلى الاثنين لأنه على الشبكتين، وهو الوحيد الذي يحتاج ذلك.
شبكتان: frontend فيها web والإنترنت، وbackend الداخلية فيها db وredis وmigrate، وال API على الاثنتين، مع نتائج التجربة: web لا يجد db وredis لا يصل إلى deb.debian.org
ال API الخدمة الوحيدة على الشبكتين، والشبكة الداخلية لا تصل إلى الإنترنت

وللشبكة الداخلية أثر جانبي واجهناه في التجربة. فملف التطوير الذي سنشرحه بعد قليل ينشر منفذ قاعدة البيانات 5432 لكي يتصل بها المطور من برنامج على جهازه، وبعد التشغيل كان هذا ما يعرضه Docker:

SERVICE   PORTS
api       0.0.0.0:3000->3000/tcp, [::]:3000->3000/tcp
db        5432/tcp
redis     6379/tcp
web       0.0.0.0:8080->80/tcp, [::]:8080->80/tcp

المنفذ لم ينشر، والأمر docker port لم يطبع شيئاً، بينما docker inspect يبين أن الطلب موجود في PortBindings وأن النتيجة في NetworkSettings.Ports قائمة فارغة، ولم يظهر أي خطأ. والسبب أن ال Container الذي يكون على شبكة داخلية فقط لا يمكن أن ينشر منفذاً، فالنشر يمر بالشبكة التي تصل إلى خارج السيرفر، والشبكة الداخلية مصممة لكي لا تصل. وهذا في الإنتاج ميزة، فلو أضاف أحدهم منفذاً لقاعدة البيانات بالخطأ فلن يصل إليها أحد، وفي التطوير مفاجأة تضيع نصف ساعة. والحل الذي اخترناه أن يجعل ملف التطوير وحده الشبكة غير داخلية:

networks:
  backend:
    internal: false        # in development only: lets the published db port work

وهنا واجهنا مشكلة ثانية: بعد تغيير إعداد الشبكة شغلنا up -d --wait، فأعاد Compose إنشاء الشبكة، ولكن مهمة الترحيل فشلت برسالة getaddrinfo EAI_AGAIN db، أي أنها لم تجد اسم قاعدة البيانات. فالشبكة الجديدة أنشئت، ولكن بعض ال Containers ما زالت تحمل أثر الشبكة القديمة. وبعد docker compose down ثم up -d --wait عمل كل شيء، وظهر المنفذ 0.0.0.0:5432->5432/tcp. لذلك عندما تغير إعدادات شبكة في ملف Compose أوقف المشروع بالأمر down ثم شغله من جديد، ولا تعتمد على up وحده.

حدود الموارد Resource Limits

Container دون حد للذاكرة يستطيع أن يأخذ ذاكرة السيرفر كلها، فإذا كان في ال API تسرب ذاكرة Memory Leak أو طلب غير متوقع يحمل ملفاً كبيراً، فلن يتوقف ال API وحده، وإنما سيبدأ نظام التشغيل بقتل العمليات حتى يجد ذاكرة، وقد تكون قاعدة البيانات من بينها. والحد يكتب في Compose هكذا:

    deploy:
      resources:
        limits:
          memory: 128M
          cpus: "0.50"

وكان هذا القسم في الإصدارات القديمة يعمل مع Swarm فقط، أما Compose الحالي فيطبقه على السيرفر الواحد، كما في مرجع deploy، وdocker inspect أكده: Memory=134217728 NanoCpus=500000000، أي 128 ميجابايت ونصف معالج. ثم أرسلنا طلبات إلى المسار الذي يحجز 50 ميجابايت في كل مرة، ونحن نتوقع أن يتوقف ال API عند الطلب الثالث:

holding 50 MB
holding 100 MB
holding 150 MB
OOMKilled=false ExitCode=0 RestartCount=0 Status=running

150 ميجابايت محجوزة وال API يعمل والحد 128. وأظهر docker stats استهلاك 125.2MiB / 128MiB، أي أن ال Container لم يتجاوز الحد في الذاكرة الحقيقية، فأين ذهب الباقي؟ الإجابة في سطر واحد من docker inspect:

Memory=134217728 MemorySwap=268435456 NanoCpus=500000000

الحد الكلي للذاكرة مع ال Swap هو 256 ميجابايت، أي ضعف الحد الذي كتبناه. وتقول وثائق قيود الموارد إنك إذا حددت الذاكرة ولم تحدد حد ال Swap فإن ال Container يستطيع أن يستخدم من ال Swap بقدر حد الذاكرة نفسه، إذا كان في السيرفر Swap. فالذي حدث أن الجزء الزائد نقل إلى ال Swap على القرص، وهذا أسوأ من التوقف في حالات كثيرة، لأن التطبيق يبقى يعمل ولكن ببطء شديد، والفحص قد يبقى ناجحاً، ولا ينبهك شيء. ثم أرسلنا طلبات أخرى:

holding 200 MB
<head><title>502 Bad Gateway</title></head>
<head><title>502 Bad Gateway</title></head>

وسجل أحداث Docker لل Container:

docker events --since 3m --until 0s --filter container=ct2-c-shop-api-1 --filter event=oom --filter event=die --filter event=start
1795017856 oom <no value>
1795017863 die 137
1795017875 start <no value>

في المخرج أعلاه لاحظ التالي:

  • الحدث oom يعني أن نواة Linux قتلت العملية لأنها تجاوزت حدها، وهذا يسمى OOM Killer، والقتل كان داخل ال Container فقط، ولم يمس قاعدة البيانات ولا أي شيء آخر على السيرفر، وهذا هو الهدف من الحد.
  • رمز الخروج 137 هو 128 مضافاً إليه 9، أي أن العملية انتهت بالإشارة SIGKILL، وهو الرمز الذي ستراه في كل حالة OOM.
  • سياسة إعادة التشغيل أعادت ال API، وأصبح RestartCount=1، ولكن nginx أعاد للزوار 502 في الفترة بين القتل والبدء، فالحد يحمي السيرفر ولا يحمي الزوار.

والحل أن تجعل حد ال Swap مساوياً لحد الذاكرة، فلا يبقى للContainer أي Swap:

    deploy:
      resources:
        limits:
          memory: 128M
          cpus: "0.50"
    memswap_limit: 128M        # same as the memory limit: no swap on top of it

وبعد إعادة الإنشاء أصبح MemorySwap=134217728، وفي التجربة نفسها رد ال API على الطلب الأول بنجاح، ثم قتل عند الطلب الثاني بالحدث oom ورمز الخروج 137، أي عند 100 ميجابايت محجوزة فوق ما يستخدمه Node.js نفسه، وهذا ما كنا نتوقعه من حد 128. ولاحظ أيضاً في سجل الأحداث عند إعادة الإنشاء هذا التسلسل: kill ثم stop ثم die 0، فقد أرسل Compose الإشارة SIGTERM، وأغلق ال API اتصالاته وخرج بالرمز 0، ولم يحتج Docker أن ينتظر المهلة stop_grace_period ثم يقتله.

رسم أعمدة من التجربة: دون memswap_limit حجز التطبيق 50 ثم 100 ثم 150 ثم 200 ميجابايت رغم حد 128M لأن MemorySwap كانت 256M ثم قتل بالرمز 137، ومع memswap_limit مساوياً 128M قتل عند الطلب الثاني
حد الذاكرة وحده يسمح بمثله من ال Swap، ومع memswap_limit يصبح الحد حداً فعلاً

أما حد المعالج cpus فلا يقتل أحداً، وإنما يبطئ ال Container عندما يحاول أن يأخذ أكثر من حصته، وهذا مناسب للخدمات التي قد تستهلك المعالج كله في عملية ثقيلة فتجعل الخدمات الأخرى بطيئة. وكيف تختار الأرقام؟ شغل التطبيق تحت ضغط Load يشبه الحقيقي وراقب docker stats، ثم ضع الحد فوق أعلى استهلاك رأيته بهامش معقول، مرة ونصفاً مثلاً، لأن الحد المنخفض جداً يحول كل ارتفاع مفاجئ Spike عادي إلى توقف. وقد شرحنا كيف تقيس ما يحتاجه السيرفر كله في تخطيط السعة Capacity Planning.

وهناك مورد ثالث ينساه الجميع حتى يمتلئ القرص، وهو السجلات Logs. فقد شرحنا في دليل التثبيت كيف تضبط تدوير السجلات للمحرك كله، ويمكنك أيضاً أن تضبطه في الملف نفسه لكل خدمة. ولكي لا تكرر الإعداد نفسه خمس مرات استخدمنا مفتاحاً إضافياً يبدأ ب x-، وهو مفتاح يتجاهله Compose كخدمة، مع مرساة YAML Anchor، كما في وثائق Fragments ووثائق Extensions:

x-logging: &logging
  driver: local
  options:
    max-size: "10m"
    max-file: "3"

services:
  web:
    logging: *logging

سياسات إعادة التشغيل Restart Policies

سياسة إعادة التشغيل تقول ل Docker ماذا يفعل عندما يتوقف ال Container، وتطبق أيضاً عند إعادة تشغيل Docker نفسه أو السيرفر، كما في وثائق التشغيل التلقائي:

السياسةمتى يعيد التشغيلمناسبة لـ
noأبداً، وهي الافتراضيةمهام تعمل مرة واحدة مثل الترحيل
on-failure[:N]عند الخروج برمز غير 0، وبحد أقصى N محاولة إذا كتبتهمهام قد تفشل لسبب مؤقت
alwaysدائماً، حتى لو أوقفته بيدك فسوف يبدأ بعد إعادة تشغيل Dockerخدمات يجب أن تعمل مهما حدث
unless-stoppedدائماً، إلا إذا أوقفته بيدك فيبقى متوقفاً بعد إعادة التشغيلأغلب الخدمات الطويلة

ولكي نرى ماذا يحدث عندما يكون الخطأ دائماً وليس مؤقتاً، شغلنا ال API باسم قاعدة بيانات خاطئ، مع سياسته العادية unless-stopped، وسألنا Docker كل خمس ثوان:

t=5s RestartCount=1 Status=running ExitCode=0
t=10s RestartCount=3 Status=running ExitCode=0
t=15s RestartCount=4 Status=running ExitCode=0
t=20s RestartCount=5 Status=running ExitCode=0
t=25s RestartCount=6 Status=restarting ExitCode=1
t=30s RestartCount=6 Status=running ExitCode=0
t=35s RestartCount=7 Status=restarting ExitCode=1
t=40s RestartCount=7 Status=running ExitCode=0
t=45s RestartCount=8 Status=restarting ExitCode=1
t=50s RestartCount=8 Status=restarting ExitCode=1
t=55s RestartCount=8 Status=running ExitCode=0

في المخرج أعلاه لاحظ التالي:

  • في أول عشر ثوان ثلاث محاولات، ثم صارت المسافة بين المحاولات تكبر، فبين المحاولة السادسة والثامنة عشرون ثانية تقريباً، لأن Docker يضاعف الانتظار بين المحاولات لكي لا يستهلك السيرفر في حلقة سريعة.
  • الحالة تتنقل بين running وrestarting، فمن يشغل docker ps في اللحظة المناسبة يرى Up 2 seconds ويظن أن ال Container يعمل، والرقم الذي يكشف الحقيقة هو RestartCount.
  • بعد دقيقة ونصف تقريباً وصل العدد إلى 10، وفي السجل عشر نسخ من السطر نفسه error: database "shop_typo" does not exist، والسياسة لن تتوقف أبداً لأن الخطأ لن يصلح نفسه.

ثم غيرنا السياسة إلى on-failure:3، فبعد ثلاث محاولات توقف ال Container وبقي متوقفاً:

RestartCount=3 Status=exited ExitCode=1
Exited (1) 30 seconds ago

وأيهما أفضل؟ لخدمة طويلة مثل ال API نبقى على unless-stopped، لأن أغلب أسباب التوقف في الإنتاج مؤقتة: قاعدة بيانات أعيد تشغيلها، أو نفاد ذاكرة لمرة واحدة كما رأينا، والسياسة التي تتوقف بعد ثلاث محاولات قد تترك الخدمة متوقفة طوال الليل بسبب عطل استمر دقيقة. ولكن هذا يعني أن مراقبة RestartCount أو عدد مرات إعادة التشغيل في أداة المراقبة ضرورية، لأن الحلقة لا تتوقف وحدها. أما مهمة الترحيل فسياستها "no"، لأن ترحيلاً فشل يجب أن يوقف النشر وينتظر إنساناً، وليس أن يعاد عشر مرات على قاعدة بيانات في حالة غير معروفة. ولاحظ علامات التنصيص حول "no"، فبدونها يقرأ YAML الكلمة كقيمة منطقية false.

docker compose config: راجع الملف كما يراه Compose

الأمر docker compose config يقرأ كل ملفات المشروع، ويعوض المتغيرات، ويدمج الملفات الإضافية، ويتحقق من الصيغة، ثم يطبع الملف النهائي الذي سيعمل به Compose فعلاً، كما في وثائق الأمر. ومع الخيار -q يتحقق فقط ويخرج برمز خطأ إذا وجد مشكلة. وهذه ثلاث مشكلات حقيقية أمسكها في التجربة قبل أن تصل إلى السيرفر. الأولى متغير مطلوب فارغ:

APP_VERSION= docker compose config -q
error while interpolating services.api.image: required variable APP_VERSION is missing a value: set APP_VERSION in .env
exit=1

وهذا ما تكسبه من الصيغة ${APP_VERSION:?...}، فلولاها لكان الوسم فارغاً، ولظهرت رسالة غامضة عن اسم Image غير صالح في مكان آخر. والثانية خطأ إملائي في شرط الانتظار، كتبنا فيه service_completed بدل service_completed_successfully:

validating …\compose.typo.yaml: services.api.depends_on.migrate.condition value must be one of 'service_started', 'service_healthy', 'service_completed_successfully'
exit=1

والثالثة علامة الدولار في كلمة المرور التي رأيناها في قسم المتغيرات، وهي أخطرها لأنها تحذير وليست خطأ، فالأمر ينجح ويطبع POSTGRES_PASSWORD: Xk9، ولا يكتشفها إلا من يقرأ التحذيرات. لذلك ضع docker compose config -q خطوة في خط CI قبل النشر، كما في Gitea Actions، واجعل الخط يفشل إذا ظهرت كلمة warning في المخرج، لأن تحذيرات Compose في الغالب أخطاء لم تظهر بعد.

ويفيد الأمر أيضاً عندما تريد أن تعرف ما الذي سيتغير بعد دمج عدة ملفات، وهذا موضوع القسم التالي.

ملفات التطوير والإنتاج Overrides

التطوير يحتاج أشياء لا يحتاجها الإنتاج: منفذ مفتوح لل API لكي تختبره مباشرة، ومنفذ لقاعدة البيانات لبرنامج على جهازك، ومراقبة الملفات، وسجلات أكثر تفصيلاً. والإنتاج يحتاج أشياء أخرى: منافذ على 127.0.0.1 فقط خلف Reverse Proxy، وحدود موارد أكبر، وعدم البناء على السيرفر. والطريقة التي يقترحها Compose هي ملف أساسي مشترك وملفات إضافية تدمج فوقه، كما في وثائق دمج الملفات. وإذا وجد Compose ملفاً اسمه compose.override.yaml بجانب compose.yaml فإنه يدمجه تلقائياً دون أن تطلب، وهذا ملف التطوير في التجربة:

# Developer settings. `docker compose up` loads this file automatically when it sits next to compose.yaml.
services:
  api:
    ports:
      - "3000:3000"          # call the API directly, without nginx
    environment:
      LOG_LEVEL: debug
    develop:
      watch:
        - action: sync+restart
          path: ./api
          target: /app
          ignore:
            - node_modules/
            - package.json
        - action: rebuild
          path: ./api/package.json
  db:
    ports:
      - "5432:5432"          # for a desktop SQL client

networks:
  backend:
    internal: false        # in development only: lets the published db port work

وهذا ملف الإنتاج، ولا يدمج إلا إذا ذكرته بالخيار -f:

# Production: docker compose -f compose.yaml -f compose.prod.yaml up -d --wait
services:
  web:
    ports: !override
      - "127.0.0.1:8080:80"   # only the reverse proxy on this server reaches it
  api:
    build: !reset null        # the server never builds; CI pushes the image
    restart: always
    deploy:
      resources:
        limits:
          memory: 256M
          cpus: "1.0"

في الإعداد أعلاه لاحظ التالي:

  • قواعد الدمج ليست واحدة لكل المفاتيح، فالقيم المفردة مثل restart تستبدل، أما القوائم مثل ports فتضاف إلى بعضها، فلو كتبنا المنفذ في ملف الإنتاج دون !override لأصبح لل web منفذان: 8080:80 على كل العناوين من الملف الأساسي و127.0.0.1:8080:80، وهذا ليس ما نريده. والعلامة !override تستبدل القائمة كلها، و!reset تحذف المفتاح، كما في مرجع الدمج.
  • build: !reset null يحذف تعريف البناء في الإنتاج، فلا يستطيع أحد أن يبني Image على السيرفر من كود قد يكون مختلفاً عما اختبره خط CI.

والآن المفاجأة. سألنا Compose عن المنافذ في الحالتين، بالأمر docker compose config --format json مرة دون -f ومرة مع ملف الإنتاج، وطبعنا المنافذ فقط:

--- default (override auto-loaded)
api [":3000->3000"]
db [":5432->5432"]
web [":8080->80"]
--- -f compose.yaml -f compose.prod.yaml
api build: none restart: always mem: 268435456
web ["127.0.0.1:8080->80"]

الأمر نفسه docker compose up -d الذي يكتبه المطور كل يوم، إذا كتبه أحدهم على السيرفر وكان ملف compose.override.yaml هناك، لأن المستودع كله نسخ إلى السيرفر مثلاً، فسوف ينشر ال API على المنفذ 3000 وقاعدة البيانات على 5432 لكل عناوين السيرفر، وتذكر أن Docker يتجاوز جدار الحماية ufw كما شرحنا في دليل التثبيت، فهذه منافذ مفتوحة للإنترنت فعلاً. ولا يوجد أي تحذير، لأن Compose فعل بالضبط ما صمم له.

ملف compose.yaml يتفرع إلى compose.override.yaml الذي يحمل تلقائياً فينتج api على 0.0.0.0:3000 وdb على 0.0.0.0:5432 وweb على 0.0.0.0:8080، وإلى compose.prod.yaml الذي يحمل بالخيار -f فقط فينتج web على 127.0.0.1:8080 وapi دون build
الملف الأساسي نفسه بنتيجتين: الأمر القصير يحمل ملف التطوير، وملف الإنتاج لا يحمل إلا إذا ذكرته

وهناك عدة طرق لتجنب ذلك، ويمكن أن تجمعها:

  • لا تنسخ ملف compose.override.yaml إلى السيرفر أصلاً، فإذا كان النشر بأداة أو خط CI فانسخ الملفات التي يحتاجها الإنتاج فقط.
  • اختر لملف التطوير اسماً لا يحمل تلقائياً، مثل compose.dev.yaml، واجعل المطورين يكتبون -f أو يضعونه في متغير COMPOSE_FILE على أجهزتهم.
  • على السيرفر ضع في ملف .env السطر COMPOSE_FILE=compose.yaml:compose.prod.yaml، فيستخدم الأمر القصير ملفي الإنتاج دائماً، كما في وثائق متغيرات Compose. والفاصل بين الملفين نقطتان على Linux.
  • تحقق بعد كل نشر بالأمر docker compose ps من عمود المنافذ، أو أضف فحصاً في خط النشر يفشل إذا ظهر 0.0.0.0 لخدمة غير ال Reverse Proxy.

وتشرح وثائق Compose في الإنتاج النمط نفسه: ملف أساسي وملف إنتاج يذكر صراحة.

وضع المراقبة Compose Watch للتطوير

في التطوير تريد أن ترى التغيير بعد أن تحفظ الملف مباشرة، والطريقة القديمة كانت Bind Mount لمجلد الكود كله داخل ال Container، ولها مشكلات معروفة: مجلد node_modules من جهازك يغطي المجلد الذي داخل ال Container وقد يكون لنظام تشغيل آخر، وصلاحيات الملفات تختلف، والأداء على Docker Desktop أبطأ. أما وضع المراقبة Watch فيراقب الملفات على جهازك وينفذ إجراءً عندما تتغير، كما في وثائق Compose Watch ومرجع develop. والإجراءات الأساسية ثلاثة: sync ينسخ الملف المتغير إلى ال Container، وsync+restart ينسخ ثم يعيد تشغيل الخدمة، وrebuild يعيد بناء ال Image وإنشاء ال Container. وفي ملف التطوير أعلاه جعلنا تغيير ملفات JavaScript ينسخ ويعيد التشغيل، لأن Node.js لا يعيد تحميل الكود وحده، وجعلنا تغيير package.json يعيد البناء، لأن الاعتماديات تثبت أثناء البناء. ثم شغلنا المراقبة وعدلنا سطر الرسالة في server.js:

docker compose watch --no-up
Watch enabled
Syncing service "api" after 2 changes were detected
 Container ct2-c-shop-api-1 Restarting
 Container ct2-c-shop-api-1 Started
service(s) ["api"] restarted

وسجل ال API:

api-1  | api: SIGTERM, closing
api-1  | api: connected to postgres and redis in 209 ms, version 1.0.0 (watch edit)
api-1  | api: listening on :3000

في المخرج أعلاه لاحظ التالي:

  • «2 changes» لتغيير واحد في ملف واحد، لأن المحرر الذي استخدمناه يكتب ملفاً مؤقتاً ثم يعيد تسميته، فرأت المراقبة حدثين، ولا مشكلة في ذلك لأن Compose يجمع التغييرات المتقاربة في عملية واحدة.
  • ال API استقبل SIGTERM وأغلق اتصالاته، ثم بدأ بالكود الجديد، والدورة كلها أقل من ثانيتين.
  • الخيار --no-up لأن المشروع كان يعمل، ودونه يبدأ الأمر الخدمات أولاً.

ثم غيرنا رقم الإصدار في package.json، فبدأ إعادة البناء:

Rebuilding service(s) ["api"] after changes were detected...
 Image ct2-c-shop-api:1.0.0 Building
#8 [3/5] COPY package.json ./
#9 [4/5] RUN npm install --omit=dev --no-audit --no-fund
#9 19.44 added 20 packages in 17s
 Image ct2-c-shop-api:1.0.0 Built
service(s) ["api"] successfully built
 Container ct2-c-shop-migrate-1 Recreate
 Container ct2-c-shop-migrate-1 Recreated
 Container ct2-c-shop-api-1 Recreate
 Container ct2-c-shop-api-1 Recreated
 Container ct2-c-shop-api-1 Starting
 Container ct2-c-shop-api-1 Started
 Container ct2-c-shop-api-1 Waiting
 Container ct2-c-shop-api-1 Healthy 

إعادة البناء أخذت وقتاً أطول بكثير من النسخ، لأن تغيير package.json يلغي ال Cache لكل الطبقات بعده، فيعيد npm install تنزيل الاعتماديات كلها، وأعيد إنشاء migrate أيضاً لأنه يستخدم ال Image نفسها. ولهذا السبب فصلنا المسارين، فتغيير الكود اليومي ثانيتان، وتغيير الاعتماديات النادر عشرات الثواني. وواجهنا هنا مشكلة صغيرة تستحق الذكر: في المحاولة الأولى شغلنا المراقبة بمهلة محددة بالأمر timeout، وكان البناء على قرص مشغول أطول من المهلة، فانتهت العملية برسالة Build failed. Error: failed to execute bake: exit status 143، والرمز 143 يعني أن العملية استقبلت SIGTERM، أي أن المهلة قتلتها وليس خطأ في البناء. فإذا رأيت هذا الرمز في خط CI فابحث عن مهلة الخطوة قبل أن تبحث في ال Dockerfile.

والمراقبة أداة تطوير فقط، ولذلك مكانها ملف التطوير وليس الملف الأساسي، وقد بنينا بيئة تطوير محلية كاملة بملف Compose واحد في بيئة تطوير محلية بملف Docker Compose واحد.

الملف النهائي كاملاً

وهذا الملف الأساسي بعد كل ما سبق، كما عمل في التجربة:

name: ct2-c-shop

x-logging: &logging
  driver: local
  options:
    max-size: "10m"
    max-file: "3"

services:
  web:
    image: nginx:1.29.8-alpine
    ports:
      - "${WEB_PORT:-8080}:80"
    volumes:
      - ./web/index.html:/usr/share/nginx/html/index.html:ro
      - ./web/default.conf:/etc/nginx/conf.d/default.conf:ro
    networks: [frontend]
    depends_on:
      api:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://127.0.0.1/"]
      interval: 10s
      timeout: 3s
      retries: 3
    restart: unless-stopped
    logging: *logging

  api:
    build: ./api
    image: ct2-c-shop-api:${APP_VERSION:?set APP_VERSION in .env}
    env_file: api.env
    environment:
      APP_VERSION: ${APP_VERSION}
      DB_PASSWORD_FILE: /run/secrets/db_password
    secrets: [db_password]
    networks: [frontend, backend]
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
      migrate:
        condition: service_completed_successfully
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:3000/healthz"]
      interval: 10s
      timeout: 3s
      retries: 3
      start_period: 10s
      start_interval: 1s
    restart: unless-stopped
    stop_grace_period: 10s
    deploy:
      resources:
        limits:
          memory: 128M
          cpus: "0.50"
    memswap_limit: 128M        # same as the memory limit: no swap on top of it
    logging: *logging

  migrate:
    image: ct2-c-shop-api:${APP_VERSION}
    command: ["node", "migrate.js"]
    env_file: api.env
    environment:
      DB_PASSWORD_FILE: /run/secrets/db_password
    secrets: [db_password]
    networks: [backend]
    depends_on:
      db:
        condition: service_healthy
    restart: "no"

  db:
    image: postgres:18.6-alpine
    environment:
      POSTGRES_USER: shop
      POSTGRES_DB: shop
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets: [db_password]
    volumes:
      - pgdata:/var/lib/postgresql
      - ./db-init:/docker-entrypoint-initdb.d:ro
    networks: [backend]
    healthcheck:
      test: ["CMD", "pg_isready", "-h", "127.0.0.1", "-U", "shop", "-d", "shop"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 60s
      start_interval: 1s
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 512M
    logging: *logging

  redis:
    image: redis:8.10.3-alpine
    command: ["redis-server", "--save", "60", "1", "--maxmemory", "64mb"]
    volumes:
      - redisdata:/data
    networks: [backend]
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 3
      start_period: 10s
      start_interval: 1s
    restart: unless-stopped
    logging: *logging

  psql:
    image: postgres:18.6-alpine
    profiles: [tools]
    environment:
      PGHOST: db
      PGUSER: shop
      PGDATABASE: shop
    secrets: [db_password]
    networks: [backend]
    entrypoint: ["sh", "-c", "PGPASSWORD=\"$$(cat /run/secrets/db_password)\" exec psql \"$$@\"", "psql"]

networks:
  frontend:
  backend:
    internal: true

volumes:
  pgdata:
  redisdata:

secrets:
  db_password:
    file: ./secrets/db_password.txt

في الإعداد أعلاه لاحظ التالي، إضافة إلى ما شرحناه في كل قسم:

  • كل Image بوسم دقيق مثل postgres:18.6-alpine وليس 18-alpine. وفي الإنتاج اذهب خطوة أبعد واكتب البصمة Digest مع الوسم، وقد شرحنا لماذا وكيف في تحديث ال Containers بأمان.
  • Redis له حد ذاكرة داخلي --maxmemory 64mb، وهو مختلف عن حد ال Container، فالأول يجعل Redis يرفض الكتابة أو يحذف المفاتيح بحسب سياسته، والثاني يقتل العملية. والأفضل أن يصل Redis إلى حده قبل أن يصل ال Container إلى حده.
  • مجلد سكربتات التهيئة مركب للقراءة فقط :ro، وكذلك ملفات nginx، فلا يستطيع ال Container أن يغير ملفات السيرفر.
  • لا يوجد أي منفذ منشور غير منفذ nginx، والوصول إلى قاعدة البيانات للصيانة عبر خدمة psql من داخل الشبكة.

وقد يتساءل البعض: هل هذا كثير على أربع خدمات؟ والإجابة أن كل سطر فيه جاء من مشكلة رأيناها في التجربة، وأن الملف يبقى مقروءاً في صفحتين. وعندما يصبح عندك عشرات الخدمات على عدة سيرفرات، وتحتاج نشراً دون توقف وتوزيعاً تلقائياً، فهذا هو الوقت الذي تفكر فيه في أداة أخرى، وقد ناقشنا متى يحدث ذلك في هل تحتاج Kubernetes فعلاً؟.

أخطاء شائعة Common Mistakes

  • depends_on بالصيغة المختصرة لقاعدة بيانات: يرتب البدء ولا ينتظر الجاهزية، وفي التجربة انهار ال API قبل جاهزية القاعدة بأربع عشرة ثانية.
  • pg_isready دون -h: يفحص ال Socket، فينجح أثناء سكربتات التهيئة والخادم لا يستمع على الشبكة.
  • الاعتماد على شروط Compose وحدها: تعمل عند البدء فقط، والتطبيق يحتاج إعادة اتصال عندما تعيد قاعدة البيانات التشغيل لاحقاً.
  • فحص صحة يستدعي curl في Image لا تحتوي عليه: الخدمة Unhealthy دائماً والتطبيق سليم.
  • كلمات المرور في environment: تظهر في docker inspect وفي Git، وعلامة $ فيها تقطعها بصمت.
  • الخلط بين .env وenv_file: الأول للملف، والثاني لل Container.
  • down -v بدل down: حرفان يحذفان قاعدة البيانات.
  • ملف Compose دون name:: نقل المجلد أو -p مختلف ينشئ Volumes فارغة.
  • حد الذاكرة دون memswap_limit: ال Container يأخذ مثل حده من ال Swap ويصبح بطيئاً بدل أن يتوقف.
  • compose.override.yaml على السيرفر: يحمل تلقائياً وينشر منافذ التطوير على كل العناوين.
  • قوائم في ملف الإنتاج دون !override: المنافذ تضاف إلى منافذ الملف الأساسي ولا تستبدلها.
  • تجاهل تحذيرات Compose: أغلبها أخطاء، وأهمها «variable is not set».

قائمة تحقق Checklist

البندكيف تتحقق
اسم المشروع ثابتname: في أول الملف، وdocker volume ls يعرض الأسماء المتوقعة
لكل خدمة طويلة فحص صحة يفحص كما يتصل المستخدمdocker compose ps يعرض (healthy)، وسجل الفحوص في docker inspect
الاعتماديات بشروطservice_healthy للخدمات وservice_completed_successfully للمهام
النشر ينتظر النتيجةdocker compose up -d --wait مع مهلة، ورمز خروجه يوقف الخط
لا توجد أسرار في الملف ولا في المتغيراتdocker inspect لا يعرض كلمة مرور، ومجلد secrets/ في .gitignore
المتغيرات المطلوبة بالصيغة :?docker compose config -q يفشل إذا نقصت
الشبكات معزولةقاعدة البيانات على شبكة داخلية، ولا منفذ منشور غير ال Reverse Proxy
حدود الذاكرة والمعالجMemorySwap يساوي Memory في docker inspect
سياسات إعادة التشغيلunless-stopped للخدمات و"no" للمهام، ومراقبة RestartCount
تدوير السجلاتlogging لكل خدمة أو في إعداد المحرك
الإنتاج منفصل عن التطويرلا يوجد compose.override.yaml على السيرفر، أو COMPOSE_FILE مضبوط
ال Images ثابتةوسوم دقيقة، وبصمات في الإنتاج

إزالة التجربة Cleanup

إذا شغلت التجربة على جهازك فهذه الأوامر تزيل كل ما أنشأته، ولاحظ أن -v هنا مقصود لأنها بيانات تجربة:

docker compose down -v
docker compose -p ct2-c-first -f compose.first.yaml down -v
docker image rm ct2-c-shop-api:1.0.0 ct2-c-first-api

الخلاصة Summary

وصلنا لنهاية الموضوع، وأهم ما فيه:

  • depends_on بصيغته المختصرة يرتب البدء فقط، والشرط service_healthy مع فحص صحة حقيقي هو ما ينتظر الجاهزية، والشرط service_completed_successfully مكان مهام الترحيل.
  • الفحص الشائع pg_isready دون -h نجح في التجربة أثناء سكربت التهيئة لأن الخادم المؤقت يستمع على ال Socket فقط، فانهار الترحيل، والفحص عبر 127.0.0.1 أصلح ذلك.
  • ملف .env للملف، وenv_file لل Container ويظهر في docker inspect، وكلمات المرور مكانها Secrets تقرأ من ملفات، مع الانتباه لعلامة $.
  • الشبكة الداخلية تمنع الوصول إلى الإنترنت وتمنع نشر المنافذ بصمت، وحد الذاكرة وحده يسمح بمثله من ال Swap حتى تضيف memswap_limit.
  • docker compose config يمسك الأخطاء قبل السيرفر، وcompose.override.yaml يحمل تلقائياً، فلا تتركه على السيرفر.

والمقال التالي المناسب بعد هذا هو كتابة ال Dockerfile نفسه بشكل صحيح، ثم تصغير ال Images وتأمينها، وهما في هذه المرحلة من المسار مع مقال البيانات وال Volumes:

دليلكتابة Dockerfile صحيح: Multi-stage وLayer Cachingخمس نسخ من Dockerfile للتطبيق نفسه نزلت بال Image من 641 ميجابايت إلى 66 وبالبناء بعد تعديل سطر من خمس دقائق إلى أقل من أربع ثوان، مع شرح كل سطر والأرقام المقاسة.دليلبيانات ال Containers: Volumes وBind Mounts والنسخ الاحتياطيأين تذهب ملفات ال Container وما الذي يحذفها، مع قياس حقيقي لسرعة مسارات Windows وLinux ونسخة احتياطية مستعادة لملفات Volume وقاعدة PostgreSQL.دليلتقليل حجم ال Docker Images وتأمينها Hardeningكيف تبني Image فيها ما يحتاجه تطبيقك فقط، وتقيس الفرق بين slim وalpine وdistroless وscratch بالحجم والثغرات، ثم تشغلها بمستخدم عادي وتوقعها قبل النشر.دليلشبكات Docker وأفضل الممارسات مع Docker Composeلماذا يبقى المنفذ الذي تنشره في Compose مفتوحاً للإنترنت رغم ufw، وكيف تصل التطبيقات إلى بعضها عبر شبكات Docker دون نشر منافذ.دليلبيئة تطوير محلية كاملة بملف Docker Compose واحدنبني بيئة تطوير فيها البريد وHTTPS والأسماء المحلية، ونكتب اختباراً آلياً لبريد استعادة كلمة المرور ثم نفتعل فيها الأعطال.

سجل التحديثات Changelog

  • 18 نوفمبر 2026: كتابة المقال، وتنفيذ التجربة على Docker Engine 29.8.0 مع Docker Compose v5.5.1، وpostgres:18.6-alpine وredis:8.10.3-alpine وnginx:1.29.8-alpine وnode:24-alpine (Node.js 24.21.0)، ومكتبتي pg 8.23.1 وredis 6.3.1.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.