SSD Nodes Learn Hosting plans →
راهنماها Matt Connorتوسط Matt Connor

نصب Planka با Docker Compose روی VPS

آموزش استقرار Planka با Docker Compose روی VPS؛ تنظیم Postgres، Traefik، متغیرهای ساخت مدیر و BASE_URL را ببینید تا با خطای ورود پس از نصب روبه‌رو نشوید.

آنچه با self-hosting کردن Planka به دست می‌آورید

با self-hosting کردن Planka، یک Kanban board در اختیار تیم شما قرار می‌گیرد که مدل card، list و label آن برای کاربرانی که قبلاً از Trello استفاده کرده‌اند آشناست و روی یک VPS تحت کنترل شما اجرا می‌شود. محدودیتی برای تعداد seat وجود ندارد و هزینه‌ای به‌ازای هر user دریافت نمی‌شود، چون تنها هزینه، هزینهٔ سرور است. این راهنما Planka را با Docker Compose و پشت Traefik مستقر می‌کند، برای داده‌ها از Postgres و برای هر فایلی که کاربران upload می‌کنند از یک named volume استفاده می‌کند.

Planka 2 تحت Fair Use License اختصاصی این پروژه منتشر می‌شود. خود پروژه این مجوز را source-available، نه open source، توصیف می‌کند. اجرای آن برای پروژه‌های داخلی سازمان خودتان مجاز است. ارائهٔ آن به اشخاص ثالث به‌عنوان یک hosted service تجاری، به مجوز Pro یا Enterprise نیاز دارد.

مخاطب این راهنما تیمی دو تا پنج‌نفره است که از free tier سرویس Trello خارج می‌شود. اگر هنوز دربارهٔ انتخاب board مناسب تصمیم نگرفته‌اید، ابتدا مقایسهٔ جایگزین‌های self-hosted برای Trello را بخوانید. این راهنما فرض می‌کند انتخاب انجام شده است و فقط deploy را پوشش می‌دهد.

به یک VPS نیاز دارید که Docker Engine و Compose plugin روی آن اجرا شود و یک DNS A record نیز به آن اشاره کند. همچنین باید یک نمونهٔ Traefik داشته باشید که از قبل روی همان سرور TLS (transport layer security) را terminate کند. اگر Traefik هنوز روی سرور وجود ندارد، ابتدا یک Traefik reverse proxy را جلوی چند Compose app راه‌اندازی کنید و اگر فایل زیر برایتان ناآشناست، مبانی Docker Compose برای VPS را بخوانید.

میزان منابع مورد نیاز VPS برای Planka چقدر است؟

بخش FAQ فنی این پروژه حداقل 2 GB رم و 10 GB فضای ذخیره‌سازی را برای تیم‌های کوچک توصیه می‌کند، بنابراین این اعداد را به عنوان نقطه شروع در نظر بگیرید، نه یک اندازه‌گیری دقیق.

آنچه در واقع اجرا می‌شود سبک است: یک پردازش Node.js که API و فرانت‌اند کامپایل‌شده را سرویس می‌دهد، و یک سرور Postgres که داده‌ها را نگه می‌دارد و شامل یک پردازش نظارتی به همراه یک پردازش بک‌اند برای هر اتصال باز است. یک پردازش پروکسی کوچک نیز درون کانتینر Planka اجرا می‌شود تا درخواست‌های خروجی آن را فیلتر کند. یک پلن 2 GB با توصیه رم پروژه برای تیم‌های کوچک مطابقت دارد. یک بورد همسایه سبکی است، بنابراین اگر قرار است همان VPS اسناد تیم شما را نیز میزبانی کند، ابتدا برای آن برنامه اندازه‌گیری کنید: اجرای AFFiNE به عنوان یک فضای کاری مشابه Notion به تنهایی به یک جفت گیگابایت نیاز دارد، پیش از آنکه Planka بخواهد از منابع استفاده کند.

پیش از تعیین اندازه حافظه، دیسک را اندازه‌گیری کنید، زیرا پیوست‌ها بخشی هستند که رشد می‌کنند. به جای اعتماد به این پاراگراف، نمونه خود را اندازه‌گیری کنید:

docker stats --no-stream
docker system df -v

دستور اول حافظه و CPU زنده را به ازای هر کانتینر چاپ می‌کند. دستور دوم نشان می‌دهد که هر volume چقدر فضا اشغال کرده است. هر دو خوانش را پس از یک هفته کاری عادی انجام دهید، نه در روز نصب، زیرا یک بورد بدون فعالیت چیزی درباره تیم شما نمی‌گوید.

نوشتن فایل Compose

دایرکتوری را ایجاد کرده و مالکیت آن را در اختیار بگیرید تا دیگر نیازی نباشد این فایل‌ها را از طریق sudo ویرایش کنید.

