به‌روزرسانی خودکار Imageهای کانتینر داکر با Watchtower در اوبونتو

کیانا3 هفته پیش

0 59 خواندن این مطلب 13 دقیقه زمان میبرد

مقدمه

Watchtower کانتینری است که کانتینرهای Docker در حال اجرای شما را مانیتور کرده و وقتی Imageهای جدیدتری در رجیستریهایشان موجود باشد، به‌روزرسانی‌شان میکند. به سوکت Docker متصل شده، رجیستریهای Image را در بازههای قابل-تنظیم Poll کرده؛ و وقتی تغییر Digestای را تشخیص میدهد، Image جدید را میکشد (Pull)، کانتینر در حال اجرا را متوقف کرده و جانشینی را با Image به-روز شده شروع میکند. این خودکارسازی برای Homelabها، محیطهای توسعه و بارهای کاری کم-بحرانیتی—which در آن‌ها میخواهید کانتینرها بدون Pull و Restart دستی به-روز بمانند—مفید است.

نکته مهم: پروژه Watchtower در دسامبر ۲۰۲۵ توسط مالکش Archive شده و الان فقط-خواندنی است. مخزن همچنان موجود، Issueها و Discussionها قفل شده و آخرین Release پایدار یعنی v1.7.1 است. بحثهای جامعه (شامل r/docker) اغلب میپرسند Watchtower Deprecated یا Discontinued شده یا نه. تا زمان نگارش، Image همچنان روی Docker Hub و GHCR موجود است و کاربران زیادی هنوز آن را برای محیطهای غیر-بحرانی اجرا میکنند. برای دیپلویهای جدید یا پایپ‌لاینهای پروداکشن با الزامات Rollback، جایگزینهایی مثل Renovate یا بهروزرسانیهای CI/CD-محور را در نظر بگیرید—which بعداً در این tutorial پوشش داده میشوند.

Watchtower انتخاب خوبی است وقتی میخواهید بهروزرسانیهای Image را روی هاست منفرد یا Fleet کوچکی Hands-off داشته باشید—to‌همراه اعلانهای اختیاری و پیکربندی مینیمال. برای محیطهای پروداکشن—which به تایید تغییر، Rollback یا Orchestration بدون-قطعی نیاز دارند—مناسب نیست؛ در آن موارد، رویکرد CI/CD-یکپارچه مناسبتر است.

پیش‌نیازها

برای تکمیل این tutorial به این موارد نیاز دارید:

سرور اوبونتو (22.04 یا بعدتر)—طبق راهنمای راه‌اندازی اولیه سرور با اوبونتو در پارمین کلود—with کاربر غیر root با دسترسی sudo و فایروال فعال.
Docker نصب‌شده روی سرور—با دنبال کردن گامهای ۱ و ۲ راهنمای «نحوه نصب و استفاده از داکر روی اوبونتو» در پارمین کلود. برای Pull کردن Imageها از میرور رجیستری پارمین کلود (hub.cr.parmincloud.ir) استفاده کنید.
اگر قصد تست بهروزرسانی با Image خودتان را دارید، به حساب Docker Hub و آشنایی با Push کردن Imageها نیاز خواهید داشت.
Docker Compose نصب‌شده. روی نسخههای فعلی اوبونتو، Docker Compose v2 پیش‌فرض است (با docker compose—بدون خط تیره—فراخوانی میشود).
برای گام ۶ (HTTP API مربوط به Watchtower)، curl نصب‌شده تا بتوانید بهروزرسانیهای On-Demand را Trigger کنید (sudo apt install curl در صورت نبود).
اگر قصد راهاندازی اعلانهای ایمیلی با Gmail دارید، حساب Gmail با Verification-2-Step فعال و App Password اختصاصی. Google رمزعبور ساده برای SMTP را Deprecated کرده؛ App Passwordها روش پشتیبانیشده باقی ماندهاند.

نکات کلیدی

