برنامه روی لپ‌تاپ سالم است؛ حالا باید از بیرون واقعاً به آن رسیدIt works on our laptop—how does a real user reach it?

image را در registry داریم و روی سیستم خودمان هم همه‌چیز کار می‌کند. حالا سؤال عوض شده: کاربر واقعی چطور به این برنامه می‌رسد؟ از اینجا به بعد فقط container مهم نیست؛ image درست باید به سرور برسد، فقط portهای لازم عمومی باشند، درخواست از proxy عبور کند و بعد از هر انتشار بتوانیم ثابت کنیم نسخهٔ تازه واقعاً سالم است.

The image is in a registry. A teammate asks, “Okay, how does a real user reach it?” The problem is no longer just starting a container: the right image must reach the server, public traffic must reach the app, and after a change we need evidence that the new release works.

در این فصل مسیر اصلی Ubuntu VPS است. اگر هنوز VPS نداری، Linux VM می‌تواند بیشتر مراحل Docker، SSH، Compose و proxy را بازتولید کند؛ اما DNS عمومی و HTTPS قابل‌اعتماد برای کاربران به domain واقعی و سروری نیاز دارد که از اینترنت reachable باشد.

Ubuntu on a VPS is our main path. A Linux VM can reproduce most Docker, SSH, Compose, and proxy steps; public DNS and publicly trusted HTTPS, however, require a real domain and a server reachable from the internet.

ورودی عمومی را به proxy بده؛ app لازم نیست مستقیم روی اینترنت باز باشدSend public traffic to the proxy, not directly to the app

فرض کن app داخل container روی 8080 گوش می‌دهد. ساده‌ترین راه این است که همان port را عمومی کنیم، اما معماری تمیزتر این است که فقط reverse proxy روی 80 و 443 دیده شود. proxy درخواست را روی شبکهٔ Docker به نام سرویس app و port داخلی می‌فرستد.

If the app listens on port 8080, must we expose it to the internet? Usually not. A reverse proxy provides an HTTP/HTTPS entry point and forwards requests over Docker networking to the app service and internal port.

Caddy و app روی network مشترک‌اند؛ Caddy به app:8080 وصل می‌شود، نه localhost:8080. localhost در container یعنی خود همان container. پایگاه‌داده روی network جدا می‌ماند و port عمومی ندارد.

Caddy and the app share a network; Caddy connects to app:8080, not localhost:8080. Localhost inside a container means that same container. The database stays on a separate network with no public port.

app.example.com {
    reverse_proxy app:8080
}

با domain واقعی، رکورد A و در صورت استفاده AAAA باید به IP قابل‌دسترسی همین سرور اشاره کنند. اگر 80/443 از اینترنت به Caddy برسند، HTTPS خودکار می‌تواند گواهی عمومی بگیرد و تمدید کند؛ volume دادهٔ Caddy را پایدار نگه دار. DNS نادرست، port مسدود، AAAA قدیمی یا data غیرپایدار این مسیر را می‌شکند.

With a real domain, A and any used AAAA records must point to this reachable server. If internet traffic on 80/443 reaches Caddy, automatic HTTPS can obtain and renew a public certificate; keep Caddy's data volume persistent. Wrong DNS, blocked ports, a stale AAAA, or non-persistent data can break this path.

بدون domain یا دسترسی عمومی، Caddy را با :80 و IP یا شبکهٔ محلی VM به کار ببر. این HTTP تمرینی است، نه HTTPS عمومی؛ گواهی محلی را با گواهی مورداعتماد کاربران اشتباه نگیر.

Without a domain or public reachability, use Caddy on :80 with the VM IP or local network. This is practice HTTP, not public HTTPS; do not confuse a local certificate with one trusted by users.

فصل‌های قبلی را دوباره درس نمی‌دهیم؛ اینجا آن‌ها را روی سرور کنار هم می‌گذاریمCompose holds release configuration together