sudo mkdir -p /opt/planka
sudo chown "$USER":"$USER" /opt/planka
cd /opt/planka

رازها (secrets) را در یک فایل .env در کنار فایل Compose تولید کنید. Compose به‌طور خودکار آن فایل را می‌خواند و مقادیر را جایگزین می‌کند.

umask 077
{
  printf 'SECRET_KEY=%s\n' "$(openssl rand -hex 64)"
  printf 'POSTGRES_PASSWORD=%s\n' "$(openssl rand -hex 24)"
  printf 'ADMIN_PASSWORD=%s\n' "$(openssl rand -hex 12)"
} > .env
chmod 600 .env

استفاده از openssl rand -hex آگاهانه است. یک رشته هگزادسیمال فقط شامل ارقام و حروف a تا f است، بنابراین نمی‌تواند رشته اتصال DATABASE_URL که در آن قرار می‌گیرد را مختل کند. Base64 استاندارد ممکن است شامل اسلش، علامت مثبت و علامت مساوی برای padding باشد، اما هرگز شامل علامت at نمی‌شود؛ کاراکترهایی که در URL اتصال معنای خاصی دارند، نیاز به percent-encoding دارند. الگوی کلی‌تر در نگهداری رازها خارج از فایل Compose پوشش داده شده است.

حالا docker-compose.yml. عبارت kanban.example.com را در هر دو جایی که ظاهر شده، با نام میزبان (hostname) خود جایگزین کنید.

services:
  planka:
    image: ghcr.io/plankanban/planka:2.2.1
    restart: unless-stopped
    volumes:
      - planka-data:/app/data
    environment:
      - BASE_URL=https://kanban.example.com
      - DATABASE_URL=postgresql://planka:${POSTGRES_PASSWORD}@postgres/planka
      - SECRET_KEY=${SECRET_KEY}
      - TRUST_PROXY=true
      - DEFAULT_ADMIN_EMAIL=you@example.com
      - DEFAULT_ADMIN_PASSWORD=${ADMIN_PASSWORD}
      - DEFAULT_ADMIN_NAME=Your Name
      - DEFAULT_ADMIN_USERNAME=admin
    networks:
      - proxy
      - internal
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.planka.rule=Host(`kanban.example.com`)"
      - "traefik.http.routers.planka.entrypoints=websecure"
      - "traefik.http.routers.planka.tls.certresolver=default"
      - "traefik.http.services.planka.loadbalancer.server.port=1337"
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    volumes:
      - db-data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=planka
      - POSTGRES_USER=planka
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    networks:
      - internal
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U planka -d planka"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  planka-data:
  db-data:

networks:
  proxy:
    external: true
  internal:

چهار تصمیم در آن فایل ارزش توضیح دارند، زیرا مواردی هستند که افراد تغییر می‌دهند و سپس پشیمان می‌شوند.

  • هیچ بلوک ports: در سرویس Planka وجود ندارد. Traefik از طریق شبکه proxy به کانتینر دسترسی پیدا می‌کند، بنابراین پورت 1337 هرگز روی میزبان منتشر (publish) نمی‌شود. انتشار آن به هر کسی اجازه می‌دهد پروکسی و گواهی شما را دور بزند.
  • loadbalancer.server.port=1337 پورت داخل کانتینر را نام‌گذاری می‌کند. Planka روی 1337 گوش می‌دهد و نمونه بالادستی (upstream) فقط روی 3000 به آن دسترسی دارد زیرا پورت را به میزبان نگاشت (map) می‌کند. در اینجا هیچ نگاشتی به میزبان وجود ندارد، بنابراین باید پورت کانتینر به Traefik اعلام شود.
  • condition: service_healthy با healthcheck دیتابیس Postgres جفت می‌شود. بدون آن، Planka پیش از اینکه دیتابیس اتصالات را بپذیرد شروع به کار می‌کند، در اولین کوئری خود شکست می‌خورد و خارج می‌شود که به شکل یک crash loop دیده می‌شود. جزئیات فنی در سلامت‌سنجی Compose و ترتیب راه‌اندازی آمده است.
  • سرویس دیتابیس عمداً postgres نام‌گذاری شده است. Planka 2 درخواست‌های خروجی خود را از طریق یک فیلتر داخلی هدایت می‌کند که لیست مسدودسازی پیش‌فرض آن localhost,postgres است. اگر نام سرویس را تغییر دهید، بی‌سروصدا دیتابیس خود را از آن لیست حذف کرده‌اید.

پیش از شروع هر کاری، بررسی کنید که Compose می‌تواند رازهای شما را ببیند:

docker compose config | grep -E 'image:|BASE_URL|POSTGRES_USER'

این دستور فایل را با مقادیر .env که از قبل جایگزین شده‌اند چاپ می‌کند. مقدار خالی به این معنی است که Compose فایل .env را نمی‌خواند، که معمولاً به این دلیل است که دستور را از دایرکتوری دیگری اجرا می‌کنید.