Watchtower به‌عنوان کانتینری اجرا میشود که سوکت Docker را Mount کرده و رجیستریهای Image را در بازه تنظیمشده Poll میکند؛ وقتی Digest ریموت با Image در-حال-اجرا تفاوت داشته باشد، Image جدید را کشیده، کانتینر را متوقف و کانتینر جدیدی را با Image به-روز شده شروع میکند.
میتوانید مشخص کنید کدام کانتینرها بهروز شوند: با پاس دادن نام کانتینرها به‌عنوان آرگومان یا با Labelها (com.centurylinklabs.watchtower.enable=true همراه --label-enable، یا com.centurylinklabs.watchtower.enable=false برای مستثنی کردن از Instance نظارت-بر-همه).
احراز هویت رجیستری خصوصی از طریق REPO_USER و REPO_PASS (Docker Hub، GHCR) یا Credential Helperهای رجیستر-مشخص (مثلاً AWS ECR) پشتیبانی میشود؛ هرگز اعتبارنامهها را در فایلهای Compose کامیت‌شده به Version Control هارد-کد نکنید.
اعلانها را میتوان از طریق ایمیل (SMTP)، Webhook یعنی Slack یا Webhook عمومی (shoutrrr) فرستاد تا از تشخیص یا اعمال بهروزرسانیها باخبر شوید.
HTTP API مربوط به Watchtower (با --http-api-update فعال و با WATCHTOWER_HTTP_API_TOKEN محافظت میشود) امکان Triggerهای بهروزرسانی On-Demand را میدهد؛ بدون احراز هویت و قوانین فایروال، پورت API را عمومی افشا نکنید.
حالت فقط-مانیتور (--monitor-only یا WATCHTOWER_MONITOR_ONLY=true) Imageهای جدید را چک و اعلان میفرستد—بدون Restart کردن کانتینرها؛ سپس میتوانید بهروزرسانیها را دستی یا با اجرای یکباره --run-once اعمال کنید.
برای پایپ‌لاینهای پروداکشن—which به Rollback، تایید یا دیپلوی بدون-قطعی نیاز دارند—ابزارهای CI/CD-یکپارچه (مثلاً Renovate) را به Watchtower ترجیح بدهید؛ Watchtower برای Homelab، توسعه و پروداکشن کم-بحرانیتی عالی است.

درک نحوه کار Watchtower

Watchtower درون کانتینر Dockerای اجرا شده و با Mount کردن سوکت دیمن Docker (/var/run/docker.sock) درون کانتینر Watchtower، کنترل کانتینرهای هاست را به دست میگیرد. هیچ نرمافزاری روی هاست نصب نمیکند. Watchtower به Mount سوکت Docker نیاز دارد—چون مستقیماً با API دیمن Docker برای فهرست کانتینرها، بازرسی متادیتای Imageها، Pull کردن Imageهای جدید و صادر کردن دستورات Stop و Start—همان عملیاتی که دستی با docker pull و docker run انجام میدهید—ارتباط برقرار میکند.

چرخه حیات بهروزرسانی

چرخه حیات، حلقه Polling است. در هر دور، Watchtower کانتینرهایی را که برای مانیتور پیکربندی شدهاند (همه کانتینرهای در حال اجرا، یا فقط منطبق با نامها یا Labelها) بازرسی میکند. برای هر کانتینر، رجیستری Image (Docker Hub، GHCR، ECR و غیره) را برای Digest تگ Imageِ استفادهشده کوئری میکند. آن Digest را با Digest Imageای که کانتیر در-حال-اجرا از آن ساخته شده مقایسه میکند.

Digest چیست؟ Digest، Hash یکتای SHA256 است که Build دقیق Imageای را شناسایی میکند. دو Image با همان تگ میتوانند Digestهای متفاوتی داشته باشند—if Image بازسازی و دوباره Push شده باشد.

اگر مطابقت داشته باشند، اقدامی انجام نشده و Watchtower تا Poll بعدی میخوابد. اگر تفاوت داشته باشند، Watchtower Image جدید را کشیده، کانتیر در-حال-اجرا را متوقف و کانتینر جدیدی از Image به-روز شده شروع میکند—با همان نام و تگ Image و همان پارامترهایی که کانتیر در ابتدا با آن‌ها شروع شده بود؛ شامل متغیرهای محیطی، Volumeها، شبکهها، Port Bindingها و سیاست Restart. هیچ پیکربندیای حین بهروزرسانی از دست نمیرود. به‌صورت اختیاری، Watchtower میتواند Image قدیمی را بعد از بهروزرسانی موفق حذف کند (--cleanup) تا از انباشت Imageهای بلااستفاده جلوگیری شود.

