Software Engineer Encyclopedia
0%
Domain 08 · DevOps, Cloud & Production Engineering · Topic 8.1

Docker من الصفر إلى تشغيل ASP.NET Core وSQL Server بصورة Production-Aware

Docker — Deep Practical Guide for .NET Engineers

Containers/images/layers/build context/multistage Dockerfile/network/volumes/Compose/health checks/security/non-root/registries/scanning و.NET container publishing وAspire.

  • Advanced
  • ~26 min read
  • 17 sections
  • 22 code examples
  • 1 diagrams
  • 7 questions
  • Priority L1 · Essential
  • Docker Engine 27+ concepts · .NET 10 · ASP.NET Core 10

المتطلبات قبل ما تبدأ

تطبيق backend جاهز للنشر (المجالات 03–05).

مستوى التعمق المطلوب

DEEP PRACTICALContainerize and debug an API and its dependencies.

01

Docker بيحل إيه؟ Containers vs Virtual Machines

Package a process with its runtime dependencies
Deep dive

المشكلة التي يحلها Docker: «اشتغل عندي ومشتغلش عندك». بدل ما توثق يدويًا كل runtime/library/configuration، تبني image تحتوي application و dependencies المطلوبة، ثم تشغلها كـ container على host يدعم container runtime. الـ image artifact immutable نسبيًا، والـ container instance process مع filesystem/network isolation و resource limits حسب الإعداد.

Container مش VM كاملة. VM عادة تشغل guest operating system و kernel خاص بها عبر hypervisor. Linux containers تشارك host kernel وتستخدم namespaces/cgroups للعزل وإدارة الموارد؛ لذلك أخف وأسرع غالبًا، لكن isolation boundary مختلفة عن VM. على Windows/macOS Docker Desktop قد يستخدم Linux VM لتشغيل Linux containers.

Docker لا يجعل التطبيق stateless تلقائيًا، ولا يحل secrets/configuration/backup/network security. لو كتبت ملفات مهمة داخل container writable layer ثم حذفت container، غالبًا تفقدها. البيانات الدائمة تحتاج volume أو external storage/database. ولا تجعل container database الوحيد بدون backup وخطة restore.

02

Multi-stage build في رسمة

Multi-stage image build
Basics
Stage 1: sdkCOPY *.csproj → restore (cached)COPY src → build → testdotnet publish -c Release -o /appStage 2: aspnet runtime (or chiseled)COPY --from=build /app .USER app (non-root)ENTRYPOINT ["dotnet","Shop.Api.dll"]/app onlyFinal image: no SDK, no source, smaller attack surface; deploy by digest
Build with the SDK, ship only the runtime and the published output; layers cache by instruction
03

Image vs Container و Lifecycle

Build once, run many instances
Deep dive

Image عبارة عن template layers مرتبة. Container هو instance مبني من image مع writable layer وإعدادات runtime. تقدر تشغل عدة containers من نفس image. تغيير code لا يغير container موجود؛ عادة تعيد build image ثم recreate container. ده يشجع immutable deployment بدل SSH داخل container وتعديل ملفات يدويًا.

BashImage and container lifecycle
# Build an image from the current build context
docker build -t myshop-api:dev .

# List local images and running containers
docker image ls
docker ps

# Start a container and publish host port 8080 to container port 8080
docker run --name myshop-api -p 8080:8080 myshop-api:dev

# Inspect logs and process state
docker logs -f myshop-api
docker inspect myshop-api

# Stop and remove the container (image remains)
docker stop myshop-api
docker rm myshop-api

docker run ينشئ container جديدًا. docker start يعيد تشغيل container موجود. docker exec ينفذ command داخل container شغال. docker attach يربط terminal بال process الأساسي وقد يؤثر على stdin/stdout؛ للتشخيص غالبًا exec و logs أنسب.

Image Lifecycle: Build Context و Layers و Tagging

Docker build لا يرسل كل القرص إلى daemon؛ يرسل build context. لذلك .dockerignore مهم: استبعد .git و bin و obj وملفات secrets ونتائج الاختبار غير المطلوبة. كل instruction تنتج layer قابلة للـ cache وفق input؛ ضع الملفات التي تتغير قليلًا (project files) قبل source code حتى لا تعيد restore مع كل تعديل. لكن لا تحوّل Dockerfile إلى لعبة cache على حساب الوضوح.

لا تستخدم latest في production deployment؛ tag متغير يجعل rollback غير قابل للتكرار. استخدم semantic version أو Git SHA، والأقوى أن تثبت image digest بعد push. نفس artifact الذي اختبرته يجب أن ينتقل إلى staging ثم production. لا تعِد build لكل environment لأنك قد تنشر binary مختلفًا دون قصد.

DockerfileProduction-oriented multi-stage .NET image
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["MyApi/MyApi.csproj", "MyApi/"]
RUN dotnet restore "MyApi/MyApi.csproj"
COPY . .
RUN dotnet publish "MyApi/MyApi.csproj" -c Release -o /app/publish \\
    --no-restore /p:UseAppHost=false

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime
WORKDIR /app
ENV ASPNETCORE_HTTP_PORTS=8080
EXPOSE 8080
COPY --from=build /app/publish .
USER $APP_UID
ENTRYPOINT ["dotnet", "MyApi.dll"]

الإصدار 8.0 هنا مثال يجب تحديثه إلى supported servicing tag متوافق مع التطبيق. راجع وجود APP_UID في الصورة المختارة؛ لا تفترض أن كل base image تملك نفس user setup. اختبر container فعليًا كمستخدم غير root، وتأكد من الكتابة إلى volume محدد فقط إذا احتجت ذلك. لا تنسَ dotnet publish output لا يحتاج SDK في runtime image.