متغیرهای bootstrap مدیر سیستم دقیقاً چه کاری انجام می‌دهند

از نسخه 1.13 به بعد Planka، دیگر حساب کاربری مدیر به‌صورت خودکار برای شما ایجاد نمی‌شود؛ بنابراین در یک دیتابیس تازه، هیچ کاربری برای ورود وجود ندارد. گروه DEFAULT_ADMIN_* یکی از دو روش موجود برای حل این مشکل است.

در زمان راه‌اندازی، Planka به دنبال کاربری می‌گردد که با DEFAULT_ADMIN_EMAIL مطابقت داشته باشد. اگر چنین کاربری وجود نداشته باشد، آن را با استفاده از رمز عبور، نام نمایشی و نام کاربری تعیین‌شده در کنار آن ایجاد می‌کند. در دفعات بعدی راه‌اندازی، Planka حساب کاربری منطبق را با این متغیرها به‌روزرسانی می‌کند، که شامل بازنشانی رمز عبور در زمانی است که DEFAULT_ADMIN_PASSWORD همچنان تنظیم شده باشد.

DEFAULT_ADMIN_EMAIL وظیفه دومی دارد که گاهی باعث سردرگمی کاربران می‌شود. تا زمانی که این متغیر تنظیم شده باشد، نام، نقش یا آدرس ایمیل حساب کاربری مذکور از طریق رابط کاربری قابل تغییر یا حذف نیست. این یک مکانیزم محافظتی برای جلوگیری از قفل شدن دسترسی است و به همین دلیل نمی‌توانید نام یا ایمیل آن حساب را در UI تغییر دهید. برای رفع این محدودیت، متغیر را حذف کرده و سرویس را مجدداً راه‌اندازی کنید تا حساب کاربری به یک مدیر معمولی تبدیل شود که مانند سایر حساب‌ها قابل ویرایش است.

در مورد خط مربوط به رمز عبور باید دقت کنید. هر چیزی که تحت environment: قرار بگیرد، برای هر کسی که بتواند docker inspect را روی کانتینر اجرا کند قابل خواندن است، بنابراین DEFAULT_ADMIN_PASSWORD نباید به‌صورت دائمی در آنجا باقی بماند. وارد سیستم شوید، آن خط را حذف کنید، دوباره docker compose up -d را اجرا کنید و سپس رمز عبور خود را در رابط کاربری تغییر دهید.

روش تمیزتر، صرف‌نظر کردن کامل از این متغیرها است. کل گروه DEFAULT_ADMIN_* را کامنت کنید و سپس حساب کاربری را به‌صورت تعاملی ایجاد کنید:

docker compose run --rm planka npm run db:create-admin-user

این دستور از شما ایمیل، رمز عبور، نام نمایشی و یک نام کاربری اختیاری می‌خواهد و کاربر را مستقیماً در دیتابیس ثبت می‌کند. رمز عبور هرگز در فایل Compose یا محیط پیکربندی‌شده کانتینر قرار نمی‌گیرد. اگر بیش از یک نفر به shell سرور VPS دسترسی دارد، از این روش استفاده کنید. این دستور به دلیل depends_on ابتدا Postgres را بالا می‌آورد، بنابراین روی استکی که هرگز اجرا نشده است نیز کار می‌کند.

هر دو روش، مدیریت رمزهای عبور Planka را به‌صورت دستی باقی می‌گذارند. تا نسخه 2.1.1، نسخه Community می‌توانست احراز هویت را به یک ارائه‌دهنده OIDC مانند Authentik که به‌عنوان سرور single sign-on شخصی شما اجرا می‌شود بسپارد، اما نسخه 2.2.0 که در اوت 2026 منتشر شد، OIDC و SSO را به PLANKA Pro منتقل کرد. آنچه نسخه Community در همان نسخه به دست آورد، احراز هویت دو مرحله‌ای (TOTP) برای حساب‌های محلی است، بنابراین حداقل برای حساب مدیر، آن را فعال کنید.

چرا BASE_URL در صورت عدم تطابق با نام دامنه، باعث اختلال در ورود می‌شود

BASE_URL همان آدرس دقیقی است که کاربران در مرورگر وارد می‌کنند، شامل طرح (scheme) و بدون اسلش در انتها. برای این پشته، این مقدار https://kanban.example.com است. Planka لینک‌های خود و لیست مبدأهای مجاز WebSocket را بر اساس این مقدار می‌سازد؛ به این معنی که یک BASE_URL اشتباه، خطای واضحی به شما نمی‌دهد. در عوض، صفحه‌ای را می‌بینید که بارگذاری می‌شود اما هرگز تکمیل نمی‌شود.