میتوانید کنترل کنید حلقه هر چند وقت اجرا شود. با Interval مبتنی-بر-زمان، پیش‌فرض ۸۶۴۰۰ ثانیه (۲۴ ساعت) است. با زمانبندی Cron-مانند یعنی --schedule، دقیقاً مشخص میکنید چکها کِی اجرا شوند (مثلاً روزانه ساعت ۴ صبح). نمیتوانید –interval و –schedule را همزمان استفاده کنید. کانتینر Watchtower معمولاً حدود ۱۰-۱۵ مگابایت حافظه مصرف میکند.

  +------------------+
  | Container Running|
  +--------+---------+
           |
           v
  +------------------+
  |  Poll Registry   |
  |  (digest check)  |
  +--------+---------+
           |
           v
  +------------------+
  | Compare Digest   |
  +------------------+
           |
     +-----+-----+
     |           |
     v           v
 No Change    Change Detected
     |           |
     v           v
 +-------+   +--------+
 | Sleep |   | Pull   |
 | until |   | then   |
 | next  |   | Stop   |
 | poll  |   | then   |
 +-------+   |Restart |
 +-------+   +--------+

گام ۱ — اجرای Watchtower با docker run

حداقل به یک کانتینر در-حال-اجرا نیاز دارید تا Watchtower مانیتورش کند. مثال زیر کانتیر طولانی-عمری از Image رسمی اوبونتو میسازد تا بعداً بهروزرسانی‌اش را با Watchtower مشاهده کنید.

کانتینری که در حال اجرا بماند بسازید:

docker run -d \
  --name ubuntu-container \
  ubuntu \
  sleep infinity

Watchtower را شروع و به آن کانتینر اشاره کنید. برای تکرارپذیری از تگ Pin-شده استفاده کنید؛ Release پایدار فعلی 1.7.1 است:

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower:1.7.1 \
  ubuntu-container

-d: اجرا در حالت Detached.
--name watchtower: نام کانتینر برای مدیریت.
-v /var/run/docker.sock:/var/run/docker.sock: برای اینکه Watchtower بتواند با دیمن Docker صحبت کند، الزامی است.
containrrr/watchtower:1.7.1: Image Pin-شده؛ اگر تگ جدیدتری موجود است جایگزینش کنید.
ubuntu-container: فقط این کانتینر Watch میشود؛ برای نظارت بر همه کانتینرهای در-حال-اجرا حذفش کنید.

Docker اگر Image موجود نباشد Pull خواهد کرد. نمونه خروجی:

# Output
Unable to find image 'containrrr/watchtower:1.7.1' locally
1.7.1: Pulling from containrrr/watchtower
...
Status: Downloaded newer image for containrrr/watchtower:1.7.1
container_id

هر دو کانتینر در-حال-اجرا بودن را تأیید کنید:

docker ps

# Output
CONTAINER ID   IMAGE                        COMMAND                  CREATED         STATUS         PORTS      NAMES
watchtower_id   containrrr/watchtower:1.7.1   "/watchtower ubuntu-…"   N seconds ago   Up N seconds   8080/tcp   watchtower
ubuntu_id   ubuntu                      "sleep infinity"         N seconds ago   Up N seconds              ubuntu-container

وقتی Image جدیدتری برای تگی که کانتینرتان استفاده میکند Push شود، Watchtower در Poll بعدی تشخیصش داده، Image را کشیده، ubuntu-container را متوقف و کانتینر جدیدی با Image به-روز شده شروع میکند. به‌طور پیش‌فرض، بازه Poll یعنی ۸۶۴۰۰ ثانیه (۲۴ ساعت) است—مگر با --interval Override شود.

با چک کردن لاگها، شروع درست و مانیتور کردن کانتینر را تأیید کنید:

docker logs watchtower

در شروع تمیز، خروجی مشابه این میبینید:

# Output
time="2024-01-15T10:00:00Z" level=info msg="Starting Watchtower and scheduling first run: 2024-01-15 10:00:00 +0000 UTC"
time="2024-01-15T10:00:00Z" level=info msg="Checking all containers (except explicitly disabled)"
time="2024-01-15T10:00:00Z" level=info msg="Found new containrrr/watchtower:1.7.1 image (sha256:...)"

اگر level=error msg="Could not connect to Docker daemon" دیدید، Mount سوکت مفقود یا نادرست است. کانتینر را متوقف، فلگ -v را تأیید و دوباره شروع کنید.

نکته: Watchtower هنگام اعمال بهروزرسانیها کانتینرها را خودکار Restart میکند. در محیطهای پروداکشن، قبل از فعال کردن بهروزرسانیهای خودکار، رفتار Restart و وابستگیها را تست کنید.

برای توقف و حذف کانتینرهای دمو:

docker stop watchtower ubuntu-container
docker rm watchtower ubuntu-container

خطاهای رایج و معنایشان

Cannot connect to the Docker daemon: Mount یعنی -v /var/run/docker.sock:/var/run/docker.sock مفقود یا مسیر سوکت اشتباه است. با ls -la /var/run/docker.sock روی هاست تأیید کنید.
Error response from daemon: manifest unknown: تگ Imageای که Watchtower چک میکند دیگر در رجیستری وجود ندارد. نام و تگ را با docker inspect <container_name> --format '{{.Config.Image}}' تأیید کنید.
Error response from daemon: toomanyrequests: محدودیت نرخ Docker Hub فعال شده (۱۰۰ Pull بدون-احراز-هویت در ۶ ساعت به‌ازای IP). Watchtower را با REPO_USER و REPO_PASS احراز هویت کنید تا سقف به ۲۰۰ در ۶ ساعت برای حسابهای رایج برسد.
کانتینر Restart میشود اما اپلیکیشن بعد از بهروزرسانی در دسترس نیست: Image به-روزشده ممکن است پورت، Entrypoint یا متغیر محیطی را تغییر داده باشد. docker logs <container_name> را برای خطاهای راهاندازی چک کنید. Watchtower Health Check انجام نمیدهد.

گام ۲ — مانیتور کردن کانتینرهای مشخص با Labelها

دو راه برای کنترل اینکه Watchtower کدام کانتینرها را بهروز کند: پاس دادن نامها (مثل گام ۱) یا Labelها. فیلترینگ Label-محور وقتی مفید است که کانتینرهای زیادی دارید و میخواهید بدون فهرست کردن نامها، Opt-in یا Opt-out کنید.

Opt-in: فقط کانتینرهای دارای Label یعنی enable

Label یعنی com.centurylinklabs.watchtower.enable=true را به کانتینرهایی که میخواهید Watchtower بهروزشان کند اضافه کنید. Watchtower را با --label-enable اجرا کنید تا فقط کانتینرهای دارای این Label را مانیتور کند:

# کانتینری که Watchtower بهروزش میکند (enable=true دارد)
docker run -d \
  --name app-container \
  --label com.centurylinklabs.watchtower.enable=true \
  nginx:alpine

# کانتینری که Watchtower نادیده میگیرد (Label ندارد)
docker run -d \
  --name other-container \
  nginx:alpine

Watchtower را با فیلترینگ Label-محور شروع کنید:

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower:1.7.1 \
  --label-enable

فقط app-container برای بهروزرسانی در نظر گرفته میشود. Label بودن روی کانتینر درست را تأیید کنید:

docker inspect app-container --format '{{json .Config.Labels}}'
# Output
{"com.centurylinklabs.watchtower.enable":"true"}

Opt-out: همه را Watch کن—به‌جز کانتینرهای disable

اگر از --label-enable استفاده نکنید، Watchtower به‌طور پیش‌فرض همه کانتینرهای در-حال-اجرا را Watch میکند. برای مستثنی کردن موارد خاص، com.centurylinklabs.watchtower.enable=false روی آن‌ها بگذارید:

