Docker Compose తో Planka ను self-host చేయడం ఎలా?

Planka ను self-host చేయడం వల్ల కలిగే ప్రయోజనాలు

Planka ను self-host చేయడం ద్వారా, మీ బృందానికి Trello లో ఉండే కార్డ్, లిస్ట్ మరియు లేబుల్ మోడల్ కలిగిన Kanban బోర్డు లభిస్తుంది. ఇది మీరు నియంత్రించే VPS పై నడుస్తుంది. ఇందులో వినియోగదారుల సంఖ్యపై పరిమితులు ఉండవు మరియు ప్రతి వినియోగదారునికి బిల్లింగ్ ఉండదు, ఎందుకంటే సర్వర్ ఖర్చు మాత్రమే ఉంటుంది. ఈ గైడ్ దీనిని Docker Compose మరియు Traefik ద్వారా డిప్లాయ్ చేస్తుంది. డేటా కోసం Postgres ను మరియు అప్‌లోడ్ చేసిన ఫైళ్ల కోసం named volume ను ఉపయోగిస్తుంది.

Trello యొక్క ఉచిత ప్లాన్ నుండి బయటకు వస్తున్న ఇద్దరు నుండి ఐదుగురు సభ్యులున్న బృందాల కోసం ఈ గైడ్ రూపొందించబడింది. మీరు ఏ బోర్డును ఎంచుకోవాలో ఇంకా నిర్ణయించుకోకపోతే, ముందుగా self-hosted Trello ప్రత్యామ్నాయాల పోలిక చదవండి. ఈ గైడ్ మీరు ఇప్పటికే నిర్ణయం తీసుకున్నారని భావించి, కేవలం డిప్లాయ్‌మెంట్ ప్రక్రియను మాత్రమే వివరిస్తుంది.

మీకు Docker Engine మరియు Compose plugin ఉన్న VPS, మరియు దానికి పాయింట్ చేసే DNS A record అవసరం. అలాగే, ఆ సర్వర్‌లో ఇప్పటికే TLS (transport layer security) ను terminate చేస్తున్న Traefik instance ఉండాలి. ఒకవేళ Traefik ఇంకా లేకపోతే, ముందుగా అనేక Compose అప్లికేషన్ల ముందు Traefik reverse proxy ని సెటప్ చేయండి. కింద ఉన్న ఫైల్ మీకు కొత్తగా అనిపిస్తే, VPS కోసం Docker Compose ప్రాథమిక అంశాలను చదవండి.

Planka కు ఎంత VPS అవసరం?

ఈ ప్రాజెక్ట్ కనీస హార్డ్‌వేర్ అవసరాలను అధికారికంగా ప్రకటించలేదు, కాబట్టి మీరు ఎక్కడైనా చూసే సంఖ్యలను కొలమానంగా కాకుండా ఒక ప్రాథమిక అంచనాగా మాత్రమే పరిగణించండి. హోస్టింగ్ పేజీలలో తరచుగా కనిపించే 2 vCPU మరియు 4 GB అనేది ప్రొవైడర్లు సూచించే సౌకర్యవంతమైన డిఫాల్ట్ మాత్రమే, ప్రాజెక్ట్ నిర్దేశించిన అవసరం కాదు. ఐదుగురు వ్యక్తులు ఉపయోగించే బోర్డుకు ఇది చాలా ఎక్కువ.

వాస్తవానికి నడిచే ప్రక్రియలు చాలా చిన్నవి: API మరియు బిల్డ్ చేసిన frontend ను అందించే ఒక Node.js ప్రాసెస్, మరియు డేటాను నిల్వ చేసే ఒక Postgres ప్రాసెస్. Planka కంటైనర్ లోపల అవుట్‌గోయింగ్ అభ్యర్థనలను ఫిల్టర్ చేయడానికి మూడవ చిన్న ప్రాక్సీ ప్రాసెస్ నడుస్తుంది. 1 vCPU మరియు 2 GB ప్లాన్ ఇద్దరు నుండి ఐదుగురు వ్యక్తులున్న బోర్డుకు సరిపోతుంది, మరియు మిగిలిన మెమరీలో ఎక్కువ భాగం Postgres కాష్‌గా ఉపయోగపడుతుంది.

మెమరీని నిర్ణయించే ముందు డిస్క్ పరిమాణాన్ని నిర్ణయించండి, ఎందుకంటే అటాచ్‌మెంట్‌లు పెరిగే కొద్దీ డిస్క్ స్థలం అవసరమవుతుంది. ఈ పేరాను నమ్మే బదులు మీ స్వంత ఇన్‌స్టన్స్‌ను కొలవండి:

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

మొదటి కమాండ్ ప్రతి కంటైనర్ యొక్క లైవ్ మెమరీ మరియు CPU వినియోగాన్ని చూపుతుంది. రెండవది ప్రతి వాల్యూమ్ ఎంత స్థలాన్ని ఆక్రమిస్తుందో చూపుతుంది. ఈ రీడింగ్‌లను ఇన్‌స్టాల్ చేసిన రోజున కాకుండా, ఒక సాధారణ పని వారం తర్వాత తీసుకోండి, ఎందుకంటే ఖాళీగా ఉన్న బోర్డు మీ టీమ్ పనితీరు గురించి ఏమీ చెప్పదు.