نسخه رایج این مشکل: شما مثال بالادستی (upstream) را کپی می‌کنید، BASE_URL=http://localhost:3000 را به همان صورت باقی می‌گذارید و از طریق HTTPS به دامنه واقعی خود متصل می‌شوید. فرم ورود ارسال شده و اعتبارنامه شما پذیرفته می‌شود، اما برد (board) هرگز نمایش داده نمی‌شود. کنسول توسعه‌دهنده مرورگر را باز کنید؛ خواهید دید که درخواست‌ها به /socket.io/ با شکست مواجه می‌شوند، زیرا سوکت به مبدأ صفحه مرورگر متصل می‌شود، اما محدودیت مبدأ سرور، مبدأ مشتق‌شده از BASE_URL را مجاز می‌داند.

TRUST_PROXY=true نیمه دیگر همین مشکل است. Planka پشت Traefik قرار دارد، بنابراین هر درخواست از طریق آدرس پروکسی و با پروتکل HTTP ساده در شبکه Docker به آن می‌رسد. بدون TRUST_PROXY، برنامه هدرهای X-Forwarded-Proto و X-Forwarded-For که توسط Traefik تنظیم شده‌اند را نادیده می‌گیرد؛ در نتیجه تصور می‌کند اتصال ناامن است و با همه کلاینت‌ها به عنوان یک آدرس IP مشترک برخورد می‌کند. با تنظیم این مقدار، برنامه هدرها را می‌خواند و در مورد طرح اتصال با مرورگر توافق می‌کند.

Traefik درخواست‌های WebSocket را بدون پیکربندی اضافی پروکسی می‌کند، که یکی از دلایل ترجیح آن در اینجا است. در nginx، پروکسی باید هدرهای ارتقا (upgrade)، یعنی proxy_set_header Upgrade $http_upgrade و proxy_set_header Connection "upgrade" را فوروارد کند، در غیر این صورت با همان مشکل توقف بارگذاری اما از دلیلی متفاوت مواجه خواهید شد. این تنظیمات می‌توانند در بلوک عمومی location / قرار بگیرند؛ یک بلوک جداگانه برای /socket.io نیز کارساز است اما الزامی نیست.

انتقال برد به یک نام دامنه جدید در آینده، به معنای تغییر همزمان دو مورد است: مقدار BASE_URL و قانون Host() در Traefik. اگر یکی را تغییر دهید و دیگری را فراموش کنید، دوباره با مشکل توقف بارگذاری مواجه می‌شوید. ارائه Planka از یک مسیر فرعی (subpath) مانند https://example.com/planka از نسخه 2.1.0 به بعد که در مارس 2026 منتشر شد، امکان‌پذیر است. در تگ‌های قدیمی‌تر، از یک زیردامنه (subdomain) اختصاصی استفاده کنید.

محل ذخیره‌سازی فایل‌های پیوست و آواتارها در Planka

نرم‌افزار Planka 2 تمام فایل‌های آپلودشده توسط کاربر را در یک مسیر واحد داخل کانتینر ذخیره می‌کند: /app/data. فایل‌های پیوست، آواتارهای کاربران و تصاویر پس‌زمینه بردها همگی در این مسیر قرار دارند. در نسخه 1 از سه دایرکتوری مجزا استفاده می‌شد؛ بنابراین اگر فایل Compose را از یک راهنمای قدیمی کپی کرده باشید، ممکن است مسیرهایی را mount کرده باشید که دیگر وجود ندارند و در نتیجه، mount داده‌های مورد نظر انجام نمی‌شود.

آن mount واحد، تفاوت بین بردی است که پس از ارتقا سالم می‌ماند و بردی که باعث دردسر می‌شود. ایمیج Docker، مسیر /app/data را به عنوان یک volume تعریف می‌کند؛ بنابراین حذف mount از فایل Compose باعث می‌شود فایل‌های آپلودشده در یک volume ناشناس (anonymous) قرار بگیرند. دستور Compose در طول یک بازسازی معمولی up آن را حفظ می‌کند، اما اجرای down و به دنبال آن up، آن را به‌طور خودکار دوباره متصل نمی‌کند. در این حالت، برد دوباره بالا می‌آید و کارت‌ها سر جایشان هستند، اما تمام لینک‌های پیوست از کار می‌افتند، زیرا ردیف‌های دیتابیس همچنان به فایل‌های موجود در volume قدیمی اشاره دارند.

استفاده از volume نام‌گذاری‌شده در فایل Compose بالا، از این مشکل جلوگیری می‌کند. Bind mount نیز کارساز است و پشتیبان‌گیری از فایل‌ها را با ابزارهای معمولی آسان‌تر می‌کند، اما به یک مرحله اضافی نیاز دارد. پردازش Node داخل کانتینر با UID 1000 اجرا می‌شود، بنابراین اگر مالکیت دایرکتوری روی میزبان (host) متعلق به root باشد، در اولین آپلود با خطای مجوز مواجه خواهید شد:

sudo chown -R 1000:1000 /opt/planka/data

مزایا و معایب این دو روش در تفاوت bind mount و named volume بررسی شده است.

اگر حجم فایل‌های پیوست از فضای دیسک پلن شما فراتر رفت، Planka می‌تواند آن‌ها را از طریق S3_ENDPOINT، S3_BUCKET و متغیرهای کلیدی مربوطه، در فضای ذخیره‌سازی سازگار با S3 بنویسد. این تنظیمات می‌تواند به یک bucket میزبانی‌شده یا یک سرویس ذخیره‌سازی شیء MinIO خودمیزبان روی سروری دیگر اشاره کند. پیش از آنکه تیم شما بردها را پر کند، در این مورد تصمیم بگیرید؛ زیرا فعال‌سازی S3، عملیات خواندن و نوشتن فایل‌ها را به آن backend منتقل می‌کند بدون اینکه فایل‌های آپلودشده قبلی را مهاجرت دهد.

راه‌اندازی استک و بررسی صحت عملکرد

docker compose pull
docker compose up -d
docker compose ps

docker compose ps باید postgres را به عنوان healthy و planka را به عنوان running نشان دهد. اگر Planka در یک حلقه بازراه‌اندازی (restart loop) گیر کرده است، ابتدا اتصال دیتابیس را بررسی کنید، نه خود برنامه را.

docker compose logs -f planka

یک راه‌اندازی اولیه موفق، مهاجرت‌های دیتابیس (migrations) را اجرا می‌کند، اما پیکربندی production مقدار noShip: true را تنظیم کرده و پیام شروع به کاری که پورت 1337 را گزارش می‌دهد، سرکوب می‌کند. برای اطمینان از اینکه طرح‌واره (schema) واقعاً ایجاد شده است، به جای اعتماد به لاگ، مستقیماً از Postgres سوال کنید:

docker compose exec postgres psql -U planka -d planka -c '\dt'

لیستی از جداول که شامل board و card باشد، به این معنی است که مهاجرت‌ها با موفقیت اجرا شده‌اند. پیام "Did not find any relations" به این معنی است که Planka هرگز متصل نشده است؛ بنابراین مقدار DATABASE_URL را با مقادیر POSTGRES_USER و POSTGRES_PASSWORD در فایل .env خود مقایسه کنید.

سپس مسیر (route) را از دستگاه خودتان بررسی کنید، نه از داخل VPS:

curl -I https://kanban.example.com

HTTP/2 200 به این معنی است که Traefik دارای گواهی است و به کانتینر دسترسی دارد. خطای 404 که توسط Traefik ارائه می‌شود به این معنی است که هیچ router با درخواست مطابقت نداشته است: قانون Host() با نام دامنه‌ای که درخواست کرده‌اید مطابقت ندارد یا Traefik برچسب‌ها (labels) را شناسایی نکرده است. خطای 502 به این معنی است که router مطابقت داشته اما Traefik نتوانسته به کانتینر دسترسی پیدا کند، برای مثال به این دلیل که کانتینر به شبکه proxy متصل نیست. اکنون سایت را باز کرده و با حساب کاربری مدیر وارد شوید.

پیش از هر ارتقای نسخه، یک pg_dump بگیرید

دو فضای ذخیره‌سازی مجزا، داده‌های برد شما را نگه می‌دارند، بنابراین پشتیبان‌گیری باید هر دو را پوشش دهد: پایگاه داده Postgres و volume مربوط به planka-data. در حالی که stack در حال اجرا است، از پایگاه داده dump بگیرید.

docker compose exec -T postgres pg_dump -U planka -d planka > "planka-db-$(date +%F).sql"

دستور -T تخصیص pseudo-terminal پیش‌فرض Compose را غیرفعال می‌کند تا خروجی dump در یک جریان متنی ساده باقی بماند.

سپس نوبت به فایل‌های آپلود شده می‌رسد. ابتدا نام واقعی volume را پیدا کنید، زیرا Compose نام دایرکتوری پروژه را به ابتدای آن اضافه می‌کند.

docker volume ls | grep planka
docker run --rm -v planka_planka-data:/data -v "$PWD":/backup alpine \
  tar czf /backup/planka-files-$(date +%F).tgz -C /data .

این پروژه همچنین فایل‌های docker-backup.sh و docker-restore.sh را در مخزن خود ارائه می‌دهد و مستندات رسمی، اجرای آن‌ها را در یک cron job شبانه توصیه می‌کند. هر دو روش مناسب هستند. آنچه مناسب نیست، پشتیبانی است که هرگز آن را بازیابی نکرده‌اید؛ پس یک بار آن را روی یک VPS آزمایشی بازیابی کنید و مطمئن شوید که می‌توانید وارد سیستم شوید و یک پیوست را باز کنید. همین جفت فضای ذخیره‌سازی در هر برنامه Compose که آپلود می‌پذیرد وجود دارد، بنابراین اگر بعداً Chatwoot را روی همان سرور میزبان پشتیبانی خود قرار دادید، روالی که اینجا ایجاد می‌کنید با تغییر جزئی در نام volumeها، قابل استفاده مجدد خواهد بود.