docker run -d \
  --name no-update-container \
  --label com.centurylinklabs.watchtower.enable=false \
  nginx:alpine

Watchtower را در حالت نظارت-بر-همه اجرا کنید:

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower:1.7.1

کانتینری با enable=false در لاگها—to‌عنوان Skipped—در هر دور Poll ظاهر میشود.

مثالهای Docker Compose برای Labelها

الگوی Opt-in:

services:
  app:
    image: nginx:alpine
    container_name: app-container
    labels:
      - com.centurylinklabs.watchtower.enable=true

  other:
    image: nginx:alpine
    container_name: other-container
    # بدون Label — Watchtower این را نادیده میگیرد

  watchtower:
    image: containrrr/watchtower:1.7.1
    container_name: watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: --label-enable --interval 300

الگوی Opt-out:

services:
  app:
    image: nginx:alpine
    container_name: app-container
    # بدون Label — Watchtower بهروزش میکند

  no-update:
    image: nginx:alpine
    container_name: no-update-container
    labels:
      - com.centurylinklabs.watchtower.enable=false

  watchtower:
    image: containrrr/watchtower:1.7.1
    container_name: watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: --interval 300

گام ۳ — استفاده از Watchtower با Docker Compose

میتوانید Watchtower و کانتینرهای اپلیکیشنتان را از فایل Compose منفردی اجرا کنید. مثال زیر از الگوی Opt-in Label-محور و بازه Poll یعنی ۳۰-ثانیهای برای تست استفاده میکند.

دایرکتوری پروژه و فایل Compose بسازید:

mkdir -p ~/watchtower
cd ~/watchtower
nano docker-compose.yml

محتوای زیر را Paste کنید (sammy را با نامکاربری Docker Hub خودتان—if از Image خصوصی استفاده میکنید—جایگزین کنید):

services:
  ubuntu:
    image: ubuntu
    container_name: ubuntu-container
    command: sleep infinity
    labels:
      - com.centurylinklabs.watchtower.enable=true

  custom-test:
    image: sammy/ubuntu-nodejs
    container_name: test-container
    command: sleep infinity
    labels:
      - com.centurylinklabs.watchtower.enable=true

  watchtower:
    image: containrrr/watchtower:1.7.1
    container_name: watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: --interval 30 --label-enable --cleanup

Stack را شروع کنید:

docker compose up -d

شروع Watchtower و مانیتور کردن کانتینرهای درست را تأیید کنید:

docker compose logs watchtower

# Output
watchtower  | time="..." level=info msg="Starting Watchtower and scheduling first run: ..."
watchtower  | time="..." level=info msg="Checking containers with enable label"
watchtower  | time="..." level=info msg="ubuntu-container (ubuntu): up to date"
watchtower  | time="..." level=info msg="test-container (sammy/ubuntu-nodejs): up to date"

بعد از تغییر فایل Compose، کانتینرها را بازسازی کنید:

docker compose up -d --force-recreate

فلگ --cleanup بعد از بهروزرسانی موفق، Imageهای قدیمی را حذف میکند.

گام ۴ — احراز هویت با رجیستریهای خصوصی

Watchtower میتواند از رجیستریهای خصوصی Image Pull کند. اعتبارنامهها را از طریق متغیرهای محیطی یا کانفیگ Docker فراهم میکنید.

Docker Hub (مخازن خصوصی)

REPO_USER و REPO_PASS (نامکاربری Docker Hub و رمزعبور یا Access Token) را تنظیم کنید:

services:
  watchtower:
    image: containrrr/watchtower:1.7.1
    container_name: watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      REPO_USER: your_dockerhub_username
      REPO_PASS: your_dockerhub_password_or_token
    command: --interval 3600 --label-enable

GitHub Container Registry (GHCR)

از نامکاربری GitHub و Personal Access Token یعنی PAT با read:packages استفاده کنید:

environment:
  REPO_USER: your_github_username
  REPO_PASS: your_github_pat