Compose ఫైల్‌ను రాయండి

డైరెక్టరీని సృష్టించి, దానికి యాజమాన్యాన్ని (ownership) తీసుకోండి, తద్వారా మీరు ఈ ఫైళ్లను ఎప్పుడూ sudo ద్వారా ఎడిట్ చేయాల్సిన అవసరం ఉండదు.

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

Compose ఫైల్ పక్కనే ఉన్న .env ఫైల్‌లోకి రహస్యాలను (secrets) రూపొందించండి. 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 పాస్‌వర్డ్ తప్పుడు హోస్ట్‌నేమ్ లాంటి కనెక్షన్ ఎర్రర్‌ను కలిగిస్తుంది, దీనివల్ల మీ సమయం వృథా అవుతుంది. దీనికి సంబంధించిన విస్తృత విధానం Compose ఫైల్ నుండి రహస్యాలను దూరంగా ఉంచడం లో వివరించబడింది.

ఇప్పుడు docker-compose.yml. kanban.example.com ఉన్న రెండు చోట్లా మీ స్వంత హోస్ట్‌నేమ్‌తో భర్తీ చేయండి.

services:
  planka:
    image: ghcr.io/plankanban/planka:2.1.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:

ఆ ఫైల్‌లోని నాలుగు నిర్ణయాలను వివరించడం అవసరం, ఎందుకంటే చాలామంది వాటిని మార్చి తర్వాత ఇబ్బంది పడతారు.

• Planka సర్వీస్‌పై ports: బ్లాక్ లేదు. Traefik కంటైనర్‌ను proxy నెట్‌వర్క్ ద్వారా చేరుకుంటుంది, కాబట్టి 1337 పోర్ట్ హోస్ట్‌పై ఎప్పుడూ పబ్లిష్ చేయబడదు. దీన్ని పబ్లిష్ చేయడం వల్ల ఎవరైనా మీ ప్రాక్సీని మరియు సర్టిఫికేట్‌ను దాటవేసే అవకాశం ఉంటుంది.
• loadbalancer.server.port=1337 కంటైనర్ లోపల ఉన్న పోర్ట్‌ను సూచిస్తుంది. Planka 1337 పోర్ట్‌పై వింటుంది (listens), మరియు అప్‌స్ట్రీమ్ ఉదాహరణలో అది 3000 పోర్ట్‌పై మాత్రమే చేరుకోగలదు ఎందుకంటే అది పోర్ట్‌ను హోస్ట్‌కు మ్యాప్ చేస్తుంది. ఇక్కడ హోస్ట్ మ్యాపింగ్ లేదు, కాబట్టి Traefik కు కంటైనర్ పోర్ట్ గురించి తెలియజేయాలి.
• condition: service_healthy అనేది Postgres హెల్త్‌చెక్‌తో జత చేయబడింది. ఇది లేకపోతే, డేటాబేస్ కనెక్షన్‌లను అంగీకరించకముందే Planka ప్రారంభమై, తన మొదటి క్వెరీలో విఫలమై నిష్క్రమిస్తుంది, ఇది క్రాష్ లూప్ లాగా కనిపిస్తుంది. దీనికి సంబంధించిన మెకానిక్స్ Compose హెల్త్‌చెక్‌లు మరియు స్టార్టప్ ఆర్డరింగ్ లో ఉన్నాయి.
• డేటాబేస్ సర్వీస్‌కు postgres అని పేరు పెట్టడం వెనుక ఒక కారణం ఉంది. Planka 2 తన అవుట్‌గోయింగ్ అభ్యర్థనలను ఒక అంతర్గత ఫిల్టర్ ద్వారా పంపుతుంది, దీని డిఫాల్ట్ బ్లాక్ లిస్ట్ localhost,postgres. మీరు సర్వీస్ పేరు మార్చితే, మీ డేటాబేస్ ఆ జాబితా నుండి నిశ్శబ్దంగా తొలగించబడుతుంది.

ఏదైనా ప్రారంభించే ముందు Compose మీ రహస్యాలను చూడగలదో లేదో తనిఖీ చేయండి:

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

ఇది .env విలువలు ఇప్పటికే ప్రతిక్షేపించబడిన ఫైల్‌ను ప్రింట్ చేస్తుంది. ఖాళీ విలువ ఉందంటే Compose ఆ .env ఫైల్‌ను చదవడం లేదని అర్థం, సాధారణంగా మీరు వేరే డైరెక్టరీ నుండి కమాండ్‌ను రన్ చేస్తున్నప్పుడు ఇలా జరుగుతుంది.

అడ్మిన్ బూట్‌స్ట్రాప్ వేరియబుల్స్ వాస్తవానికి ఏమి చేస్తాయి