healthcheck، secret، volume، non-root و read-only را قبلاً یاد گرفته‌ایم. اینجا همان تصمیم‌ها را وارد تعریف deployment می‌کنیم: image نسخه‌دار، app غیرریشه، filesystem محدود، healthcheck، restart policy و فقط proxy با port عمومی. اگر پایگاه‌داده داریم، روی شبکهٔ داخلی و volume خودش می‌ماند.

We do not reteach healthchecks, secrets, volumes, and hardening; we apply them: a versioned image, non-root user, read-only filesystem with required writable paths, healthcheck, restart policy, and proxy as the only service with public ports. The DB stays on an internal network and persistent volume.

services:
  proxy:
    image: caddy:2.11.4
    restart: unless-stopped
    ports: ["80:80", "443:443"]
    volumes:
      - ./proxy/Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    networks: [edge]
  app:
    image: ${APP_IMAGE:?Set APP_IMAGE to an explicit registry image and version}
    user: "10001:10001"
    read_only: true
    tmpfs: ["/tmp:rw,noexec,nosuid,size=16m,uid=10001,gid=10001"]
    restart: unless-stopped
    mem_limit: 384m
    cpus: 1.0
    pids_limit: 128
    expose: ["8080"]
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health', timeout=2)"]
      interval: 20s
      timeout: 3s
      retries: 3
      start_period: 15s
    environment:
      DB_HOST: db
      DB_NAME: app
      DB_USER: app
      DB_PASSWORD_FILE: /run/secrets/db_password
    secrets: [db_password]
    depends_on:
      db:
        condition: service_healthy
    networks: [edge, backend]
  db:
    image: postgres:17
    restart: unless-stopped
    environment:
      POSTGRES_USER: app
      POSTGRES_DB: app
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets: [db_password]
    volumes: ["db_data:/var/lib/postgresql/data"]
    networks: [backend]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 20s
networks:
  edge: {}
  backend:
    internal: true
volumes:
  caddy_data: {}
  caddy_config: {}
  db_data: {}
secrets:
  db_password:
    file: ./secrets/db_password

هدف این نیست که compose.yaml را با هر گزینهٔ ممکن شلوغ کنیم. هر خط باید دلیل عملی داشته باشد و بتوانیم بعداً از روی docker compose config و ps بفهمیم سرور قرار است چه چیزی اجرا کند.

Only the proxy publishes ports; expose does not publish the app port on the host. The healthcheck assumes Python and a /health endpoint; verify the binary exists in your image. Memory, CPU, and PID values are examples, not universal settings; size them from observed use and Chapter 13.

برای تولید واقعی، tag image برنامه، Caddy و پایگاه‌داده را مطابق نسخهٔ آزموده‌شدهٔ پروژه pin کن؛ حتی tag نسخهٔ بزرگ مثل postgres:17 یا caddy:2 می‌تواند با انتشار جزئی جدید جابه‌جا شود. CI باید همان خروجی ساخته‌شده نام‌دار یا digest را برای VPS منتشر کند.

For production, pin the app, Caddy, and database images to the versions tested by the project; even a major tag such as postgres:17 or caddy:2 can move as patch releases appear. CI should publish the same named artifact or digest that the VPS deploys.

انتشار فقط pull و up نیست؛ باید نسخهٔ تازه را از بیرون هم ثابت کنیFollow a release from pull to HTTP response

روی VPS image reference را روی tag مشخصی مثل 1.4.0 می‌گذاریم. اول فایل نهایی Compose را بررسی می‌کنیم، بعد image را pull می‌کنیم و up -d می‌زنیم. تا اینجا فقط می‌دانیم Docker تلاش کرده نسخهٔ تازه را اجرا کند.

Create the deployment files on the VPS and set APP_IMAGE to the exact pushed tag. For a private registry, authenticate securely with a read-only token. Review rendered configuration, then pull and apply.