هشدار: اعتبارنامهها را در docker-compose.ymlای که به Version Control کامیت میشود هارد-کد نکنید. از Docker Secrets یا فایل .envای که در .gitignore فهرست شده استفاده و با env_file ارجاعش بدهید.

مثال با فایل .env:

.env (به .gitignore اضافه کنید):

REPO_USER=your_username
REPO_PASS=your_secret

docker-compose.yml:

services:
  watchtower:
    image: containrrr/watchtower:1.7.1
    container_name: watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    env_file:
      - .env
    command: --interval 3600 --label-enable

گام ۵ — پیکربندی اعلانها (ایمیل، Slack، Webhook)

Watchtower میتواند هنگام شروع، یافتن و اعمال بهروزرسانیها اعلان بفرستد. از shoutrrr برای چندین Backend استفاده میکند.

ایمیل (Gmail SMTP)

از Gmail با App Password استفاده کنید (Google رمزعبور ساده را Deprecated کرده):

environment:
  WATCHTOWER_NOTIFICATIONS: email
  WATCHTOWER_NOTIFICATION_EMAIL_FROM: your_gmail@gmail.com
  WATCHTOWER_NOTIFICATION_EMAIL_TO: recipient@example.com
  WATCHTOWER_NOTIFICATION_EMAIL_SERVER: smtp.gmail.com
  WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT: 587
  WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER: your_gmail@gmail.com
  WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD: gmail_app_password

Slack

environment:
  WATCHTOWER_NOTIFICATIONS: slack
  WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL: https://hooks.slack.com/services/YOUR/WEBHOOK/PATH

Webhook عمومی (shoutrrr)

environment:
  WATCHTOWER_NOTIFICATIONS: shoutrrr
  WATCHTOWER_NOTIFICATION_URL: generic+https://your-webhook-endpoint.example.com/notify

اعلان Watchtower چه شکلی است

Watchtower به‌ازای هر دورِ بهروزرسانی—which حداقل یک کانتینر بهروز شده—یکی اعلان میفرستد. پیام Slack شبیه این است:

Watchtower Updates on hostname

Updated containers:
- ubuntu-container (ubuntu:latest): updated from sha256:abc123 to sha256:def456
- test-container (sammy/ubuntu-nodejs:latest): updated from sha256:111aaa to sha256:222bbb

Watchtower v1.7.1

اگر هیچ کانتینری در دور Poll بهروز نشده باشد، اعلانی فرستاده نمیشود. اگر بعد از Pushای اعلانی دریافت نکردید، docker logs watchtower را برای خطاهای SMTP یا Webhook چک کنید.

فقط-مانیتور با اعلان

برای فقط باخبر شدن از بهروزرسانیهای موجود—بدون اعمال—to:

environment:
  WATCHTOWER_MONITOR_ONLY: "true"

سپس بهروزرسانیها را وقتی خودتان انتخاب میکنید اعمال کنید.

گام ۶ — استفاده از HTTP API مربوط به Watchtower برای بهروزرسانیهای On-Demand

Watchtower میتواند HTTP APIای افشا کند تا بهجای انتظار برای Poll بعدی، دور بهروزرسانی را On-Demand Trigger کنید. برای CI/CD یا اسکریپتها مفید است.

API را با --http-api-update فعال و برای احراز هویت Tokenای تنظیم کنید:

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 8080:8080 \
  -e WATCHTOWER_HTTP_API_UPDATE=true \
  -e WATCHTOWER_HTTP_API_TOKEN=your_secret_token \
  containrrr/watchtower:1.7.1

در فایل Compose:

services:
  watchtower:
    image: containrrr/watchtower:1.7.1
    container_name: watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      WATCHTOWER_HTTP_API_UPDATE: "true"
      WATCHTOWER_HTTP_API_TOKEN: your_secret_token
    command: --label-enable

نکته امنیتی: Bind کردن به 127.0.0.1:8080 به‌جای 0.0.0.0:8080، API را فقط به Localhost محدود میکند—which امنترین پیشفرض در راهاندازی تک-هاست است. اگر لازم است از هاست دیگری API را صدا بزنید، پشت Reverse Proxy با TLS قرارش بدهید.

بهروزرسانی را با curl Trigger کنید:

curl -H "Authorization: Bearer your_secret_token" \
  http://localhost:8080/v1/update

# Output
{"updated":["ubuntu-container"],"fresh":[],"failed":[],"skipped":[]}

مثال: Trigger کردن Watchtower از پایپ‌لاین CI/CD بعد از Push Image

در Workflow یعنی GitHub Actions، میتوانید بعد از Push کردن Image جدید، فوراً Watchtower را Trigger کنید:

# .github/workflows/deploy.yml (فقط مرحله مرتبط)
- name: Trigger Watchtower update
  run: |
    curl -f -H "Authorization: Bearer ${{ secrets.WATCHTOWER_TOKEN }}" \
      https://your-host/v1/update

WATCHTOWER_TOKEN را به‌عنوان GitHub Actions Secret ذخیره کنید. فلگ -f باعث میشود curl در پاسخ HTTP خطا با Status غیرصفر خارج شود—پس اگر Trigger به Watchtower نرسد، مرحله Workflow بهشکست-محسوس شکست میخورد.

نکته: HTTP API روی پورت ۸۰۸۰ گوش میدهد. بدون احراز هویت (Token) و قوانین فایروال این پورت را عمومی افشا نکنید؛ وگرنه هر کسی که به پورت برسد میتواند بهروزرسانیها را Trigger کند.

مرجع پیکربندی Watchtower

فلگ	متغیر محیطی	پیش‌فرض	توضیح
`--interval`	WATCHTOWER_POLL_INTERVAL	86400	بازه Poll به ثانیه. با –schedule قابل استفاده نیست.
`--schedule`	WATCHTOWER_SCHEDULE	–	عبارت Cron (۶ فیلد). با –interval قابل استفاده نیست.
`--cleanup`	WATCHTOWER_CLEANUP	false	حذف Imageهای قدیمی بعد از بهروزرسانی.
`--label-enable`	WATCHTOWER_LABEL_ENABLE	false	فقط مانیتور کانتینرهای با enable=true.
`--monitor-only`	WATCHTOWER_MONITOR_ONLY	false	فقط چک و اعلان؛ Restart نکن.
`--run-once`	WATCHTOWER_RUN_ONCE	false	یک دور بهروزرسانی و خروج.
`--http-api-update`	WATCHTOWER_HTTP_API_UPDATE	false	فعالسازی HTTP API.
`--http-api-periodic-polls`	WATCHTOWER_HTTP_API_PERIODIC_POLLS	false	همراه API، Poll دوره‌ای را ادامه بده.
–	WATCHTOWER_HTTP_API_TOKEN	–	Token احراز هویت API.
–	WATCHTOWER_NOTIFICATIONS	–	نوع اعلان: email، slack و غیره.
–	REPO_USER	–	نامکاربری احراز هویت رجیستری.
–	REPO_PASS	–	رمزعبور یا Token.

وقتی هم فلگ (مثلاً در command:) و هم متغیر محیطی تنظیم شده باشند، فلگ تقدم دارد.

Watchtower در مقابل جایگزینها

ابزار	روش بهروزرسانی	پشتیبانی رجیستری	اعلانها	مناسب برای
Watchtower	Docker هاست را Poll، Pull و Restart	Docker Hub، ECR، GHCR	ایمیل، Slack، Webhook	Homelab، توسعه، کم-بحرانیتی
What’s Up Docker (WUD)	رجیستریها را Poll، گزارش یا Trigger	چندین رجیستری	Webhook، Slack	دید و گزارشگری
Renovate	مبتنی-بر-PR، در مخزن	هر رجیستری	GitHub/GitLab	CI/CD، پروداکشن با Rollback
Portainer	UI-محور، دستی یا زمانبندی	هر رجیستری	Built-in و Webhook	تیمهایی که UI را ترجیح میدهند