Planka 1.13 వెర్షన్ నుండి మీ కోసం ఎటువంటి అడ్మినిస్ట్రేటర్ స్వయంచాలకంగా సృష్టించబడరు, కాబట్టి కొత్త డేటాబేస్‌లో లాగిన్ అవ్వడానికి ఎవరూ ఉండరు. దీన్ని పరిష్కరించడానికి DEFAULT_ADMIN_* గ్రూప్ రెండు మార్గాలలో ఒకటి.

ప్రారంభ సమయంలో, Planka DEFAULT_ADMIN_EMAIL కి సరిపోయే వినియోగదారు కోసం వెతుకుతుంది. అటువంటి వినియోగదారు ఎవరూ లేకపోతే, దానితో పాటు సెట్ చేసిన పాస్‌వర్డ్, డిస్‌ప్లే నేమ్ మరియు యూజర్‌నేమ్ ఉపయోగించి ఒకరిని సృష్టిస్తుంది. ఇది ఖాళీ డేటాబేస్‌పై మొదటి బూట్ సమయంలో జరుగుతుంది, కాబట్టి ఈ వేరియబుల్స్ ఖాతాను నిర్వహించడానికి కాకుండా, ఖాతాను బూట్‌స్ట్రాప్ చేయడానికి ఉపయోగపడతాయి.

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 ఫైల్‌ను లేదా కంటైనర్ ఎన్విరాన్‌మెంట్‌ను తాకదు. VPSకి ఒకటి కంటే ఎక్కువ మందికి షెల్ యాక్సెస్ ఉంటే ఈ మార్గాన్ని అనుసరించండి. depends_on కారణంగా ఈ కమాండ్ ముందుగా Postgresను ప్రారంభిస్తుంది, కాబట్టి ఇది ఇంతకుముందు రన్ అవ్వని స్టాక్‌పై కూడా పనిచేస్తుంది.

ఏ మార్గాన్ని ఎంచుకున్నా, Planka పాస్‌వర్డ్‌లను మీరే మాన్యువల్‌గా నిర్వహించాల్సి ఉంటుంది. ఒకవేళ మీ టీమ్ ఇప్పటికే నాలుగు రకాల క్రెడెన్షియల్స్‌ను కలిగి ఉంటే, Planka లాగిన్‌లను OIDC ప్రొవైడర్‌కు బదిలీ చేయగలదు. ఉదాహరణకు మీ స్వంత సింగిల్ సైన్-ఆన్ సర్వర్‌గా పనిచేసే Authentik ను వాడవచ్చు. బూట్‌స్ట్రాప్ అడ్మిన్ ఖాతాను ప్రొవైడర్ అందుబాటులో లేని సమయాల్లో అత్యవసర ప్రవేశం (break-glass) కోసం ఉంచుకోవచ్చు.

BASE_URL హోస్ట్ నేమ్‌తో సరిపోలకపోతే లాగిన్‌లు ఎందుకు విఫలమవుతాయి

BASE_URL అనేది వినియోగదారులు బ్రౌజర్‌లో టైప్ చేసే ఖచ్చితమైన చిరునామా, ఇందులో స్కీమ్ ఉంటుంది మరియు చివరన స్లాష్ ఉండకూడదు. ఈ స్టాక్ కోసం అది https://kanban.example.com. Planka తన సొంత లింక్‌లను మరియు WebSocket కనెక్షన్‌ను ఆ విలువ నుండే నిర్మించుకుంటుంది, అంటే BASE_URL తప్పుగా ఉంటే మీకు స్పష్టమైన ఎర్రర్ రాదు. బదులుగా, పేజీ లోడ్ అవుతున్నట్లు కనిపిస్తుంది కానీ ఎప్పటికీ పూర్తి కాదు.

సాధారణంగా జరిగే పొరపాటు: మీరు అప్‌స్ట్రీమ్ ఉదాహరణను కాపీ చేసి, BASE_URL=http://localhost:3000ని అలాగే వదిలేసి, మీ అసలు డొమైన్‌లో HTTPS ద్వారా సైట్‌ను యాక్సెస్ చేస్తారు. లాగిన్ ఫారమ్ సబ్మిట్ అవుతుంది మరియు మీ క్రెడెన్షియల్స్ ఆమోదించబడతాయి. కానీ బోర్డు కనిపించదు. బ్రౌజర్ డెవలపర్ కన్సోల్‌ను తెరిచి చూస్తే, /socket.io/కి వెళ్లే అభ్యర్థనలు విఫలమవుతున్నట్లు కనిపిస్తుంది. ఎందుకంటే క్లయింట్ తన లైవ్ కనెక్షన్‌ను localhost:3000కి తెరవాలని సూచించబడింది, కానీ మీ ల్యాప్‌టాప్‌లో ఆ చిరునామా ఏమీ లేదు.