cd /opt/codenames-app
docker compose config
docker compose pull app
docker compose up -d
docker compose ps
docker compose logs --tail=80 app proxy

مرحلهٔ بعد مهم‌تر است: compose ps، health، لاگ و در نهایت یک درخواست HTTP از بیرون. انتشار زمانی تمام شده که همان مسیری که کاربر طی می‌کند جواب درست بدهد. فقط دیدن «Started» در خروجی Compose برای اعلام موفقیت کافی نیست.

Compose config catches YAML and interpolation errors early; review output for secrets too. Pull fetches the image and up reconciles state with the file; changing an image may recreate a container. Named volumes are not removed.

سه شاهد جدا بگیر: compose ps برای state/health، compose لاگ‌ها برای گفته‌های سرویس و HTTP بیرونی برای مسیر کامل. هیچ‌کدام به‌تنهایی دیگری را ثابت نمی‌کند.

Collect three separate kinds of evidence: compose ps for state/health, compose logs for service output, and external HTTP for the full path. None proves the others.

docker compose ps
docker inspect "$(docker compose ps -q app)" --format '{{.State.Status}} {{if .State.Health}}{{.State.Health.Status}}{{end}}'
docker compose logs --since=10m app proxy
curl -fsS https://app.example.com/health

بدون domain از http://SERVER_IP/health و Caddy روی :80 استفاده کن؛ provider و میزبان firewall باید اجازه دهند. اگر health سالم ولی curl timeout است، DNS/firewall/port proxy را بسنج؛ برای 502 نام سرویس، network مشترک و port داخلی را بررسی کن.

Without a domain use http://SERVER_IP/health and Caddy on :80; provider and host firewalls must allow it. If health passes but curl times out, check DNS, firewalls, and proxy ports; for 502, inspect service name, shared network, and internal port.

Rollback نقشهٔ فرار نیست؛ بخشی از طراحی انتشار استIf the release is bad, rollback is part of deployment

فرض کن 1.4.0 بالا می‌آید اما unhealthy می‌شود یا پاسخ اشتباه می‌دهد. اگر نسخهٔ سالم قبلی 1.3.2 بوده، باید بتوانیم image reference را صریح به همان نسخه برگردانیم و دوباره apply کنیم. «شاید image قبلی هنوز در cache باشد» برنامهٔ rollback نیست.

Suppose 1.4.0 becomes unhealthy after an update. Preserve state, health, logs, and a real request. If 1.3.2 was the known-good version, explicitly restore its image reference; do not rely on an accidental cache. Pull and apply it, then verify version and response.

# Edit .env so APP_IMAGE names :1.3.2
docker compose config
docker compose pull app
docker compose up -d
docker compose ps
docker compose logs --since=10m app
curl -fsS https://app.example.com/health

بعد از rollback همان بررسی‌های انتشار را دوباره انجام می‌دهیم: state، health، لاگ‌ها و HTTP بیرونی. اگر فقط container قبلی را بالا آوردیم ولی درخواست کاربر هنوز خطا می‌گیرد، rollback کامل نشده است.

Rolling back the image does not necessarily reverse a database migration. Schema changes need version compatibility and a backup/restore plan. Do not delete a volume as cleanup; distinguish a code failure from a data change.

یک app container یعنی هنگام جایگزینی، جایی برای فرستادن ترافیک نداریمOne instance means no alternate target

اگر فقط یک نمونهٔ app داریم، هنگام جایگزینی نسخه ممکن است چند لحظه هیچ upstream آماده‌ای پشت proxy نباشد. healthcheck می‌تواند بگوید نمونهٔ تازه آماده شده یا نه، اما خودش نمونهٔ جایگزین نمی‌سازد. restart policy هم اگر فرایند بمیرد دوباره تلاش می‌کند؛ ترافیک را به container دیگری منتقل نمی‌کند.