Watchtower: روی همان هاستِ کانتینرها اجرا، از سوکت Docker استفاده و وقتی Digestهای جدید تشخیص میدهد کانتینرها را Restart میکند. با Git یا CI/CD یکپارچه نمیشود—پس Rollback یا مرحله تایید Built-inای ندارد.
Renovate: با باز کردن Pull Requestهایی که ارجاعات Image در مخزنتان را بهروز میکنند کار میکند. پایپ‌لاین شما بعد از Merge بیلد و دیپلوی میکند—که بازبینی، Rollback از طریق Git و کنترل تغییر را فراهم میکند.
Portainer: Web UI برای مدیریت کانتینرها فراهم میکند که میتواند از UI یا زمانبندی-شده بهروزرسانی کند.

سوالات متداول

۱. آیا Watchtower داکر Deprecated شده؟

مخزن Upstream یعنی containrrr/watchtower در دسامبر ۲۰۲۵ Archive شد و فقط-خواندنی است. پروژه فعالانه نگهداری نمیشود. Image Docker همچنان موجود است و کاربران زیادی هنوز آن را برای بارهای غیر-بحرانی اجرا میکنند. برای دیپلویهای جدید یا بحرانی-پروداکشنی، جایگزینهای فعالانه-نگهداری‌شده را در نظر بگیرید.

۲. با پروژه Watchtower Docker چه شد؟

نگهدارندگان مخزن GitHub را Archive کردند؛ Release جدیدی برنامه‌ریزی نشده. آخرین تگ پایدار v1.7.1 است.

۳. Watchtower چگونه با Docker کار میکند؟

به‌عنوان کانتینری اجرا شده که سوکت Docker هاست را Mount میکند. به‌طور دوره‌ای رجیستریهای Image را برای Digest تگ Imageِ هر کانتینرِ مانیتورشده کوئری میکند. اگر Digest ریموت با مورد استفادهشده توسط کانتیر در-حال-اجرا تفاوت داشته باشد، Image جدید را Pull کرده، کانتیر را Stop و کانتینر جدیدی از Image به-روز شده Start میکند.

۴. آیا Watchtower میتواند از رجیستریهای خصوصی بهروز کند؟

بله. برای Docker Hub و GHCR از REPO_USER و REPO_PASS استفاده کنید. اعتبارنامهها را هرگز در فایلهای Compose در Version Control ذخیره نکنید.

۵. چطور جلوی بهروزرسانی کانتینر مشخصی را بگیرم؟

اگر فهرست نام کانتینرها را به Watchtower پاس بدهید، فقط همان‌ها مانیتور میشوند. برای مستثنی کردن کانتیر وقتی Watchtower همه را Watch میکند، Label یعنی com.centurylinklabs.watchtower.enable=false به آن کانتیر بدهید.

۶. آیا اجرای Watchtower در محیط پروداکشن امن است؟

Watchtower هنگام اعمال بهروزرسانیها کانتینرها را خودکار Restart میکند—which قطعی کوتاهی به‌ازای هر کانتیر ایجاد میکند. Health Check یا Rollback انجام نمیدهد. فقط برای بارهای کم-بحرانیتی—which در آن‌ها Restart خودکار قابل-قبول است—در پروداکشن استفاده کنید.

نتیجه‌گیری

Watchtower روش ساده و مؤثری برای خودکارسازی بهروزرسانیهای Image کانتینر Docker در اوبونتو فراهم میکند—to‌همراه پشتیبانی از رجیستریهای رایج، احراز هویت خصوصی و گزینههای اعلان انعطافپذیر. برای Homelabها، محیطهای توسعه و بارهایی—which در آن‌ها بهحداقلرساندن نگهداری اولویت و Restartهای اتفاقی قابل-قبول است—ایدهآل است. هرچند پروژه دیگر نگهداری نمیشود، برای کاربران زیادی خوب کار میکند—فقط مراقب بده-بستانهای امنیتی و عملیاتی باشید.

برای دیپلویهای بزرگتر یا پروداکشنی—which بدون-قطعی، کنترل تغییر، Rollback یا یکپارچگی با CI/CD را میطلبند—جایگزینهایی مثل Renovate یا پایپ‌لاینهای دیپلوی مدیریت‌شده را در نظر بگیرید. هر انتخابی، همیشه اسرارتان را محافظت و کانتینرهایتان را مانیتور کنید تا محیطتان امن و به-روز بماند.