04

Build Context و .dockerignore

Control what the builder can see
Deep dive

عند تنفيذ docker build .، النقطة تحدد build context: الملفات المتاحة للـ Dockerfile أثناء build. لو context هو root solution وفيه bin/obj/.git/secrets و node_modules، ممكن ترفع بيانات غير لازمة وتبطئ build وتكسر caching. استخدم .dockerignore لتحديد ما لا يدخل السياق.

Text.dockerignore for a .NET solution
**/bin/
**/obj/
**/.vs/
.git/
.gitignore
.vscode/
TestResults/
**/node_modules/
.env
.env.*
secrets.json
*.user

انتبه: .dockerignore يمنع الملفات من build context لكنه لا يحذف secrets سبق تضمينها في Git history أو image layer. لا تستخدمه كبديل لإدارة secrets. لا تنسخ solution كاملًا لو Dockerfile يحتاج ملفات محددة فقط؛ اجعل context مناسبًا للمشروع.

05

Image Layers و Build Cache

Order instructions for fast reproducible builds
Deep dive

كل instruction مناسبة قد تنتج layer/cache entry. لو نسخت كل source code قبل restore، أي تعديل في ملف .cs قد يبطل cache لمرحلة dependency restore. الأفضل نسخ project/solution files أولًا، restore، ثم source code، ثم publish. لا تضع خطوات متغيرة بلا داعٍ قبل خطوات ثابتة. استخدم .dockerignore لتقليل context.

DockerfileCache-friendly .NET build ordering
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src

COPY MyShop.Api/MyShop.Api.csproj MyShop.Api/
COPY MyShop.Application/MyShop.Application.csproj MyShop.Application/
COPY MyShop.Core/MyShop.Core.csproj MyShop.Core/
COPY MyShop.Infrastructure/MyShop.Infrastructure.csproj MyShop.Infrastructure/
RUN dotnet restore MyShop.Api/MyShop.Api.csproj

COPY . .
RUN dotnet publish MyShop.Api/MyShop.Api.csproj \
    -c Release -o /app/publish --no-restore

الكود يفترض أسماء ومسارات مشاريع مطابقة فعلًا؛ غيّرها حسب solution عندك. لو عندك Directory.Build.props أو NuGet.config أو central package management، انسخها قبل restore لأنها تؤثر في dependency resolution. BuildKit يضيف cache mounts لـ NuGet packages لتقليل network downloads عبر builds.

06

Multi-Stage Builds: SDK للبناء و Runtime للتشغيل

Keep compilers and source out of production
Deep dive

SDK image تحتوي compiler و CLI وأدوات build، وغالبًا أكبر. Runtime/ASP.NET image تحتوي runtime اللازم لتشغيل app فقط. Multi-stage build يستخدم SDK في stage ثم ينسخ publish output إلى runtime stage. النتيجة أصغر، attack surface أقل، ولا تحتاج source code أو compiler داخل production image.

DockerfileMulti-stage ASP.NET Core Dockerfile
# Build stage
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY . .
RUN dotnet restore MyShop.Api/MyShop.Api.csproj
RUN dotnet publish MyShop.Api/MyShop.Api.csproj \
    -c Release -o /app/publish --no-restore

# Runtime stage
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS final
WORKDIR /app
COPY --from=build /app/publish .
ENV ASPNETCORE_HTTP_PORTS=8080
EXPOSE 8080
USER app
ENTRYPOINT ["dotnet", "MyShop.Api.dll"]

راجع أن runtime image متوافقة مع طريقة النشر: framework-dependent يحتاج ASP.NET runtime image، بينما self-contained publish له اعتبارات مختلفة وقد يحتاج base image مختلفة. Native dependencies و ICU globalization و timezone data قد تختلف بين Alpine و Debian/chiseled. لا تختَر Alpine لمجرد الحجم من غير اختبار.

في ‎.NET 8+ الصور الرسمية تتضمن user باسم app، و ASP.NET Core images تستخدم port 8080 افتراضيًا بدل الافتراض القديم 80. لكن تحقق من image tag والـ documentation الحالية عند تغيير major version أو base variant؛ لا تنسخ Dockerfile قديمًا كما هو.

07

Ports و Networks و DNS بين Containers

Host ports are not container ports
Deep dive

لو API داخل container تستمع على 8080، لا يعني أن host port 8080 مفتوح تلقائيًا. -p 8088:8080 معناها host:8088 → container:8080. داخل Docker network، container يتصل ب container آخر عبر service/container DNS name والـ container port، وليس host localhost. localhost داخل API container يعني API container نفسه، مش SQL Server container ولا جهازك.

BashCreate a network and connect API to SQL Server
docker network create myshop-net

docker run -d --name myshop-db \
  --network myshop-net \
  -e ACCEPT_EULA=Y \
  -e MSSQL_SA_PASSWORD='Use-A-Strong-Dev-Only-Secret!' \
  -p 1433:1433 \
  mcr.microsoft.com/mssql/server:2022-latest

# Connection from API container uses myshop-db, not localhost
# Server=myshop-db,1433;Database=MyShop;User Id=sa;Password=...;Encrypt=True;TrustServerCertificate=True

كلمة المرور هنا placeholder تعليمي فقط؛ لا تضعها في shell history أو source control في بيئة حقيقية. استخدم secrets management. نشر 1433 على host غير ضروري لو API فقط هي التي تتصل بقاعدة البيانات؛ احذف -p في production أو قيّد الوصول. لا تجعل SQL Server متاحًا للعالم.