TRUST_PROXY=true అనేది ఇదే సమస్యలో మరో భాగం. Planka, Traefik వెనుక ఉంటుంది, కాబట్టి ప్రతి అభ్యర్థన Docker నెట్‌వర్క్‌లో ప్రాక్సీ చిరునామా నుండి సాధారణ HTTP ద్వారా అందుతుంది. TRUST_PROXY లేకపోతే, అప్లికేషన్ Traefik సెట్ చేసిన X-Forwarded-Proto మరియు X-Forwarded-For హెడర్‌లను పట్టించుకోదు. దీనివల్ల కనెక్షన్ సురక్షితం కాదని భావించి, ప్రతి క్లయింట్‌ను ఒకే షేర్డ్ IP అడ్రస్‌గా పరిగణిస్తుంది. ఇది సెట్ చేసినప్పుడు, అప్లికేషన్ ఆ హెడర్‌లను చదివి, స్కీమ్ విషయంలో బ్రౌజర్‌తో ఏకీభవిస్తుంది.

Traefik ఎటువంటి అదనపు కాన్ఫిగరేషన్ లేకుండానే WebSocketsను ప్రాక్సీ చేస్తుంది, అందుకే ఇక్కడ దీన్ని ఎంచుకోవడం మంచిది. nginxలో అయితే, socket.io కోసం proxy_set_header Upgrade $http_upgrade మరియు proxy_set_header Connection "upgrade" ఉన్న ప్రత్యేక location బ్లాక్ అవసరం, లేకపోతే వేరే కారణంతో అదే విధంగా లోడింగ్ ఆగిపోతుంది.

తర్వాత బోర్డును కొత్త హోస్ట్ నేమ్‌కు మార్చాలంటే రెండు విషయాలను కలిపి మార్చాలి: BASE_URL విలువ మరియు Traefik Host() రూల్. ఒకదాన్ని మార్చి మరొకటి మర్చిపోతే, మళ్ళీ లోడింగ్ సమస్య వస్తుంది. Plankaను https://example.com/planka వంటి సబ్‌పాత్ నుండి సర్వ్ చేయడం మార్చి 2026లో విడుదలైన 2.1.0 వెర్షన్ నుండి సాధ్యమవుతుంది. పాత ట్యాగ్‌ల కోసం, దానికి ప్రత్యేకమైన సబ్‌డొమైన్‌ను కేటాయించండి.

Planka అటాచ్‌మెంట్‌లు మరియు అవతార్‌లను ఎక్కడ నిల్వ చేస్తుంది

Planka 2 వినియోగదారు అప్‌లోడ్ చేసే ప్రతిదాన్ని కంటైనర్‌లోని ఒకే పాత్ /app/data కింద నిల్వ చేస్తుంది. అటాచ్‌మెంట్‌లు, వినియోగదారు అవతార్‌లు మరియు బోర్డ్ బ్యాక్‌గ్రౌండ్ చిత్రాలన్నీ దీని కిందే ఉంటాయి. వెర్షన్ 1 మూడు వేర్వేరు డైరెక్టరీలను ఉపయోగించేది, కాబట్టి పాత గైడ్ల నుండి కాపీ చేసిన Compose ఫైల్ ఇప్పుడు లేని పాత్‌లను మౌంట్ చేస్తుంది, దీనివల్ల అసలైన డేటా డైరెక్టరీ మౌంట్ అవ్వదు.

ఆ ఒక్క మౌంట్ పాయింట్, అప్‌గ్రేడ్ తర్వాత కూడా బోర్డ్ సురక్షితంగా ఉండటానికి లేదా డేటా మొత్తం పోవడానికి మధ్య ఉన్న తేడాను నిర్ణయిస్తుంది. ఒకవేళ /app/data వాల్యూమ్‌లో లేకపోతే, అప్‌లోడ్‌లు కంటైనర్ యొక్క writable layer లోకి వెళ్తాయి. కంటైనర్‌ను రీక్రియేట్ చేసినప్పుడు ఆ లేయర్ తొలగించబడుతుంది, మరియు మీరు ఇమేజ్ ట్యాగ్‌ను మార్చిన ప్రతిసారీ కంటైనర్ రీక్రియేట్ అవుతుంది. అప్పుడు బోర్డ్ చూడటానికి బాగున్నా, కార్డులు అన్నీ ఉన్నా, అటాచ్‌మెంట్ లింక్‌లు పనిచేయవు; ఎందుకంటే డేటాబేస్ రోస్ ఇప్పుడు లేని ఫైళ్లను చూపిస్తుంటాయి.

పైన పేర్కొన్న Compose ఫైల్‌లోని named volume దీనిని నివారిస్తుంది. Bind mount కూడా పనిచేస్తుంది మరియు సాధారణ టూల్స్‌తో ఫైళ్లను బ్యాకప్ చేయడం సులభతరం చేస్తుంది, కానీ దీనికి ఒక అదనపు దశ అవసరం. కంటైనర్‌లోని Node ప్రాసెస్ UID 1000 గా రన్ అవుతుంది, కాబట్టి root యాజమాన్యంలో ఉన్న హోస్ట్ డైరెక్టరీ మొదటి అప్‌లోడ్ సమయంలో పర్మిషన్ ఎర్రర్‌ను ఇస్తుంది:

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

ఈ రెండింటి మధ్య ఉన్న తేడాలను bind mounts against named volumes లో చూడవచ్చు.