پیش از هر تغییر نسخه، بلافاصله dump بگیرید. پشتیبانی که دیشب گرفته شده با پشتیبانی پیش از مهاجرتی که قصد انجام آن را دارید، یکسان نیست.

ثابت‌سازی تگ‌ها و مطالعه یادداشت‌های انتشار

هر دو تگ ایمیج در آن فایل به‌صورت هدفمند ثابت (pin) شده‌اند.

ghcr.io/plankanban/planka:2.2.1 یک نسخه خاص است که تا اکتبر 2026 به‌روز بوده است. نسخه Community 2.3.0 در تاریخ 4 نوامبر 2026 با اصلاحات امنیتی منتشر شد و توسعه‌دهنده اصلی به‌روزرسانی به آن را توصیه می‌کند. نسخه Community 2.3.1 در تاریخ 5 نوامبر 2026 عرضه شد که مشکل کرش کردن هنگام ویرایش توضیحات کارت در بردهایی با عضو بدون نام کاربری را برطرف می‌کند. latest با هر انتشار جدید توسط توسعه‌دهنده اصلی تغییر می‌کند، بنابراین یک docker compose pull روتین ممکن است باعث اعمال یک مهاجرت اسکیما (schema migration) در زمانی شود که شما انتخاب نکرده‌اید. پیش از تغییر آن شماره، یادداشت‌های انتشار را مطالعه کنید، زیرا تغییرات ساختارشکن (breaking changes) و اصلاحات امنیتی در آنجا شرح داده شده‌اند. نسخه 2.0.3 به‌عنوان یک نسخه امنیتی منتشر شد؛ این دقیقاً همان نوع اطلاعاتی است که می‌خواهید پیش از مواجهه ناگهانی با آن، مطالعه کنید. نسخه 2.2.1 که در اوت 2026 منتشر شد نیز همین‌طور بود: این نسخه یک آسیب‌پذیری path traversal را برطرف می‌کند که به کاربر واردشده اجازه می‌داد فایل‌های دلخواه را در نمونه‌هایی که از ذخیره‌سازی فایل محلی استفاده می‌کنند (که تنظیمات این راهنما نیز همین است) بخواند؛ در گزارش امنیتی، نسخه‌های 2.1.1 و قبل از آن به‌عنوان نسخه‌های آسیب‌پذیر ذکر شده‌اند. اگر از نسخه 2.1.x مهاجرت می‌کنید، ابتدا یادداشت‌های نسخه 2.2.0 را بخوانید، زیرا آن نسخه کاربرانی را که فقط از طریق SSO وارد شده‌اند غیرفعال می‌کند تا زمانی که یک مدیر به آن‌ها رمز عبور بدهد و دوباره فعالشان کند. ثابت‌سازی در اینجا ساده است زیرا توسعه‌دهنده اصلی ایمیج‌ها را منتشر می‌کند، و در مواردی که پروژه‌ای هیچ ایمیجی ارائه نمی‌دهد، شما باید همین نظم را با یک گام اضافی رعایت کنید، همان‌طور که در openGym ساخته‌شده روی سیستم از یک تگ git چک‌اوت‌شده آمده است.

postgres:16-alpine به دلیل مهم‌تری روی یک نسخه اصلی (major version) ثابت شده است. Postgres دایرکتوری داده‌های خود را با فرمتی می‌نویسد که به نسخه اصلی وابسته است و سرور از باز کردن دایرکتوری نوشته‌شده توسط نسخه دیگر خودداری می‌کند. اگر postgres:latest را بنویسید و اجازه دهید تگ از 16 عبور کند، کانتینر اجرا نخواهد شد. برای مثال، ایمیج 17 با این خطا متوقف می‌شود:

FATAL:  database files are incompatible with server
DETAIL:  The data directory was initialized by PostgreSQL version 16, which is not compatible with this version 17.

هیچ داده‌ای از دست نمی‌رود و با ری‌استارت کردن نیز چیزی درست نمی‌شود. انتقال به یک نسخه اصلی جدید Postgres به معنای گرفتن dump از نسخه قدیمی و restore کردن آن در یک دایرکتوری داده جدید در نسخه تازه است، یا اجرای یک pg_upgrade که داده‌ها را بدون نیاز به dump تبدیل می‌کند اما به در دسترس بودن هم‌زمان باینری‌های سرور قدیمی و جدید نیاز دارد، یا استفاده از replication منطقی به سروری که نسخه جدید را اجرا می‌کند و سپس انجام switchover. هر یک از این مسیرها یک مهاجرت برنامه‌ریزی‌شده است، نه یک اثر جانبی از pull کردن ایمیج؛ replication منطقی به سرور قدیمی اجازه می‌دهد تا زمانی که سرور جدید همگام‌سازی شود، به کار خود ادامه دهد.