Docker bridge network يوفر service discovery و network isolation نسبي. لا تخلط بين port publishing و container-to-container communication. استخدم explicit network بدل default bridge عندما تريد DNS-based communication، وراجع firewall/security groups على host/cloud.

Debugging شبكة Docker: من DNS إلى Port Binding

داخل Docker network، container يتصل باسم service/container على port الداخلي، وليس host-published port. مثلًا API container يتصل بـ ecproj-db,1433، بينما جهاز Windows يتصل بـ localhost,1433 لو تم نشر المنفذ. لا تستخدم localhost داخل API container للإشارة إلى SQL container؛ localhost يعني نفس API container.

BashInspect the network and test name resolution
docker network inspect ecommerce-network
docker inspect ecproj-db --format '{{json .NetworkSettings.Networks}}'
docker exec ecproject sh -c 'getent hosts ecproj-db'
docker exec ecproject sh -c 'nc -vz ecproj-db 1433'
docker logs --tail 200 ecproject

الأوامر المتاحة تختلف حسب base image؛ Alpine قد لا يحتوي nc أو getent أو bash. استخدم temporary diagnostic container على نفس network عند الحاجة. افصل بين DNS failure و TCP refused و timeout و SQL authentication failure: كل واحد له طبقة تشخيص مختلفة. لا تفتح 1433 للعالم؛ انشره على localhost فقط للتطوير أو اتركه داخليًا في production.

Docker Networking: DNS و Port Publishing و Service Discovery

داخل user-defined bridge network، container يصل إلى container آخر باستخدام service/container name و container port، مثل Server=db,1433. هذا مختلف عن الاتصال من Windows host إلى published port مثل localhost,1433. لا تستخدم IP ثابتًا داخل التطبيق؛ Docker DNS يحل الاسم إلى IP الحالي عند الاتصال. عند إعادة إنشاء container قد يتغير IP.

-p 1433:1433 ينشر port على host؛ لا يعني أن كل container يحتاج publish حتى يتواصل مع الآخر. افتح أقل ports ممكنة، ولا تعرض database للإنترنت. استخدم network segmentation عند الحاجة: edge network للـ proxy و private network للـ database. DNS resolution لا يضمن أن الخدمة جاهزة؛ client يحتاج retry محدودًا أو startup dependency strategy.

BashCreate isolated network and run SQL Server
docker network create shop-net

docker run -d --name shop-db \\
  --network shop-net \\
  -e ACCEPT_EULA=Y \\
  -e MSSQL_SA_PASSWORD="$DB_ADMIN_PASSWORD" \\
  -p 127.0.0.1:1433:1433 \\
  mcr.microsoft.com/mssql/server:2022-latest

# API container connects to Server=shop-db,1433
# Host tools connect to localhost,1433

في production لا تستخدم SA credentials للتطبيق؛ أنشئ login محدودًا بصلاحيات database المطلوبة. لا تضع password literal في shell history أو Dockerfile. استخدم secret store و rotation. لا تجعل database port public إلا لسبب واضح مع network policy و TLS.

08

Volumes و Bind Mounts و Persistence

Keep data outside the disposable container
Deep dive

Named volume يديره Docker ومناسب لبيانات database container. Bind mount يربط path من host إلى container، ومفيد في local development لمشاركة source/config. tmpfs storage مؤقت في memory على Linux. كل نوع له lifecycle و permissions ومخاطر مختلفة. لا تستخدم bind mount لمسارات حساسة بدون فهم host/container permissions.

BashPersist SQL Server data in a named volume
docker volume create myshop-sql-data

docker run -d --name myshop-db \
  --network myshop-net \
  -v myshop-sql-data:/var/opt/mssql \
  -e ACCEPT_EULA=Y \
  -e MSSQL_SA_PASSWORD="$MSSQL_SA_PASSWORD" \
  mcr.microsoft.com/mssql/server:2022-latest

docker volume inspect myshop-sql-data

Volume ليس backup. لو database corruption أو حذف volume أو ransomware، volume قد يضيع. صمم backup/restore خارج container lifecycle، واختبر restore فعلًا. لا تنفذ docker compose down -v بلا فهم؛ -v يحذف named volumes المعرفة في compose.

Volumes و Secrets و Health: البيانات خارج عمر الـ Container

Container filesystem مؤقت؛ حذف container قد يحذف البيانات المكتوبة داخله. Database files تحتاج named volume أو managed database، مع backup/restore plan. Volume ليس backup: تلف disk أو حذف volume أو corruption قد يضيع البيانات. اختبر restore دوريًا. Bind mounts مناسبة للتطوير ومشاركة ملفات host، لكنها تختلف في performance و permissions عبر Windows/Linux.

Environment variables عملية للـ configuration غير السرية، لكن secrets قد تظهر في inspect أو process metadata أو logs حسب البيئة. لا تمرر secrets في build args؛ قد تبقى في image layers/history. استخدم Docker/Platform secrets أو cloud secret manager. Healthcheck داخل image يجب أن يعتمد على أداة موجودة بالفعل؛ لا تفترض وجود curl في slim image. والأفضل أن التطبيق يعرض health endpoint واضحًا ويحدد orchestrator طريقة الفحص.