ఒకవేళ మీ ప్లాన్‌లోని డిస్క్ సామర్థ్యం కంటే అటాచ్‌మెంట్‌లు పెరిగిపోతే, Planka వాటిని S3_ENDPOINT, S3_BUCKET మరియు సంబంధిత కీ వేరియబుల్స్ ద్వారా S3-compatible స్టోరేజ్‌కు రాయగలదు. ఇది హోస్ట్ చేసిన బకెట్‌కు లేదా మరొక బాక్స్‌లో ఉన్న a self-hosted MinIO object store కు పాయింట్ చేయవచ్చు. టీమ్ బోర్డ్‌ను నింపకముందే దీనిపై నిర్ణయం తీసుకోండి, ఎందుకంటే ఈ సెట్టింగ్ కొత్త అప్‌లోడ్‌లకు మాత్రమే వర్తిస్తుంది.

స్టాక్‌ను ప్రారంభించి, అది పనిచేస్తుందో లేదో తనిఖీ చేయండి

docker compose pull
docker compose up -d
docker compose ps

docker compose ps కమాండ్ postgres ను healthy గా మరియు planka ను running గా చూపాలి. Planka ఒక లూప్‌లో రీస్టార్ట్ అవుతుంటే, అప్లికేషన్‌ను కాకుండా ముందుగా డేటాబేస్ కనెక్షన్‌ను తనిఖీ చేయాలి.

docker compose logs -f planka

మొదటిసారి సరిగ్గా బూట్ అయినప్పుడు, అది డేటాబేస్ మైగ్రేషన్లను రన్ చేసి, సర్వర్ 1337 పోర్ట్‌లో వింటున్నట్లు (listening) తెలియజేస్తుంది. లాగ్‌ను మాత్రమే నమ్మకుండా, నేరుగా Postgres ను అడగడం ద్వారా స్కీమా నిజంగా క్రియేట్ అయిందో లేదో నిర్ధారించుకోండి:

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

board మరియు card ఉన్న టేబుల్ జాబితా కనిపిస్తే, మైగ్రేషన్లు విజయవంతంగా జరిగినట్లు అర్థం. "Did not find any relations" అని వస్తే, Planka కనెక్ట్ కాలేదని అర్థం; కాబట్టి మీ .env లోని POSTGRES_USER మరియు POSTGRES_PASSWORD విలువలతో DATABASE_URL ను సరిపోల్చండి.

ఆ తర్వాత, VPS నుండి కాకుండా మీ స్వంత మెషిన్ నుండి రూట్‌ను తనిఖీ చేయండి:

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

HTTP/2 200 అంటే Traefik వద్ద సర్టిఫికేట్ ఉందని మరియు అది కంటైనర్‌ను చేరుకోగలదని అర్థం. Traefik ద్వారా 404 ఎర్రర్ వస్తుందంటే, రూటర్ లేబుల్స్ సరిపోలడం లేదని అర్థం; సాధారణంగా కంటైనర్ proxy నెట్‌వర్క్‌కు కనెక్ట్ కాకపోవడం వల్ల ఇలా జరుగుతుంది. ఇప్పుడు సైట్‌ను ఓపెన్ చేసి, అడ్మిన్ ఖాతాతో లాగిన్ అవ్వండి.

ప్రతి వెర్షన్ మార్పుకు ముందు pg_dump తీసుకోండి

మీ బోర్డు డేటా రెండు వేర్వేరు చోట్ల నిల్వ చేయబడుతుంది, కాబట్టి బ్యాకప్ ఈ రెండింటినీ కవర్ చేయాలి: Postgres డేటాబేస్ మరియు planka-data వాల్యూమ్. స్టాక్ రన్ అవుతున్నప్పుడే డేటాబేస్‌ను డంప్ చేయండి.

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

-T అనేది ఐచ్ఛికం కాదు. ఇది లేకపోతే, Compose ఒక సూడో-టెర్మినల్‌ను కేటాయిస్తుంది. టెర్మినల్ లేయర్ స్ట్రీమ్‌లోని లైన్ ఎండింగ్స్‌ను మారుస్తుంది, దీనివల్ల రీస్టోర్ చేసేటప్పుడు మధ్యలో విఫలమయ్యే డంప్ ఫైల్ వస్తుంది. ఈ వైఫల్యం వారాల తర్వాత బయటపడుతుంది, ఇది అత్యంత ప్రమాదకరమైన సమయం.

ఆ తర్వాత అప్‌లోడ్లు. ముందుగా అసలైన వాల్యూమ్ పేరును కనుగొనండి, ఎందుకంటే 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 లను కూడా అందిస్తుంది, మరియు అధికారిక డాక్యుమెంటేషన్ వీటిని నైట్లీ క్రోన్ జాబ్ (nightly cron job) లో ఉంచమని సూచిస్తుంది. ఏ పద్ధతినైనా అనుసరించవచ్చు. మీరు ఎప్పుడూ రీస్టోర్ చేయని బ్యాకప్ సరైనది కాదు, కాబట్టి ఒకసారి స్క్రాచ్ VPSలో రీస్టోర్ చేసి, మీరు లాగిన్ అవ్వగలరో లేదో మరియు అటాచ్‌మెంట్‌ను తెరవగలరో లేదో నిర్ధారించుకోండి.