اگر به‌جای شروع تازه، قصد انتقال یک نصب موجود از Planka 1.x را دارید، آن ارتقا رویه مستند خاص خود را در مستندات پروژه دارد و بدون بک‌آپ تهیه‌شده از قبل، راه بازگشتی به نسخه 1 وجود ندارد.

حالت‌های شکست و پیام‌هایی که مشاهده خواهید کرد

Planka در یک حلقه مدام ری‌استارت می‌شود و لاگ به پایگاه داده اشاره دارد. اعتبارنامه‌ها در DATABASE_URL با محیط Postgres مطابقت ندارند. توجه داشته باشید که POSTGRES_PASSWORD فقط هنگام اولین مقداردهی اولیه دایرکتوری داده اعمال می‌شود، بنابراین اصلاح متغیر پس از یک بوت ناموفق اولیه، تغییری ایجاد نمی‌کند. رمز عبور نقش پایگاه داده را با ALTER ROLE تغییر دهید تا با رمز عبور پیکربندی‌شده مطابقت داشته باشد؛ حذف volume مربوط به db-data فقط برای نصب‌های موقتی که داده‌ای برای حفظ کردن ندارند، یک گزینه محسوب می‌شود.

ورود موفقیت‌آمیز است اما برد (board) هرگز بارگذاری نمی‌شود. مقدار BASE_URL با آدرس موجود در نوار مرورگر مطابقت ندارد، بنابراین سرور مبدأ سوکت را رد می‌کند. کنسول مرورگر درخواست‌های ناموفق به /socket.io/ را نشان می‌دهد.

آپلودها شکست می‌خورند در حالی که سایر بخش‌ها کار می‌کنند. یک bind mount متعلق به root است. دستور sudo chown -R 1000:1000 را روی دایرکتوری میزبان اجرا کرده و کانتینر را ری‌استارت کنید.

فایل‌های پیوست پس از ارتقا ناپدید شده‌اند. مسیر /app/data به volume اصلی آپلودها متصل نشده است. آن volume را دوباره متصل کنید یا فایل‌ها را از نسخه پشتیبان بازیابی کنید، سپس پیش از تغییر مجدد تگ ایمیج، از یک volume نام‌گذاری‌شده استفاده کنید.

Traefik خطای 404 برمی‌گرداند. هیچ روتر (router) با درخواست مطابقت ندارد: قانون Host() با رکورد DNS شما همخوانی ندارد یا برچسب‌ها (labels) هرگز به Traefik نرسیده‌اند. دستور docker compose config برچسب‌ها را پس از جایگزینی نشان می‌دهد، جایی که غلط‌های تایپی نمایان می‌شوند. خطای 502 به این معنی است که مسیر مطابقت داشته اما کانتینر در دسترس نبوده است، بنابراین بررسی کنید که کانتینر در شبکه proxy قرار داشته باشد.

اعلان‌ها یا وب‌هوک‌ها هرگز نمی‌رسند. نسخه 2 از Planka درخواست‌های HTTP خروجی خود را از طریق یک فیلتر داخلی ارسال می‌کند و لیست مسدودسازی پیش‌فرض شامل localhost و postgres است. یک وب‌هوک که به localhost ارسال شود طبق طراحی مسدود می‌شود، و هنگامی که OUTGOING_ALLOWED_HOSTS را تنظیم کنید، هر میزبانی که در آن لیست نباشد نیز مسدود خواهد شد. وب‌هوک را به نام سرویس کانتینر دیگر هدایت کنید و اگر از لیست مجاز (allow list) استفاده می‌کنید، آن نام را به OUTGOING_ALLOWED_HOSTS اضافه کنید؛ به جای اینکه فیلتر را حذف کنید.

هنگامی که برنامه در حال اجرا باشد، بار عملیاتی آن ناچیز است. یادداشت‌های انتشار (release notes) را زیر نظر داشته باشید و پیش از هر ارتقا، از پایگاه داده dump بگیرید. یک ری‌استارت به دلیل وجود restart: unless-stopped، استک را به‌طور خودکار بالا می‌آورد، به شرطی که سرویس Docker در هنگام بوت فعال باشد، و استک‌های Compose که پس از ری‌استارت بازمی‌گردند مواردی را که این اتفاق نمی‌افتد، پوشش می‌دهد.

FAQ

چرا Planka پس از ورود به سیستم، بی‌نهایت در حال بارگذاری می‌ماند؟