YAMLCompose development stack with persistent database
services:
  api:
    build: .
    environment:
      ASPNETCORE_ENVIRONMENT: Development
      ConnectionStrings__Default: Server=db,1433;Database=Shop;User Id=app;Password=${DB_PASSWORD};Encrypt=True;TrustServerCertificate=True
    ports:
      - "8080:8080"
    depends_on:
      db:
        condition: service_healthy
  db:
    image: mcr.microsoft.com/mssql/server:2022-latest
    environment:
      ACCEPT_EULA: "Y"
      MSSQL_SA_PASSWORD: ${DB_ADMIN_PASSWORD}
    volumes:
      - sql-data:/var/opt/mssql
    healthcheck:
      test: ["CMD-SHELL", "/opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P \"$$MSSQL_SA_PASSWORD\" -C -Q 'SELECT 1' || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 10
volumes:
  sql-data:

هذا compose مثال تطوير وليس production template؛ تحقق من مسار sqlcmd في image tag المختار، واستخدم secret mechanism مناسبًا بدل .env غير المحمي. depends_on: service_healthy ينتظر healthcheck في Compose، لكنه لا يحل انقطاع database بعد بدء التطبيق. التطبيق نفسه يجب أن يتعامل مع transient failures.

09

Environment Variables و Secrets

Configuration is runtime input; secrets need stronger handling
Deep dive

12-factor style: app تقرأ configuration من environment/config providers بدل hard-coded values. لكن environment variables ليست secret vault؛ قد تظهر في docker inspect أو process metadata أو logs أو crash dumps. لا تضع production passwords في Dockerfile ENV أو ARG أو image layers. Build secrets مخصصة لبيانات يحتاجها build مؤقتًا، أما runtime secrets فتأتي من secret manager/orchestrator.

BashPass non-secret configuration at runtime
docker run -d --name myshop-api \
  --network myshop-net \
  -p 8080:8080 \
  -e ASPNETCORE_ENVIRONMENT=Production \
  -e ConnectionStrings__DefaultConnection="$DB_CONNECTION" \
  myshop-api:1.0.0

في ASP.NET Core، ConnectionStrings__DefaultConnection يقابل ConnectionStrings:DefaultConnection بسبب double underscore mapping. لا تسجل connection string في logs. في cloud، فضّل Managed Identity/Workload Identity للوصول إلى secrets/database عندما provider يدعمها بدل static credentials.

BuildKit Secrets و Private NuGet Feeds

لو restore يحتاج private NuGet feed، لا تمرر PAT كـ build ARG أو ENV ثم تمسحها في layer لاحقة؛ layers السابقة قد تحتفظ بالقيمة. BuildKit secret mount يمرر الملف مؤقتًا لمرحلة واحدة ولا يضيفه تلقائيًا إلى image layer. احمِ build logs، لأن command قد يطبع secret بنفسه.

DockerfileBuildKit secret mount for NuGet config
# syntax=docker/dockerfile:1.7
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY . .
RUN --mount=type=secret,id=nuget_config,target=/root/.nuget/NuGet/NuGet.Config \
    dotnet restore MyShop.Api/MyShop.Api.csproj
RUN dotnet publish MyShop.Api/MyShop.Api.csproj \
    -c Release -o /app/publish --no-restore
BashBuild with a secret file
docker buildx build \
  --secret id=nuget_config,src="$HOME/.nuget/NuGet/NuGet.Config" \
  -t myshop-api:dev .

Secret mount متاح أثناء RUN المحددة فقط، لكن أي process في نفس step يمكنها قراءة الملف. لا تشغّل arbitrary scripts غير موثوقة في نفس step. كذلك لا تستخدم build secrets لإعداد runtime connection string؛ runtime secrets لها lifecycle مختلف.

Secrets و Container Runtime Hardening

Environment variables مريحة لكنها ليست secret manager؛ قد تظهر في process inspection أو diagnostics أو crash dumps أو configuration dumps. في local development استخدم user-secrets أو local secret store، وفي cloud استخدم managed identity لقراءة secret وقت التشغيل. Docker secrets أو orchestrator secret store أفضل من تضمين السر في image، لكن يلزم ضبط encryption/access/rotation حسب المنصة.

شغّل process كمستخدم غير root، واستخدم filesystem read-only مع writable temp path محدد، واحذف Linux capabilities غير اللازمة، وحدد CPU/memory limits، وحدث base images، وافحص CVEs، ووقّع images أو تحقق من provenance عند توفر supply-chain controls. لا تستخدم latest في production؛ استخدم immutable digest أو version tag مرتبطًا بـ release.

لا تضع ASPNETCORE_ENVIRONMENT=Development في production ولا تعرض developer exception page. اجعل container يتلقى SIGTERM ويغلق gracefully؛ PID 1 وسلوك signal forwarding مهمان خصوصًا لو تشغل shell wrapper. اختبر shutdown أثناء request و message processing حتى لا تفقد عملًا جاريًا.

10

Docker Compose: تشغيل API و Database معًا

Describe a local multi-container application
Deep dive

Compose يصف services و networks و volumes و configs في ملف declarative. مناسب local development و integration environments؛ لا يعني أنه production orchestrator كامل. كل service تحصل DNS name باسمها داخل network. depends_on ينظم startup order، لكن لا يضمن readiness إلا مع healthcheck و condition supported by Compose implementation؛ التطبيق نفسه يجب يعالج transient connection failures/retries.

YAMLcompose.yaml — local API and SQL Server
services:
  db:
    image: mcr.microsoft.com/mssql/server:2022-latest
    environment:
      ACCEPT_EULA: "Y"
      MSSQL_SA_PASSWORD: ${MSSQL_SA_PASSWORD:?set a local secret}
    volumes:
      - sql-data:/var/opt/mssql
    healthcheck:
      test: ["CMD-SHELL", "/opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P \"$${MSSQL_SA_PASSWORD}\" -C -Q 'SELECT 1' || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 12
      start_period: 30s

  api:
    build:
      context: .
      dockerfile: MyShop.Api/Dockerfile
    environment:
      ASPNETCORE_ENVIRONMENT: Development
      ASPNETCORE_HTTP_PORTS: "8080"
      ConnectionStrings__DefaultConnection: ${DB_CONNECTION}
    ports:
      - "8080:8080"
    depends_on:
      db:
        condition: service_healthy

volumes:
  sql-data:

الـ healthcheck command path قد يختلف حسب SQL Server image version؛ اختبره على tag المستخدم. لو أدوات sqlcmd غير موجودة، استخدم healthcheck مناسب أو أداة probe منفصلة. لا تنس أن Compose interpolation لملف .env لا يجعل القيمة secret-safe تلقائيًا. الملف أعلاه نموذج local فقط؛ لا تستخدم Development ولا SA password في production.

BashCompose workflow
docker compose config
docker compose up --build -d
docker compose ps
docker compose logs -f api
docker compose exec api sh
docker compose down
# Keep the volume: do not add -v unless data deletion is intended.

Compose Lifecycle: Startup لا يعني Readiness

Docker Compose ممتاز لتجميع local development dependencies: API و SQL و Redis و broker. depends_on يرتب startup، وشرط service_healthy ينتظر healthcheck في Compose الحديث، لكنه لا يضمن أن dependency ستظل سليمة لاحقًا. التطبيق يجب يتعامل مع connection drops و database restart ويعيد فتح connections عبر provider resiliency policy.

اجعل volumes واضحة، ولا تستخدم نفس named volume لنسختين database متزامنتين. افصل profiles مثل dev و test إذا كانت الخدمات تختلف. لا تجعل Compose file نسخة طبق الأصل من production؛ production قد يستخدم managed database و secret manager و orchestrator. الهدف بيئة محلية reproducible وليس محاكاة كل cloud detail.

11

Health Checks و Restart Policies و Graceful Shutdown

A running process is not necessarily a ready service
Deep dive

Health check تقيس حالة container/service من منظور probe. Liveness: هل process عالقة وتحتاج restart؟ Readiness: هل instance قادرة تستقبل traffic؟ Dependency health: هل DB/broker متاح؟ لا تجعل liveness تعتمد على database؛ انقطاع DB مؤقت قد يجعل كل API instances unhealthy فتعمل restart storm. readiness يمكن أن تعكس dependency availability حسب architecture.

Restart policy مثل unless-stopped تعيد تشغيل process عند exit وفق قواعد Docker، لكنها ليست health remediation شاملة. healthcheck status وحده لا يعيد تشغيل container تلقائيًا في كل configurations. في orchestration platforms، readiness/liveness/startup probes لها semantics مختلفة. التطبيق لازم يتعامل مع SIGTERM، يوقف قبول طلبات جديدة، يكمل in-flight work ضمن grace period، ويغلق connections.

Production Readiness: Resource Limits و Logging و Shutdown

Containerization لا تعني أن process يمكنها استهلاك CPU/RAM بلا حدود. ضع resource requests/limits في orchestrator أو flags مناسبة في runtime، وراقب memory working set و GC behavior و CPU throttling. Container memory limit قد تجعل ‎.NET GC يختار heap behavior مختلفًا؛ راقب memory داخل cgroup بدل الاعتماد على host free memory فقط.

اكتب logs إلى stdout/stderr بدل ملفات داخل container في أغلب deployments، حتى platform تجمعها. استخدم structured logging مع correlation/trace IDs، ولا تسجل secrets أو tokens أو full payment data. اجعل process تتعامل مع SIGTERM gracefully، وتغلق DB connections و message consumers. حدد termination grace period أكبر من shutdown المتوقع، لكن لا تعتمد على shutdown لإنهاء jobs طويلة غير durable.

لا تجعل filesystem داخل container مصدر truth ل uploads أو reports أو generated files المطلوبة بعد restart. استخدم object storage أو persistent volume مناسبًا. لو تحتاج local temp files، ضعها في temp path وراقب disk pressure.

Runtime Limits و Graceful Shutdown

Container memory limit قد يؤدي إلى OOM kill دون فرصة للتطبيق كي يرمي exception. راقب working set و GC heap و container memory، ولا تضبط memory limit قريبًا جدًا من heap المتوقع؛ native memory و buffers و runtime overhead تحتاج مساحة. CPU throttling قد يرفع latency حتى لو CPU average يبدو منخفضًا. اختبر تحت limits مشابهة للإنتاج.

عند stop يرسل runtime signal ثم ينتظر grace period قبل kill. ASP.NET Core Generic Host يتعامل مع graceful shutdown و CancellationToken؛ تأكد أن background workers توقف استقبال عمل جديد، وتكمل أو تحفظ العمل الجاري ضمن deadline، وتغلق connections. لا تستخدم Environment.Exit في normal shutdown. Queue visibility/lease يجب تجدد أو تعاد الرسالة إذا لم يكتمل العمل.

12

Container Security: Non-root و Image Hygiene

Reduce privileges and attack surface
Deep dive

شغّل process كمستخدم non-root متى أمكن، وقلل packages والـ capabilities والملفات القابلة للكتابة. لا تضف SSH server داخل application container لمجرد سهولة الدخول. لا تستخدم --privileged إلا لسبب استثنائي مدروس. استخدم read-only root filesystem عند توافق التطبيق، وحدد CPU/memory limits، وامنع secrets من image layers.

ثبّت image versions ولا تعتمد على floating tags وحدها في release process. Digest pinning يعطي artifact محددًا، لكن يتطلب تحديثًا دوريًا منظمًا للحصول على security fixes. امسح images باستخدام scanner، راجع SBOM، راقب base image vulnerabilities، وأعد build بعد تحديثات security. Scan ليس ضمانًا مطلقًا؛ false positives و unfixed CVEs تحتاج risk triage.

BashInspect and scan image metadata
docker image inspect myshop-api:1.0.0
docker history myshop-api:1.0.0
# Example scanner command; install and configure a scanner such as Trivy separately:
trivy image myshop-api:1.0.0

لا تطبع secrets أثناء build، ولا تستخدم ARG TOKEN=... كأنه آمن؛ build args قد تظهر في metadata/history. BuildKit secret mounts أفضل للـ private NuGet feed credentials أثناء restore. لا تجعل production image تحتوي .git, source secrets, test data أو development certificates.

Multi-Architecture Images و Image Provenance

Image المبنية لـ amd64 قد لا تعمل على arm64 والعكس، أو قد تعمل عبر emulation مع أداء مختلف. Buildx يدعم multi-platform builds باستخدام buildx builder/QEMU أو native builders. اختبر architecture target، خصوصًا native dependencies و runtime identifiers و base image support.

BashBuild and push multi-platform image
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t registry.example.com/myshop-api:1.2.0 \
  --push .

لـ supply-chain assurance، أضف SBOM و provenance attestations وتوقيع image حسب tooling والسياسات. Registry digest يحدد المحتوى، لكن provenance يساعدك تعرف مصدر build. لا تخلط بين signature صحة publisher وبين vulnerability scan؛ هما checks مختلفة.

Container Supply Chain: Base Images و SBOM و Image Scanning

صورة Docker artifact يحمل OS packages و runtime و application binaries؛ لذلك هي جزء من supply chain. استخدم official/minimal base image من publisher موثوق، ثبّت tag servicing واضحًا، حدّث بانتظام، وامسح vulnerabilities. لا تختَر Alpine تلقائيًا لمجرد الحجم؛ native dependencies و ICU/globalization و musl compatibility قد تسبب مشاكل. قارن distroless/chiseled/alpine/debian حسب التطبيق والدعم.

SBOM يسجل مكونات artifact، ويساعد على معرفة هل dependency متأثرة بـ CVE. image scanning لا يغني عن patching ولا يحدد exploitability وحده. افصل critical vulnerabilities القابلة للاستغلال عن false positives وفق policy موثقة، ولا تخفيها. وقّع images أو استخدم provenance/attestations في pipeline عند توفر tooling مناسب، ثم تحقق من signature قبل deployment.

لا تضع compiler أو SDK في runtime image. لا تنسخ .env أو private NuGet config أو certificates السرية ضمن build context. BuildKit secrets يمكنها توفير credentials مؤقتًا أثناء build دون تخزينها ك layer، لكن أي output ينسخه build step إلى filesystem قد يظل ضمن image. افحص layers وليس Dockerfile فقط.

Docker Production Checklist: Least Privilege و Network و Patch

قبل production راجع: image من مصدر موثوق ومثبتة بال digest؛ runtime user غير root؛ لا توجد secrets في layers أو labels أو build args؛ filesystem read-only قدر الإمكان؛ capabilities أقل؛ ports منشورة عند الحاجة فقط؛ database على private network؛ resource limits مضبوطة؛ logs إلى stdout/stderr؛ graceful shutdown يعمل؛ image scan و SBOM موجودان؛ والـ base image لها patch cadence.

راجع أيضًا container escape risk وحدود kernel sharing: containers ليست VMs كاملة، فهي تشارك kernel host. لا تشغل untrusted code في container عادي وتفترض isolation تامة. استخدم sandbox/runtime isolation أقوى أو managed service مناسب عند تنفيذ user-supplied code. لا تمنح Docker socket للتطبيق؛ الوصول إلى daemon قد يعادل root على host.

13

Container Registries و Tagging و Release Promotion

Build an artifact and promote the same digest
Practical

Registry يخزن images و manifests/layers، مثل Azure Container Registry أو GitHub Container Registry أو Docker Hub. Tag مثل 1.4.2 label قابل لإعادة التوجيه ما لم تفرض immutability policy؛ digest content-addressed identifier يحدد image content. CI الأفضل يبني image مرة، يختبرها، يسجل digest، ثم يرقّي نفس artifact بين environments بدل إعادة build مختلف لكل environment.

BashTag and push an image
docker login myregistry.azurecr.io
docker tag myshop-api:1.0.0 myregistry.azurecr.io/myshop-api:1.0.0
docker push myregistry.azurecr.io/myshop-api:1.0.0

docker pull myregistry.azurecr.io/myshop-api:1.0.0
docker image inspect myregistry.azurecr.io/myshop-api:1.0.0

لا تضع credentials في command history في بيئة مشتركة. استخدم registry login عبر workload identity أو secure CI credential. افصل image version عن app config: نفس image يمكن أن تعمل في staging و production مع runtime configuration مختلفة.

Container Deployment Patterns: Immutable Infrastructure

تعامل مع container instance كنسخة disposable؛ لا تدخل إليها وتثبت package أو تغير config يدويًا. كل تغيير يجب يرجع إلى source أو image build أو runtime config ثم يعاد إنشاء instance. هذا يجعل rollback و reproducibility ممكنين. لا تكتب application state على container writable layer؛ استخدم database/object storage/volume مصمم للبيانات الدائمة.

افصل build-time عن runtime: compiler و SDK و test tools في build stage، والـ runtime image تحتوي فقط ما يلزم لتشغيل التطبيق. افصل config per environment عن image. اجعل startup deterministic ولا تشغل database migrations في كل replica عند startup. استخدم one-off migration job أو controlled release stage. هذا يمنع race عندما تتوسع الخدمة إلى عدة containers.

14

بديل Dockerfile: dotnet publish كـ Container

Understand SDK container publishing
Practical

SDK الحديثة تقدر تنتج OCI container image مباشرة من dotnet publish في سيناريوهات مدعومة، من غير كتابة Dockerfile يدوي. ده يقلل boilerplate لتطبيق ‎.NET بسيط، لكنه لا يلغي حاجتك لفهم base image، ports، non-root، native dependencies، registry، configuration و health. لو تحتاج build stages مخصصة أو OS packages أو frontend build، Dockerfile/BuildKit قد يكون أوضح.

BashPublish a .NET project as a container
dotnet publish MyShop.Api/MyShop.Api.csproj \
  -c Release \
  -p:PublishProfile=DefaultContainer \
  -p:ContainerRepository=myshop-api \
  -p:ContainerImageTag=1.0.0

راجع SDK documentation والـ project properties المدعومة في ‎.NET version المستخدمة؛ container publishing properties تتغير عبر SDK versions. لا تفترض أن الأمر أعلاه سيعمل بنفس الشكل في كل SDK أو CI environment، واختبر image الناتجة قبل نشرها.

15

‎.NET Aspire و Dev Containers و Chiseled Images

Know the adjacent tools
Practical

‎.NET Aspire يساعد في local orchestration/observability لتطبيقات ‎.NET متعددة المكونات؛ لا يغني عن فهم Docker networks/volumes/images. Dev Containers توحّد developer environment داخل container، وتهدف reproducibility للتطوير وليس بالضرورة production runtime. Chiseled/distroless images تقلل packages و attack surface، لكن قد تفتقد shell/package manager/diagnostic tools؛ لازم تعرف كيف تشخص التطبيق عبر logs/metrics/traces بدل افتراض وجود bash.

اختيار base image قرار trade-off بين size، security, globalization, native dependencies, diagnostics, startup و patch cadence. Alpine يستخدم musl libc بدل glibc؛ بعض native dependencies تتطلب glibc. اختبر التطبيق والـ NuGet packages والـ globalization behavior على الصورة الفعلية.

16

تشخيص مشاكل Docker الشائعة خطوة بخطوة

Observe before changing random settings
Deep dive
  • API لا تصل إلى SQL: افحص network membership، DNS service name، container port، connection string، SQL readiness، credentials و TLS. localhost داخل API container غالبًا السبب.
  • Port already allocated: host port مستخدم؛ غيّر host side من -p 8088:8080 أو أوقف الخدمة المتعارضة.
  • Container exits: ابدأ بـ docker ps -a و docker logs و docker inspect؛ لا تفترض أن المشكلة port.
  • Build بطيء: افحص build context و .dockerignore وترتيب COPY/restore و cache hits.
  • Data disappeared: راجع volume mount واسم volume و down -v والـ host storage.
  • Permission denied: افحص UID/GID و volume ownership و non-root user؛ لا تحلها تلقائيًا بتشغيل root.
  • Container healthy لكن API broken: تأكد أن healthcheck يفحص readiness الفعلية وليس مجرد وجود process.
BashA repeatable diagnostic sequence
docker ps -a
docker logs --tail 200 myshop-api
docker inspect myshop-api
docker network inspect myshop-net
docker volume ls
docker stats
# Execute a diagnostic command only if the image contains the needed tools:
docker exec -it myshop-api sh

Debugging: لا تدخل Container قبل ما تقرأ Signals

ابدأ بـ docker ps -a لمعرفة state و exit code، ثم docker logs، ثم docker inspect للـ env/mounts/network/health. استخدم docker stats لمراقبة الموارد. docker exec مناسب لو container شغالة وبها shell/tools، لكن production chiseled image قد لا تحتوي shell. لا تثبت أدوات داخل production container يدويًا؛ استخدم ephemeral debug container أو diagnostics image حسب platform.

لو app starts then exits، افحص entrypoint و DLL name و working directory و environment و configuration. لو container healthy لكن request fails، اختبر من داخل network باستخدام diagnostic container، وافحص DNS و TLS و ports. لو DNS resolves لكن TCP fails، المشكلة غالبًا listener/firewall/port mapping، مش DNS.

تشخيص Container في التشغيل الحقيقي

ابدأ بـ docker ps -a لمعرفة الحالة و exit code، ثم docker logs --since 10m api، ثم docker inspect للـ environment/network/mounts، ثم docker stats لمراقبة CPU والذاكرة. استخدم docker exec للتشخيص فقط، لا تعدّل production container يدويًا؛ التعديل سيضيع عند إعادة إنشائه ولن يكون reproducible. أصلح Dockerfile/config ثم أعد deployment.

BashA compact diagnostic sequence
docker ps -a
docker logs --tail 200 --since 15m api
docker inspect api
docker stats --no-stream
docker network inspect shop-net
# Check published ports and host binding
docker port api

لو container في restart loop، افحص آخر logs و exit code و OOMKilled. لو API لا يصل إلى SQL، اختبر DNS من نفس network، ثم port reachability، ثم credentials، ثم TLS/database name. لا تبدأ بإطفاء firewall أو TrustServerCertificate=True كحل دائم؛ شخّص طبقة الفشل. Rollback يكون إلى image digest سابق، لا إلى tag عائم.

Docker Troubleshooting Lab: DNS و TLS و OOM و Exit Codes

لو API لا يصل إلى database، افحص من container API: هل DNS يحل db؟ هل TCP port مفتوح؟ هل SQL يستمع على container interface؟ هل credentials صحيحة؟ هل TLS certificate موثوق؟ هل database جاهزة؟ افصل name resolution عن transport عن authentication عن SQL login. ping قد لا يعمل لأن ICMP غير متاح، فلا تعتبر فشله دليلًا على network failure.

Exit code 137 غالبًا يشير إلى SIGKILL وقد يكون OOM، لكنه ليس إثباتًا وحده؛ راجع OOMKilled و host events. Exit code 1 غالبًا application error؛ راجع logs. docker inspect يوضح restart policy و mounts و network. لا تعالج certificate error بإيقاف TLS validation في production؛ أصلح trust chain و hostname. دوّن hypothesis ونتيجة كل اختبار حتى لا تكرر خطوات عشوائية.

Docker في Production: Failure Drills و Debugging Checklist

الـ container ليس VM كاملة؛ process واحدة أو مجموعة processes تعمل داخل namespaces/cgroups. وقت incident اسأل: هل process خرجت؟ هل container اتقتلت بسبب OOM؟ هل DNS أو network فشل؟ هل volume ممتلئ؟ هل التطبيق لم يستقبل SIGTERM؟ لا تبدأ بـ restart عشوائي لأنه قد يمسح evidence.

سيناريوهات التشخيص

  • Exited non-zero: افحص exit code و logs و command/entrypoint و environment.
  • OOMKilled: قارن memory limit مع working set و GC behavior؛ لا ترفع limit بلا قياس.
  • Cannot connect to SQL: تحقق من network membership و DNS name و port و SQL readiness، ولا تستخدم localhost داخل container للإشارة إلى host أو container آخر.
  • Container healthy لكن API unavailable: health check قد يفحص process فقط؛ اختبر endpoint الذي يمثل readiness المطلوبة.
  • Graceful shutdown failure: تأكد أن التطبيق يستقبل SIGTERM، يوقف قبول requests الجديدة، وينهي in-flight work ضمن grace period.
BashIncident commands — inspect before restarting
docker ps -a

docker inspect --format '{{.State.Status}} {{.State.ExitCode}} {{.State.OOMKilled}}' my-api

docker logs --timestamps --tail 200 my-api

docker stats --no-stream my-api

docker inspect --format '{{json .NetworkSettings.Networks}}' my-api

docker exec my-api sh -c 'printenv | sort | sed -E "s/(PASSWORD|TOKEN|KEY)=.*/\1=[REDACTED]/I"'

docker events --since 15m

لا تنسخ environment output إلى تذكرة عامة؛ حتى بعد masking قد تظهر أسرار بأسماء غير متوقعة. لا تستخدم docker exec كحل دائم لتعديل production container؛ التغيير يجب أن يأتي من image/config versioned. اجمع logs/inspect/events أولًا، ثم نفّذ remediation مع توثيق.

Checklist قبل النشر

  • Image مبنية multi-stage، pinned base image، non-root، وبدون SDK في runtime image.
  • لا secrets داخل image layers أو build args؛ استخدم secret mount أثناء build عند الحاجة.
  • Ports و health checks و stop timeout و read-only filesystem حيث يناسب.
  • CPU/memory limits مع headroom، logs إلى stdout/stderr، و volume فقط للبيانات التي يجب أن تبقى.
  • اختبر startup، readiness، SIGTERM، restart، و dependency unavailable.
17

اختبر فهمك

Knowledge check
Practical
ما الفرق بين image و container؟
Image artifact من layers؛ container instance شغال/متوقف مبني من image مع writable layer وإعدادات runtime.
لماذا API container لا تتصل بـ SQL باستخدام localhost؟
لأن localhost يشير لنفس container؛ استخدم service/container DNS name داخل network.
هل named volume يعتبر backup؟
لا؛ volume persistence خارج container فقط، وتحتاج backup/restore مستقل ومختبر.
لماذا multi-stage build مفيد؟
يفصل SDK/build tools عن runtime image ويقلل الحجم والـ attack surface.
هل depends_on وحده يضمن أن database جاهزة؟
لا؛ startup order لا يساوي readiness. استخدم healthcheck مع retries في التطبيق.
هل environment variables secret vault؟
لا؛ قد تظهر عبر inspect/process metadata. استخدم runtime secret manager أو orchestrator secrets.
متى تختار Alpine؟
بعد اختبار التوافق والحجم؛ musl/native dependencies/globalization قد تسبب اختلافات مقارنة بـ Debian/glibc.
↗

المراجع والقراءة الإضافية

References & further reading

الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)

خريطة التغطية: 27 عنصر من الـ Roadmap ومكان شرحه في الدرس
RoadmapContainers vs Virtual Machines§01
RoadmapImages vs Containers§01
RoadmapDockerfile§03
RoadmapBuild Context§03
RoadmapImage Layers and Build Cache§03
RoadmapMulti-Stage Builds§06
RoadmapPorts§03
RoadmapVolumes and Bind Mounts§07
RoadmapNetworks§03
RoadmapEnvironment Variables§03
RoadmapDocker Compose§03
RoadmapLogs§03
Roadmapdocker exec and Debugging§03
RoadmapHealth Checks§07
RoadmapRestart Policies§07
RoadmapNon-Root Containers§09
RoadmapASP.NET Core Applications in Docker§06
RoadmapDatabase Containers§07
RoadmapPersistent Storage§08
RoadmapProduction Configuration§09
RoadmapImage Optimization§05
RoadmapContainer Registries§09
Suggested.NET Aspire for local orchestration (awareness)§15
SuggestedDev containers§15
SuggestedSDK container publishing§14
SuggestedChiseled / distroless images§15
SuggestedImage vulnerability scanning§09

خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.

محتويات الدرس