ప్రతి వెర్షన్ మార్పుకు వెంటనే ముందు డంప్ రన్ చేయండి. నిన్న రాత్రి తీసిన బ్యాకప్, మీరు చేయబోయే మైగ్రేషన్‌కు ముందు తీసిన బ్యాకప్‌తో సమానం కాదు.

ట్యాగ్‌లను పిన్ చేయండి మరియు రిలీజ్ నోట్స్‌ను చదవండి

ఆ ఫైల్‌లోని రెండు ఇమేజ్ ట్యాగ్‌లు ఉద్దేశపూర్వకంగానే పిన్ చేయబడ్డాయి.

ghcr.io/plankanban/planka:2.1.1 అనేది ఒక నిర్దిష్టమైన రిలీజ్, ఇది ఆగస్టు 2026 నాటికి ప్రస్తుత వెర్షన్. latest అనేది అప్‌స్ట్రీమ్ వారు కొత్త వెర్షన్‌ను విడుదల చేసినప్పుడల్లా మారుతూ ఉంటుంది, కాబట్టి సాధారణంగా చేసే docker compose pull వల్ల మీరు కోరుకోని సమయంలోనే స్కీమా మైగ్రేషన్ జరగవచ్చు. ఆ నంబర్‌ను మార్చే ముందు రిలీజ్ నోట్స్‌ను చదవండి, ఎందుకంటే బ్రేకింగ్ ఛేంజెస్ (breaking changes) మరియు సెక్యూరిటీ ఫిక్స్‌ల గురించి అక్కడే వివరించబడి ఉంటుంది. వెర్షన్ 2.0.3 ఒక సెక్యూరిటీ రిలీజ్‌గా ప్రచురించబడింది; ఇటువంటి విషయాలను మీరు అనుకోకుండా కాకుండా, ముందుగానే తెలుసుకోవడం మంచిది.

postgres:16-alpine ఒక మేజర్ వెర్షన్‌కు పిన్ చేయబడటానికి బలమైన కారణం ఉంది. Postgres తన డేటా డైరెక్టరీని ఒక నిర్దిష్ట మేజర్ వెర్షన్‌కు సంబంధించిన ఫార్మాట్‌లో రాస్తుంది, వేరే వెర్షన్‌తో రాసిన డైరెక్టరీని సర్వర్ తెరవడానికి నిరాకరిస్తుంది. మీరు postgres:latest అని రాసి, ట్యాగ్‌ను 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 మేజర్ వెర్షన్‌కు మారడం అంటే పాత వెర్షన్ నుండి డేటాను డంప్ చేసి, కొత్త వెర్షన్‌లో కొత్త డేటా డైరెక్టరీలోకి రీస్టోర్ చేయడం. ఇది స్టాక్‌ను ఆపివేసి ప్లాన్ చేసుకుని చేయాల్సిన పని, అంతే కానీ ఇమేజ్ పుల్ చేసినప్పుడు అనుకోకుండా జరిగే పరిణామం కాదు.

మీరు కొత్తగా కాకుండా, ఇప్పటికే ఉన్న Planka 1.x ఇన్‌స్టాలేషన్‌ను అప్‌గ్రేడ్ చేస్తున్నట్లయితే, ఆ అప్‌గ్రేడ్ ప్రక్రియ ప్రాజెక్ట్ డాక్యుమెంటేషన్‌లో ప్రత్యేకంగా వివరించబడింది. ముందుగా బ్యాకప్ తీసుకోకుండా వెర్షన్ 1కి తిరిగి వెళ్లే అవకాశం లేదు.

వైఫల్య రీతులు మరియు మీకు కనిపించే సందేశాలు

Planka లూప్‌లో రీస్టార్ట్ అవుతోంది మరియు లాగ్‌లో డేటాబేస్ పేరు కనిపిస్తోంది. DATABASE_URL లోని ఆధారాలు (credentials) Postgres ఎన్విరాన్‌మెంట్‌తో సరిపోలడం లేదు. గమనిక: POSTGRES_PASSWORD అనేది డేటా డైరెక్టరీని మొదటిసారి ప్రారంభించినప్పుడు మాత్రమే వర్తిస్తుంది, కాబట్టి మొదటిసారి బూట్ విఫలమయ్యాక ఈ వేరియబుల్‌ను సరిదిద్దినా ఫలితం ఉండదు. మీరు db-data వాల్యూమ్‌ను తొలగించి, మళ్ళీ మొదటి నుండి ప్రారంభించాలి.

లాగిన్ విజయవంతమైంది కానీ బోర్డు లోడ్ అవ్వడం లేదు. BASE_URL బ్రౌజర్ బార్‌లోని అడ్రస్‌తో సరిపోలడం లేదు, లేదా TRUST_PROXY లేదు. బ్రౌజర్ కన్సోల్ /socket.io/ కి వెళ్లే అభ్యర్థనలు విఫలమవుతున్నట్లు చూపిస్తుంది.