In a single-container deployment, Compose may stop the old instance for a new image. Until the replacement is ready, Caddy has no ready upstream and some requests may fail. A short gap is not zero downtime.

پس روی معماری تک‌نمونه‌ای عبارت «zero downtime» را بی‌دلیل استفاده نمی‌کنیم. می‌توانیم وقفه را کم کنیم، اما برای بی‌وقفه‌بودن واقعی معمولاً به چند نمونه یا الگوی blue/green و یک نقطهٔ مسیریابی نیاز داریم. پروژهٔ نهایی همین موضوع را عملی‌تر می‌کند.

Reduce impact with predictable startup, a meaningful healthcheck, compatible migrations, and a suitable deployment window. Stronger availability requires multiple instances and traffic shifting: blue/green, rolling, or a load balancer. Project 3 covers the deeper implementation.

وقتی انتشار خراب شد، مسیر را از مرز درست شروع کنStart at the boundary that may have failed

یک خطای deployment ممکن است از registry، SSH، firewall، proxy، app یا storage بیاید. همهٔ سرویس‌ها را restart نکن. اول بپرس درخواست یا image دقیقاً تا کدام مرز جلو رفته است. اگر VPS اصلاً image را pull نکرده، لاگ app چیزی برای گفتن ندارد.

Ask “which boundary failed?” Registry, SSH, firewall, proxy, app, or data? A random restart can hide a symptom without revealing its cause.

Healthcheck آماده‌بودن را می‌سنجد؛ ظرفیت جایگزین را معماری باید بسازدReplacing one container can leave a short gap

وقتی Compose یک app تک‌نمونه را recreate می‌کند، ممکن است قبلی قبل از آماده‌شدن کامل نمونهٔ تازه کنار برود. این فاصله کوچک هم downtime است. healthcheck و restart policy اطلاعات و بازیابی فرایند می‌دهند، اما به‌تنهایی availability چندنمونه‌ای نمی‌سازند.

With only one app instance, Compose usually stops the old container and creates a new one. Requests may fail in between. Healthchecks and restart policies help detect and recover, but they do not route that traffic to another instance.

قبل از deploy، خود سرور باید قابل‌اعتماد و قابل‌مدیریت باشدFirst, make the server manageable

یک VPS تازه فقط یک IP و راه ورود است. قبل از آوردن app، دسترسی SSH را با key مرتب می‌کنیم، سیستم را به‌روز می‌کنیم، Docker Engine را از مسیر رسمی نصب می‌کنیم و firewall را طوری می‌بندیم که فقط ورودی‌های واقعاً لازم باز باشند.

You have a fresh VPS, an IP address, and an initial account. Before shipping the app, we establish dependable access, install Docker from its official repository, and allow only the required inbound traffic.

SSH با کلید؛ private key روی دستگاه خودت می‌ماندSSH keys; keep the private key on your own machine

در این معماری معمولاً SSH، HTTP و HTTPS ورودی‌های عمومی‌اند؛ پایگاه‌داده نیست. همچنین Docker daemon را روی TCP عمومی باز نمی‌کنیم. دسترسی به daemon قدرت زیادی روی میزبان می‌دهد و باید همان‌قدر جدی گرفته شود.

Create a key on your laptop or use a protected existing one; install the public key on the VPS and keep the private key on your own machine. Never copy it into the project, image, Git, or server project directory. After confirming key-based login, you may restrict password login according to server policy; keep the current SSH session open until the new path is verified.

ssh -i ~/.ssh/id_ed25519 deploy@SERVER_IP

جایگزین‌کردن IP با مقدار VPS را فراموش نکن. اگر اتصال شکست خورد، ابتدا username، آدرس و نصب public key را بسنج؛ private key را به سرور کپی‌کردن راه‌حل نیست.

Replace the address with your VPS IP. If login fails, check the username, address, and installed public key first; copying the private key to the server is not the fix.