اعتبارنامه‌ها پذیرفته شده‌اند اما اتصال زنده (live connection) برقرار نشده است. مرورگر سوکت خود را به مبدأ صفحه باز می‌کند، در حالی که Planka مبدأهای مجاز سوکت خود را از BASE_URL استخراج می‌کند؛ بنابراین اگر این متغیر را روی http://localhost:3000 رها کنید و در عین حال از طریق https://kanban.example.com به سایت دسترسی پیدا کنید، سرور اتصال را رد می‌کند. کنسول توسعه‌دهنده مرورگر، درخواست‌های ناموفق به /socket.io/ را نشان می‌دهد. مقدار BASE_URL را دقیقاً روی آدرس عمومی بدون اسلش انتهایی تنظیم کنید، TRUST_PROXY=true را اضافه کنید تا برنامه هدر X-Forwarded-Proto را از reverse proxy شما بپذیرد، سپس دستور docker compose up -d را اجرا کنید.

چگونه اولین کاربر مدیر (admin) را در Planka ایجاد کنم؟

از نسخه 1.13 به بعد، هیچ مدیر به‌طور خودکار ایجاد نمی‌شود. یا متغیرهای DEFAULT_ADMIN_EMAIL را به همراه رمز عبور، نام و نام کاربری مربوطه تنظیم کرده و stack را استارت کنید، یا دستور docker compose run --rm planka npm run db:create-admin-user را اجرا کرده و به پرسش‌ها پاسخ دهید. دستور تعاملی در سرورهای اشتراکی ایمن‌تر است، زیرا رمز عبور وارد محیط پیکربندی‌شده کانتینر نمی‌شود که docker inspect بتواند آن را بخواند. تنظیم DEFAULT_ADMIN_EMAIL پس از آن، از تغییر نام، نقش و آدرس ایمیل آن حساب جلوگیری کرده و حذف آن از طریق رابط کاربری را مسدود می‌کند. پس از راه‌اندازی، DEFAULT_ADMIN_PASSWORD را حذف کنید، زیرا باقی ماندن آن باعث می‌شود رمز عبور حساب مربوطه در هر بار شروع به کار (startup) بازنشانی شود.

Planka پیوست‌ها و آواتارها را کجا ذخیره می‌کند؟

در Planka 2، تمام فایل‌های آپلود شده شامل پیوست‌ها، آواتارهای کاربران و پس‌زمینه بردها در مسیر /app/data داخل کانتینر قرار دارند. این مسیر را روی یک volume نام‌گذاری‌شده mount کنید. بدون یک mount صریح، ایمیج Docker از یک volume ناشناس استفاده می‌کند که دستور docker compose up پس از docker compose down به‌طور خودکار آن را دوباره متصل نمی‌کند. bind mount نیز کار می‌کند، اما پردازش Node با UID 1000 اجرا می‌شود؛ بنابراین دستور sudo chown -R 1000:1000 را روی دایرکتوری میزبان اجرا کنید، در غیر این صورت آپلودها با خطای مجوز (permission error) مواجه می‌شوند.

Planka برای میزبانی شخصی به چه مقدار RAM نیاز دارد؟

بخش فنی FAQ پروژه برای تیم‌های کوچک حداقل 2 GB رم و 10 GB فضای ذخیره‌سازی توصیه می‌کند. استقرار پیش‌فرض Docker شامل یک پردازش Node، یک سرور Postgres با یک پردازش backend برای هر اتصال باز، و یک پروکسی داخلی Squid برای فیلتر کردن درخواست‌های خروجی است. پس از یک هفته استفاده عادی، دستور docker stats --no-stream را اجرا کنید و بر اساس اعداد به‌دست‌آمده، منابع را تعیین کنید. دیسک را دقیق‌تر از حافظه زیر نظر بگیرید، زیرا حجم پیوست‌ها همواره در حال افزایش است.

چگونه Planka را بدون از دست دادن داده‌ها ارتقا دهم؟

بلافاصله پیش از ارتقا، از دیتابیس dump تهیه کرده و از volume آپلودها آرشیو بگیرید؛ به پشتیبان‌گیری‌های شب گذشته اکتفا نکنید. از docker compose exec -T postgres pg_dump -U planka -d planka > planka-db.sql استفاده کنید و -T را نگه دارید تا تخصیص pseudo-terminal برای خروجی تغییر مسیر داده شده غیرفعال شود. یادداشت‌های انتشار (release notes) مربوط به تمام نسخه‌هایی که از آن‌ها عبور می‌کنید را بخوانید، تگ ایمیج را از latest به یک نسخه خاص تغییر دهید، سپس docker compose pull و docker compose up -d را اجرا کرده و لاگ را برای مشاهده فرآیند migration زیر نظر بگیرید. تگ Postgres را روی نسخه اصلی (major version) خود ثابت نگه دارید، زیرا سرور از باز کردن دایرکتوری داده‌ای که توسط نسخه اصلی دیگری نوشته شده است، خودداری می‌کند.

آیا این مقاله مفید بود؟