మిగిలినవన్నీ పనిచేస్తున్నా అప్‌లోడ్‌లు విఫలమవుతున్నాయి. బైండ్ మౌంట్ (bind mount) రూట్ యాజమాన్యంలో ఉంది. హోస్ట్ డైరెక్టరీపై sudo chown -R 1000:1000 రన్ చేసి, కంటైనర్‌ను రీస్టార్ట్ చేయండి.

అప్‌గ్రేడ్ తర్వాత అటాచ్‌మెంట్‌లు కనిపించడం లేదు. /app/data వాల్యూమ్‌లో లేదు, కాబట్టి ఫైల్స్ కంటైనర్ లేయర్‌లో ఉండిపోయాయి, అప్‌గ్రేడ్ సమయంలో అవి తొలగిపోయాయి. బ్యాకప్ నుండి ఫైళ్లను పునరుద్ధరించండి, ఆపై ఇమేజ్ ట్యాగ్‌ను మార్చే ముందు వాల్యూమ్‌ను జోడించండి.

Traefik 404 ఎర్రర్‌ను ఇస్తోంది. కంటైనర్ proxy నెట్‌వర్క్‌లో లేదు, లేదా Host() రూల్ మీ DNS రికార్డ్‌తో సరిపోలడం లేదు. docker compose config సబ్‌స్టిట్యూషన్ తర్వాత లేబుల్స్‌ను చూపిస్తుంది, ఇక్కడే టైపింగ్ తప్పులు బయటపడతాయి.

నోటిఫికేషన్‌లు లేదా వెబ్‌హుక్స్ రావడం లేదు. Planka 2 తన అవుట్‌గోయింగ్ HTTP అభ్యర్థనలను అంతర్గత ఫిల్టర్ ద్వారా పంపుతుంది, మరియు డిఫాల్ట్ బ్లాక్ లిస్ట్ localhost మరియు postgres లను కవర్ చేస్తుంది. ఒకే హోస్ట్‌లోని మరొక కంటైనర్‌కు పంపే వెబ్‌హుక్ డిజైన్ ప్రకారం బ్లాక్ చేయబడవచ్చు. ఫిల్టర్‌ను తొలగించే బదులు OUTGOING_ALLOWED_HOSTS ని సర్దుబాటు చేయండి.

ఒకసారి ఇది రన్ అవ్వడం మొదలయ్యాక, నిర్వహణ భారం తక్కువగా ఉంటుంది. రిలీజ్ నోట్స్‌ను గమనిస్తూ ఉండండి మరియు ప్రతి అప్‌గ్రేడ్‌కు ముందు డేటాబేస్‌ను డంప్ చేయండి. restart: unless-stopped కారణంగా రీబూట్ అయినప్పుడు స్టాక్ స్వయంచాలకంగా తిరిగి వస్తుంది, అయితే Docker సర్వీస్ బూట్ సమయంలో ఎనేబుల్ అయి ఉండాలి. రీబూట్ తర్వాత తిరిగి వచ్చే Compose స్టాక్‌లు అనే విభాగం ఒకవేళ సర్వీస్ రాకపోతే ఏమి చేయాలో వివరిస్తుంది.

FAQ

లాగిన్ అయిన తర్వాత Planka ఎందుకు లోడ్ అవుతూనే ఉంటుంది?

మీ ఆధారాలు (credentials) ఆమోదించబడ్డాయి, కానీ లైవ్ కనెక్షన్ కుదరలేదు. Planka తన WebSocket URLను BASE_URL నుండి నిర్మిస్తుంది. కాబట్టి, మీరు https://kanban.example.com ద్వారా సైట్‌ను చేరుకుంటున్నప్పుడు, ఆ వేరియబుల్ ఇంకా http://localhost:3000 అని ఉంటే, బ్రౌజర్ మీ మెషీన్‌లో లేని అడ్రస్‌కు సాకెట్‌ను తెరవడానికి ప్రయత్నిస్తుంది. డెవలపర్ కన్సోల్ /socket.io/ కి వెళ్లే అభ్యర్థనలు విఫలమవుతున్నట్లు చూపిస్తుంది. BASE_URL ని చివరన స్లాష్ లేకుండా ఖచ్చితమైన పబ్లిక్ అడ్రస్‌కు సెట్ చేయండి. మీ రివర్స్ ప్రాక్సీ నుండి X-Forwarded-Proto హెడర్‌ను యాప్ గుర్తించేలా TRUST_PROXY=true ని జోడించండి. ఆపై docker compose up -d ని రన్ చేయండి.

మొదటి Planka అడ్మిన్ యూజర్‌ను ఎలా సృష్టించాలి?