اگر provider هنگام ساخت VPS کلید را نصب نکرده، با حساب مدیریتی اولیه یک حساب deploy بساز و فقط public key را در authorized_keys بگذار. مسیر فایل کلید عمومی را با فایل خودت جایگزین کن.

If the provider did not install the key during VPS creation, use the initial administrative account to create deploy and place only the public key in authorized_keys. Replace the public-key path with your own file.

sudo adduser --disabled-password --gecos "" deploy
sudo install -d -o deploy -g deploy -m 0700 /home/deploy/.ssh
sudo install -o deploy -g deploy -m 0600 /path/to/deploy_key.pub /home/deploy/.ssh/authorized_keys

فایل .pub عمومی است و private key کنار آن نیست؛ پس از نصب، از نشست دیگری ورود deploy را آزمایش کن. مجوزهای سخت‌گیرانه روی پوشه و فایل باعث می‌شود SSH کلید را بپذیرد.

The .pub file is public; its private counterpart does not belong beside it. Test deploy login from a second session after installation. Restrictive directory and file permissions let SSH accept the key.

به‌روزرسانی Ubuntu و نصب Docker EngineUpdate Ubuntu and install Docker Engine

Docker نصب Ubuntu را از مخزن رسمی apt مستند می‌کند: کلید امضای مخزن، apt source و سپس Engine، CLI، Buildx و Compose plugin. جزئیات repository ممکن است با codename اوبونتو تغییر کند؛ صفحهٔ رسمی را برای نسخهٔ سرورت دنبال کن. convenience script را مسیر اصلی نصب production قرار نده.

Docker documents Ubuntu installation through its official apt repository: repository signing key, apt source, then Engine, CLI, Buildx, and Compose plugin. Repository details can vary with the Ubuntu codename; follow the official instructions for your server release. Do not make the convenience script your production installation path.

sudo apt update
sudo apt upgrade
sudo apt install ca-certificates curl
# Configure Docker's official apt repository for this Ubuntu release.
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl status docker
sudo docker run hello-world

بخش ثبت کلید و apt source را عمداً به راهنمای رسمی واگذار می‌کنیم، چون باید codename درست انتخاب شود. hello-world ثابت می‌کند daemon توانسته image بگیرد و container اجرا کند؛ هنوز دربارهٔ برنامه یا مسیر عمومی چیزی نمی‌گوید.

Repository key and apt-source setup is deliberately delegated to the official guide so the correct codename is used. hello-world proves the daemon fetched an image and ran a container; it says nothing yet about the app or public traffic.

کاربر deploy و اختیار DockerThe deploy user and Docker authority

یک حساب جدا مثل deploy و SSH key بساز تا مالکیت فایل‌های انتشار روشن باشد. اما عضویت در گروه docker اختیار بسیار بالایی، عملاً نزدیک به root میزبان، می‌دهد؛ این گروه مرز امنیتی کم‌خطر نیست. فقط به کاربر کاملاً مورداعتماد بده، وگرنه Docker را با sudo اجرا کن. Docker daemon را با TCP عمومی و بدون محافظت هرگز در دسترس نگذار.

Create a separate account such as deploy with an SSH key so release-file ownership is clear. But membership in the docker group grants very powerful access, effectively close to host root; it is not a low-risk security boundary. Give it only to a fully trusted user; otherwise use Docker through sudo. Never expose the Docker daemon through unprotected public TCP.

فایروال را بررسی کن؛ خاموشش نکنReview the firewall; do not switch it off

ورودی عمومی این معماری معمولاً SSH برای مدیریت و 80/443 برای proxy است. درگاه پایگاه‌داده را عمومی نمی‌کنیم؛ app از شبکهٔ داخلی Docker به آن می‌رسد. VPS ممکن است فایروال ارائه‌دهنده هم داشته باشد، پس میزبان و provider را جدا بررسی کن. پیش از فعال‌کردن UFW، SSH را مجاز کن و نشست فعلی را باز نگه دار.

Public inbound access for this architecture is usually SSH for administration and ports 80/443 for the proxy. The database stays private; the app reaches it over an internal Docker network. A VPS may also have a provider firewall, so inspect host and provider controls separately. Allow SSH before enabling UFW and keep the current session open.

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw status verbose
sudo ufw enable

سرور جای build نیست؛ همان image آزموده‌شده را اجرا کنShip a release; do not turn the server into a build machine

کد روی ماشین توسعه یا CI build و test می‌شود، بعد image با tag مشخص به registry می‌رود. VPS همان خروجی ساخته‌شده را pull می‌کند. این کار باعث می‌شود چیزی که روی سرور اجرا می‌شود همان خروجی‌ای باشد که قبل‌تر بررسی کرده‌ایم، نه build تازه‌ای با شرایط ناشناخته روی سرور.

Build and test source on a development machine or CI, assign an explicit tag, push it, and let the VPS pull that artifact. Avoiding production builds on the VPS means the server needs no compiler, source tree, or build tools, and the tested image is the image that runs—making releases easier to reproduce and compare.

docker build -t registry.example.com/team/my-app:1.4.0 .
docker run --rm registry.example.com/team/my-app:1.4.0
docker push registry.example.com/team/my-app:1.4.0

وقتی build را از VPS بیرون نگه می‌داریم، سرور هم به source tree و build tools کمتری نیاز دارد و rollback واضح‌تر می‌شود: فقط image reference را به نسخهٔ شناخته‌شدهٔ قبلی برمی‌گردانیم.

Starting an image is not a substitute for testing its endpoint. If the VPS architecture differs from the build machine, build for the server platform or publish a multi-platform image. Pull an explicit tag such as 1.4.0; latest is a moving pointer and does not provide a traceable rollback. A digest can identify the exact artifact.

برای registry خصوصی، با token محدود به pull وارد شو. از ورود تعاملی یا --password-stdin استفاده کن؛ token را در history، Compose یا Git نگذار. فایل Docker تنظیمات کاربر ممکن است اعتبارنامه داشته باشد، پس مجوزش را محافظت کن.

For a private registry, authenticate with a pull-scoped token. Use interactive login or --password-stdin; do not put the token in history, Compose, or Git. The user's Docker config may contain credentials, so protect its permissions.

روی سرور هر چیز جای مشخص داشته باشدGive server files a clear home

برای مثال فایل‌های deployment را زیر /opt/codenames-app می‌گذاریم: Compose، تنظیمات proxy، فایل‌های غیرحساس، secretها با permission محدود و پوشهٔ پشتیبان. این اسم و ساختار قانون جهانی نیست؛ نکته این است که نفر بعد بتواند بدون حدس بفهمد هر چیز کجاست.

We use /opt/codenames-app/ as an example, not a universal rule. The important points are that deploy can manage release files, secrets are readable only by the accounts that need them, and backups are protected from accidental deletion.

/opt/codenames-app/
├── compose.yaml
├── .env                 # image/version; not secret values
├── proxy/Caddyfile
├── secrets/             # protected host files; never commit
└── backups/             # copy off-server too

sudo install -d -o deploy -g deploy -m 0750 /opt/codenames-app
sudo install -d -o root -g deploy -m 0750 /opt/codenames-app/secrets
sudo install -d -o deploy -g deploy -m 0750 /opt/codenames-app/proxy /opt/codenames-app/backups

مالکیت فایل‌ها هم بخشی از deployment است. کاربر deploy باید بتواند فایل‌های لازم را به‌روزرسانی کند، اما secret یا پشتیبان نباید بی‌دلیل برای همه خواندنی باشند. «روی سرور هست» جایگزین طراحی permission نیست.

Pass real secrets using the Chapter 09 pattern, not in the image or .env. Persistent data has a separate lifecycle: an app update must not erase the database. Before risky changes, have a restorable backup; a directory named backups is not proof of a backup.