1.13 వెర్షన్ నుండి ఎటువంటి అడ్మినిస్ట్రేటర్ ఆటోమేటిక్‌గా సృష్టించబడరు. మీరు DEFAULT_ADMIN_EMAIL ని దాని పాస్‌వర్డ్, పేరు మరియు యూజర్‌నేమ్ వేరియబుల్స్‌తో సెట్ చేసి స్టాక్‌ను ప్రారంభించండి, లేదా docker compose run --rm planka npm run db:create-admin-user ని రన్ చేసి అడిగే ప్రశ్నలకు సమాధానం ఇవ్వండి. షేర్డ్ సర్వర్‌లో ఇంటరాక్టివ్ కమాండ్ సురక్షితమైనది, ఎందుకంటే పాస్‌వర్డ్ కంటైనర్ ఎన్విరాన్‌మెంట్‌లోకి వెళ్లదు, అక్కడ docker inspect దానిని చదవలేదు. ఆ తర్వాత DEFAULT_ADMIN_EMAIL ని సెట్ చేసి ఉంచడం వల్ల, ఆ అకౌంట్‌ను ఇంటర్‌ఫేస్ నుండి ఎవరూ ఎడిట్ చేయలేరు లేదా తొలగించలేరు.

Planka అటాచ్‌మెంట్‌లు మరియు అవతార్‌లను ఎక్కడ నిల్వ చేస్తుంది?

Planka 2లో అప్‌లోడ్ చేసిన ఫైల్‌లన్నీ కంటైనర్ లోపల /app/data కింద ఉంటాయి. ఇందులో అటాచ్‌మెంట్‌లు, యూజర్ అవతార్‌లు మరియు బోర్డ్ బ్యాక్‌గ్రౌండ్‌లు ఉంటాయి. ఆ పాత్‌ను ఒక నేమ్డ్ వాల్యూమ్‌పై మౌంట్ చేయండి. అది మౌంట్ చేయకపోతే, ఫైల్‌లు కంటైనర్ యొక్క రైటబుల్ లేయర్‌లో ఉండిపోతాయి. కంటైనర్‌ను మళ్లీ క్రియేట్ చేసినప్పుడు (ప్రతి ఇమేజ్ అప్‌గ్రేడ్‌లో ఇది జరుగుతుంది) అవి తొలగించబడతాయి. బైండ్ మౌంట్ కూడా పనిచేస్తుంది, కానీ Node ప్రాసెస్ UID 1000గా రన్ అవుతుంది, కాబట్టి హోస్ట్ డైరెక్టరీపై sudo chown -R 1000:1000 ని రన్ చేయండి, లేకపోతే పర్మిషన్ ఎర్రర్ వల్ల అప్‌లోడ్‌లు విఫలమవుతాయి.

సెల్ఫ్-హోస్టెడ్ Planka కు ఎంత RAM అవసరం?

ఈ ప్రాజెక్ట్ ఎటువంటి కనీస హార్డ్‌వేర్ అవసరాలను పేర్కొనలేదు. హోస్టింగ్ పేజీలలో కనిపించే 2 vCPU మరియు 4 GB అనేది ఒక ప్రొవైడర్ యొక్క డిఫాల్ట్ మాత్రమే, అది కొలమానం కాదు. చిన్న బోర్డులకు ఇది చాలా ఎక్కువ. ఒక Node ప్రాసెస్ మరియు ఒక Postgres ప్రాసెస్ మాత్రమే మొత్తం వర్క్‌లోడ్, కాబట్టి 1 vCPU మరియు 2 GB ప్లాన్ ఇద్దరు నుండి ఐదుగురు సభ్యుల బృందానికి సరిపోతుంది. సాధారణ వారం తర్వాత docker stats --no-stream ని రన్ చేసి, మీ సొంత గణాంకాల ఆధారంగా సైజును నిర్ణయించుకోండి. మెమరీ కంటే డిస్క్ వినియోగాన్ని నిశితంగా గమనించండి, ఎందుకంటే అటాచ్‌మెంట్‌ల వల్లే డేటా పెరుగుతుంది.

డేటా కోల్పోకుండా Plankaను ఎలా అప్‌గ్రేడ్ చేయాలి?

అప్‌గ్రేడ్‌కు సరిగ్గా ముందు డేటాబేస్‌ను డంప్ చేయండి మరియు అప్‌లోడ్స్ వాల్యూమ్‌ను ఆర్కైవ్ చేయండి; ఇది నిన్నటి షెడ్యూల్‌పై ఆధారపడకూడదు. docker compose exec -T postgres pg_dump -U planka -d planka > planka-db.sql ని ఉపయోగించండి, -T ని అలాగే ఉంచండి, తద్వారా సూడో-టెర్మినల్ రీడైరెక్ట్ చేసిన అవుట్‌పుట్‌ను పాడు చేయదు. మీరు దాటవేసే ప్రతి వెర్షన్ యొక్క రిలీజ్ నోట్స్‌ను చదవండి, ఇమేజ్ ట్యాగ్‌ను latest కి బదులుగా నిర్దిష్ట రిలీజ్‌కు మార్చండి, ఆపై docker compose pull మరియు docker compose up -d ని రన్ చేయండి. మైగ్రేషన్ కోసం లాగ్‌ను గమనించండి. Postgres ట్యాగ్‌ను దాని మేజర్ వెర్షన్‌కే పరిమితం చేయండి, ఎందుకంటే వేరే మేజర్ వెర్షన్ ద్వారా రాసిన డేటా డైరెక్టరీని సర్వర్ తెరవదు.