Docker Compose ile Planka Kurulumu ve Yapılandırması
Planka uygulamasını Docker Compose, Postgres ve Traefik kullanarak VPS üzerinde dağıtın. Giriş hatalarını önlemek için kritik BASE_URL ayarını ve admin değişkenlerini öğrenin.
Planka self-hosting ile elde ettikleriniz
Planka'yı kendi sunucunuzda barındırmak, ekibinize Trello'dan aşina olduğunuz kart, liste ve etiket modeline sahip bir Kanban panosu sunar; üstelik bu pano tamamen sizin kontrolünüzdeki bir VPS üzerinde çalışır. Kullanıcı başına ücretlendirme veya kişi sınırı yoktur, çünkü tek maliyet sunucu gideridir. Bu rehber, uygulamayı Docker Compose ile Traefik arkasında, veriler için Postgres kullanarak ve yüklenen dosyalar için adlandırılmış bir volume tanımlayarak dağıtır.
Planka 2, projenin kendi Fair Use License lisansı altında dağıtılmaktadır; proje bunu açık kaynak yerine "kaynak erişilebilir" (source-available) olarak tanımlar. Uygulamayı kendi organizasyonunuzun iç projeleri için çalıştırmanıza izin verilir. Üçüncü taraflara ticari bir barındırma hizmeti olarak sunmak için Pro veya Enterprise lisansı gereklidir.
Bu rehber, Trello'nun ücretsiz planından ayrılan iki ila beş kişilik ekipler için hazırlanmıştır. Hangi panoyu kullanacağınıza henüz karar vermediyseniz, önce self-hosted Trello alternatiflerinin karşılaştırmasını okuyun. Bu rehber, seçimin yapıldığını varsayar ve yalnızca dağıtım sürecini kapsar.
Docker Engine ve Compose eklentisi yüklü bir VPS'e ve bu sunucuya işaret eden bir DNS A kaydına ihtiyacınız vardır. Ayrıca, ilgili sunucuda TLS (transport layer security) sonlandırması yapan bir Traefik örneğinizin halihazırda çalışıyor olması gerekir. Eğer Traefik henüz kurulu değilse, önce birden fazla Compose uygulaması önünde bir Traefik reverse proxy kurulumunu tamamlayın; aşağıdaki dosya yapısı size yabancı geliyorsa VPS için Docker Compose temelleri rehberine göz atın.
Planka ne kadar VPS kaynağına ihtiyaç duyar?
Projenin teknik SSS bölümü, küçük ekipler için en az 2 GB RAM ve 10 GB depolama alanı önermektedir; bu nedenle bu değerleri kesin bir ölçümden ziyade bir başlangıç noktası olarak kabul edin.
Çalışan süreçler oldukça küçüktür: API'yi ve derlenmiş arayüzü sunan bir Node.js süreci ile verileri tutan bir Postgres sunucusu. Postgres, bir denetleyici sürecin yanı sıra her açık bağlantı için bir arka uç süreci çalıştırır. Planka container'ı içerisinde, giden istekleri filtrelemek için küçük bir proxy süreci de çalışır. 2 GB'lık bir plan, projenin küçük ekipler için önerdiği RAM miktarıyla uyumludur. Bir pano sistemi hafif bir komşudur; bu nedenle aynı VPS üzerinde ekibinizin belgelerini de barındırmayı planlıyorsanız, önce o uygulamanın boyutunu hesaplayın: Notion tarzı bir çalışma alanı olarak AFFiNE çalıştırmak, Planka'dan önce kendi başına birkaç gigabaytlık bir alan gerektirir.
Disk boyutunu bellekten önce belirleyin, çünkü ekler zamanla büyüyen kısımdır. Bu paragrafa güvenmek yerine kendi instance'ınızı ölçümleyin:
docker stats --no-stream
docker system df -vİlk komut, her container için anlık bellek ve CPU kullanımını yazdırır. İkincisi ise her bir volume'ün ne kadar alan kapladığını gösterir. Her iki ölçümü de kurulum gününde değil, normal bir çalışma haftasının ardından alın; çünkü boş bir pano ekibinizin kullanımı hakkında size bilgi vermez.
Compose dosyasını yazın
Dizini oluşturun ve sahipliğini alın; böylece bu dosyaları hiçbir zaman sudo aracılığıyla düzenlemek zorunda kalmazsınız.
sudo mkdir -p /opt/planka
sudo chown "$USER":"$USER" /opt/planka
cd /opt/plankaSecret değerlerini Compose dosyasının yanındaki bir .env dosyasına oluşturun. Compose bu dosyayı otomatik olarak okur ve değerleri yerine yerleştirir.
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 .envopenssl rand -hex kullanımı bilinçlidir. Bir onaltılık (hex) dizge yalnızca rakamları ve a'dan f'ye kadar olan harfleri içerir, bu nedenle içine yapıştırıldığı DATABASE_URL bağlantı dizgesini bozamaz. Standart Base64 eğik çizgi, artı işareti ve dolgu eşittir işareti içerebilir ancak hiçbir zaman "at" işareti içermez; bağlantı URL'sinde özel anlamı olan karakterlerin yüzde kodlamasına (percent-encoding) ihtiyacı vardır. Daha geniş kapsamlı yöntem secret'ları Compose dosyasının dışında tutma bölümünde ele alınmıştır.
Şimdi docker-compose.yml. kanban.example.com ifadesini, göründüğü her iki yerde de kendi ana makine adınızla (hostname) değiştirin.
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:Bu dosyadaki dört karar açıklanmaya değerdir; çünkü insanlar bunları değiştirip sonrasında pişman olmaktadır.
- Planka servisinde
ports:bloğu yoktur. Traefik, konteynereproxyağı üzerinden ulaşır, bu nedenle 1337 numaralı port ana makinede hiçbir zaman dışarıya açılmaz (publish edilmez). Portu dışarıya açmak, herkesin proxy'nizi ve sertifikanızı atlamasına olanak tanır. loadbalancer.server.port=1337, konteyner içindeki portu belirtir. Planka 1337 numaralı portu dinler ve yukarı akış (upstream) örneği, portu ana makineye eşlediği için ona yalnızca 3000 numaralı port üzerinden ulaşır. Burada bir ana makine eşlemesi yoktur, bu nedenle Traefik'e konteyner portunun bildirilmesi gerekir.condition: service_healthy, Postgres sağlık kontrolü (healthcheck) ile eşleşir. Bu olmadan Planka, veritabanı bağlantıları kabul etmeden önce başlar, ilk sorgusunda başarısız olur ve kapanır; bu durum bir çökme döngüsü (crash loop) gibi görünür. Mekanizmalar Compose sağlık kontrolleri ve başlatma sıralaması bölümünde açıklanmıştır.- Veritabanı servisi kasıtlı olarak
postgresşeklinde adlandırılmıştır. Planka 2, kendi giden isteklerini varsayılan engelleme listesilocalhost,postgresolan dahili bir filtre üzerinden yönlendirir. Servisi yeniden adlandırırsanız, veritabanınızı sessizce bu listeden çıkarmış olursunuz.
Herhangi bir şeyi başlatmadan önce Compose'un secret'larınızı görüp göremediğini kontrol edin:
docker compose config | grep -E 'image:|BASE_URL|POSTGRES_USER'Bu komut, .env değerleri halihazırda yerleştirilmiş olan dosyayı yazdırır. Boş bir değer, Compose'un .env dosyasını okumadığı anlamına gelir; bu durum genellikle komutu farklı bir dizinden çalıştırmanızdan kaynaklanır.
Yönetici bootstrap değişkenlerinin işlevi
Planka 1.13 sürümünden itibaren otomatik olarak yönetici oluşturulmamaktadır; bu nedenle yeni bir veritabanında giriş yapabilecek kimse bulunmaz. DEFAULT_ADMIN_* grubu, bu durumu düzeltmenin iki yolundan biridir.
Planka başlatılırken DEFAULT_ADMIN_EMAIL ile eşleşen bir kullanıcı arar. Eğer böyle bir kullanıcı yoksa, yanında belirtilen parola, görünen ad ve kullanıcı adını kullanarak bir hesap oluşturur. Sonraki başlatmalarda, DEFAULT_ADMIN_PASSWORD ayarlı kaldığı sürece, bu değişkenlerden gelen bilgilerle eşleşen hesabı günceller ve parolasını sıfırlar.
DEFAULT_ADMIN_EMAIL, kullanıcıların sıkça gözden kaçırdığı ikinci bir işlevi yerine getirir. Değişken ayarlı kaldığı sürece, bu değişkenle belirtilen hesabın adı, rolü veya e-posta adresi arayüz üzerinden değiştirilemez ya da hesap silinemez. Bu bir kilitlenme korumasıdır ve hesabın adının veya e-posta adresinin arayüzden değiştirilememesinin nedeni budur. Değişkeni kaldırıp servisi yeniden başlattığınızda, hesap diğerleri gibi düzenlenebilir sıradan bir yönetici hesabına dönüşür.
Parola satırı konusunda dikkatli olunmalıdır. environment: altındaki her veri, container üzerinde docker inspect komutunu çalıştırabilen herkes tarafından okunabilir; bu nedenle DEFAULT_ADMIN_PASSWORD kalıcı olarak orada tutulmamalıdır. Giriş yapın, ilgili satırı silin, docker compose up -d komutunu tekrar çalıştırın ve ardından arayüz üzerinden parolanızı değiştirin.
Daha temiz olan yöntem, değişkenleri tamamen devre dışı bırakmaktır. DEFAULT_ADMIN_* grubunun tamamını yorum satırı haline getirin ve ardından hesabı etkileşimli olarak oluşturun:
docker compose run --rm planka npm run db:create-admin-userBu komut e-posta, parola, görünen ad ve isteğe bağlı kullanıcı adı bilgilerini ister ve kullanıcıyı doğrudan veritabanına yazar. Parola, Compose dosyasına veya container'ın yapılandırılmış ortam değişkenlerine hiçbir şekilde temas etmez. VPS üzerinde birden fazla kişinin shell erişimi varsa bu yöntemi kullanın. Komut, depends_on nedeniyle önce Postgres servisini başlatır, bu sayede daha önce hiç çalıştırılmamış bir stack üzerinde bile sorunsuz işler.
Her iki yöntem de Planka parolalarını manuel olarak yönetmenizi gerektirir. 2.1.1 sürümüne kadar Community sürümü, giriş işlemlerini kendi tek oturum açma sunucunuz olarak çalışan Authentik gibi bir OIDC sağlayıcısına devredebilmekteydi; ancak Ağustos 2026'da yayınlanan 2.2.0 sürümü ile OIDC ve SSO özellikleri PLANKA Pro sürümüne taşındı. Community sürümünün aynı sürümle kazandığı özellik ise yerel hesaplar için iki faktörlü kimlik doğrulama (TOTP) desteğidir; bu nedenle en azından yönetici hesabı için bu özelliği etkinleştirin.
BASE_URL değeri hostname ile eşleşmediğinde oturum açma işlemleri neden başarısız olur?
BASE_URL, kullanıcıların tarayıcıya yazdığı, şema içeren ve sonunda eğik çizgi (/) bulunmayan tam adrestir. Bu yığın için bu değer https://kanban.example.com şeklindedir. Planka, kendi bağlantılarını ve izin verilen WebSocket kaynakları listesini bu değerden oluşturur; bu nedenle yanlış bir BASE_URL değeri size net bir hata mesajı vermez. Bunun yerine, yüklenen ancak yükleme işlemi asla tamamlanmayan bir sayfa ile karşılaşırsınız.
Sık karşılaşılan durum şudur: upstream örneğini kopyalarsınız, BASE_URL=http://localhost:3000 değerini olduğu gibi bırakırsınız ve siteye gerçek alan adınız üzerinden HTTPS ile erişirsiniz. Oturum açma formu gönderilir ve kimlik bilgileriniz kabul edilir. Ancak pano asla görüntülenmez. Tarayıcı geliştirici konsolunu açtığınızda /socket.io/ adresine yapılan isteklerin başarısız olduğunu görürsünüz; çünkü soket, tarayıcı sayfasının kaynağına bağlanmaya çalışır ancak sunucunun kaynak kısıtlaması, BASE_URL değerinden türetilen kaynağa izin vermektedir.
TRUST_PROXY=true, aynı sorunun diğer yarısıdır. Planka, Traefik arkasında çalıştığı için her istek proxy adresinden Docker ağı içindeki düz HTTP üzerinden ulaşır. TRUST_PROXY olmadan uygulama, Traefik tarafından ayarlanan X-Forwarded-Proto ve X-Forwarded-For başlıklarını görmezden gelir; bu nedenle bağlantının güvensiz olduğuna inanır ve her istemciyi tek bir paylaşılan IP adresi olarak ele alır. Bu değer ayarlandığında ise uygulama ilgili başlıkları okur ve şema konusunda tarayıcı ile uyumlu hale gelir.
Traefik, WebSocket trafiğini ek bir yapılandırma gerektirmeden proxy üzerinden iletir; bu durum, burada tercih edilmesinin bir nedenidir. Nginx üzerinde ise proxy'nin upgrade başlıklarını, yani proxy_set_header Upgrade $http_upgrade ve proxy_set_header Connection "upgrade" değerlerini iletmesi gerekir; aksi takdirde farklı bir nedenden dolayı aynı yükleme döngüsüyle karşılaşırsınız. Bu ayarlar genel location / bloğunda yer alabilir; /socket.io için ayrı bir blok oluşturmak da mümkündür ancak zorunlu değildir.
Panoyu daha sonra yeni bir hostname adresine taşımak, iki değerin birlikte değiştirilmesini gerektirir: BASE_URL değeri ve Traefik Host() kuralı. Birini değiştirip diğerini unutursanız, yükleme döngüsü sorunu tekrar ortaya çıkar. Planka'yı https://example.com/planka gibi bir alt yoldan sunmak, Mart 2026'da yayınlanan 2.1.0 sürümünden itibaren desteklenmektedir. Daha eski sürümlerde, uygulamaya kendine ait bir alt alan adı (subdomain) tanımlayın.
Planka eklentileri ve avatarları nerede tutar
Planka 2, bir kullanıcının yüklediği her şeyi container içinde tek bir yol altında saklar: /app/data. Eklentiler, kullanıcı avatarları ve pano arka plan görsellerinin tamamı burada bulunur. Sürüm 1, üç ayrı dizin kullanıyordu; bu nedenle eski bir kılavuzdan kopyalanan Compose dosyası artık mevcut olmayan yolları bağlar ve hedeflenen veri bağlama işlemi gerçekleşmez.
Bu tek bağlama noktası, bir yükseltme sonrasında panonun sağlam kalması ile kötü bir gün geçirmek arasındaki farktır. Docker imajı /app/data yolunu bir volume olarak tanımlar, bu yüzden Compose dosyasında bağlama işlemini atlamak yüklemelerin anonim bir volume içine gitmesine neden olur. Compose, normal bir up yeniden oluşturma işlemi sırasında bunu korur ancak daha sonra yapılan bir down ve ardından gelen up işlemi, bu bağlantıyı otomatik olarak yeniden kurmaz. Pano geri geldiğinde her şey normal görünür, kartlar yerindedir ancak tüm eklenti bağlantıları bozuktur; çünkü veritabanı satırları hala eski volume içindeki dosyalara işaret etmektedir.
Yukarıdaki Compose dosyasında yer alan isimlendirilmiş volume, bu durumu önler. Bir bind mount da işe yarar ve dosyaların standart araçlarla yedeklenmesini kolaylaştırır ancak fazladan bir adım gerektirir. Container içindeki Node süreci UID 1000 ile çalışır, bu nedenle root tarafından sahiplenilen bir ana makine dizini, ilk yüklemede izin hatasına yol açar:
sudo chown -R 1000:1000 /opt/planka/dataİkisi arasındaki farklar bind mount ve isimlendirilmiş volume karşılaştırması bölümünde ele alınmıştır.
Eklentiler planınızdaki disk alanını aşarsa, Planka bunları S3_ENDPOINT, S3_BUCKET ve ilgili anahtar değişkenleri aracılığıyla S3 uyumlu depolama alanına yazabilir. Bu, barındırılan bir bucket'a veya başka bir sunucudaki self-hosted MinIO nesne deposuna işaret edebilir. Bu kararı ekip panoyu doldurmadan önce verin; çünkü S3'ü etkinleştirmek, mevcut yüklemeleri taşımadan dosya okuma ve yazma işlemlerini doğrudan o arka uca yönlendirir.
Stack'i başlatın ve çalıştığını doğrulayın
docker compose pull
docker compose up -d
docker compose psdocker compose ps, postgres değerini healthy olarak ve planka değerini running olarak göstermelidir. Eğer Planka sürekli yeniden başlatılıyorsa, ilk kontrol edilmesi gereken yer uygulama değil veritabanı bağlantısıdır.
docker compose logs -f plankaSağlıklı bir ilk başlatma işlemi veritabanı migrasyonlarını çalıştırır, ancak üretim yapılandırması noShip: true değerini ayarlar ve 1337 numaralı portu bildiren başlatma mesajını gizler. Şemanın gerçekten oluştuğunu doğrulamak için loglara güvenmek yerine doğrudan Postgres'e sorun:
docker compose exec postgres psql -U planka -d planka -c '\dt'board ve card içeren bir tablo listesi, migrasyonların çalıştığı anlamına gelir. "Did not find any relations" ifadesi, Planka'nın hiç bağlanamadığı anlamına gelir; bu durumda DATABASE_URL değerini .env dosyanızdaki POSTGRES_USER ve POSTGRES_PASSWORD değerleri ile karşılaştırın.
Ardından, VPS üzerinden değil, kendi makinenizden rotayı kontrol edin:
curl -I https://kanban.example.comHTTP/2 200, Traefik'in bir sertifikaya sahip olduğunu ve container'a ulaştığını gösterir. Traefik tarafından döndürülen bir 404 hatası, hiçbir yönlendiricinin istekle eşleşmediği anlamına gelir: Host() kuralı talep ettiğiniz hostname ile eşleşmiyordur veya Traefik etiketleri (labels) algılamamıştır. 502 hatası, yönlendiricinin eşleştiği ancak Traefik'in container'a ulaşamadığı anlamına gelir; örneğin container proxy ağına bağlı olmayabilir. Şimdi siteyi açın ve yönetici hesabıyla giriş yapın.
Her sürüm yükseltme işleminden önce pg_dump alın
Panonuz iki ayrı depoda tutulur, bu nedenle yedekleme her ikisini de kapsamalıdır: Postgres veritabanı ve planka-data birimi. Veritabanı yedeğini yığın çalışırken alın.
docker compose exec -T postgres pg_dump -U planka -d planka > "planka-db-$(date +%F).sql"-T, Compose'un varsayılan sözde terminal tahsisini devre dışı bırakarak yedeğin düz bir çıktı akışında kalmasını sağlar.
Ardından yüklemeler. Önce gerçek birim adını bulun, çünkü Compose bunu proje dizini adıyla ön ekler.
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 .Proje ayrıca deposunda docker-backup.sh ve docker-restore.sh ile birlikte gelir ve resmi belgeler bunları gece çalışan bir cron işine yerleştirir. Her iki yaklaşım da uygundur. Uygun olmayan şey, daha önce hiç geri yüklemediğiniz bir yedektir; bu yüzden bir tanesini geçici bir VPS üzerinde geri yükleyin ve giriş yapıp bir eki açabildiğinizi doğrulayın. Aynı depolama çifti, yükleme kabul eden her Compose uygulamasında karşınıza çıkar; bu nedenle daha sonra Chatwoot'u destek masanızla aynı sunucuya kurarsanız, burada oluşturduğunuz rutin, yalnızca birim adları değiştirilerek kolayca uygulanabilir.
Her sürüm değişikliğinden hemen önce yedeği alın. Dünden kalan bir yedek, gerçekleştirmek üzere olduğunuz geçiş işleminden önceki bir yedekle aynı şey değildir.
Etiketleri sabitleyin ve sürüm notlarını okuyun
Dosyadaki her iki imaj etiketi de bilinçli olarak sabitlenmiştir.
ghcr.io/plankanban/planka:2.2.1, Ekim 2026 itibarıyla güncel olan belirli bir sürümdür. Community 2.3.0, 4 Kasım 2026'da güvenlik yamalarıyla yayınlanmıştır ve geliştiriciler güncellemeyi önermektedir. Community 2.3.1 ise 5 Kasım 2026'da, kullanıcı adı olmayan bir üyeye sahip panolardaki kart açıklamaları düzenlenirken oluşan bir çökme hatasını gidererek yayınlanmıştır. latest, geliştiriciler her yayın yaptığında değişir; bu nedenle rutin bir docker compose pull işlemi, hiç beklemediğiniz bir anda şema migrasyonunun tetiklenmesine neden olabilir. Bu numarayı değiştirmeden önce sürüm notlarını okuyun, çünkü kırılgan değişiklikler ve güvenlik yamaları burada açıklanır. Sürüm 2.0.3 bir güvenlik sürümü olarak yayınlanmıştır; bu, kazara değil, bilinçli olarak okumanız gereken türden bir bilgidir. Ağustos 2026'da yayınlanan 2.2.1 sürümü de aynı şekildedir: bu sürüm, yerel dosya depolama kullanan (bu rehberdeki yapılandırma gibi) örneklerde giriş yapmış bir kullanıcının rastgele dosyaları okumasına izin veren bir path traversal açığını kapatır; güvenlik bülteni 2.1.1 ve önceki sürümlerin etkilendiğini belirtir. Eğer 2.1.x sürümünden geliyorsanız, önce 2.2.0 notlarını okuyun; çünkü bu sürüm, yönetici bir şifre verip yeniden etkinleştirene kadar yalnızca SSO ile giriş yapan kullanıcıları devre dışı bırakır. Geliştiriciler imajları yayınladığı için burada sabitleme yapmak kolaydır; bir proje imaj yayınlamıyorsa, git etiketinden derlenen openGym örneğinde olduğu gibi, aynı disiplini fazladan bir adımla uygulamanız gerekir.
postgres:16-alpine, daha kritik bir nedenden dolayı ana sürüme sabitlenmiştir. Postgres, veri dizinini ana sürüme bağlı bir formatta yazar ve sunucu, farklı bir sürüm tarafından yazılmış bir dizini açmayı reddeder. postgres:latest yazıp etiketin 16'yı geçmesine izin verirseniz, container başlamayacaktır. Örneğin 17 imajı şu hata ile durur:
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.Hiçbir veri kaybolmaz ve yeniden başlatmak da sorunu çözmez. Yeni bir Postgres ana sürümüne geçmek; eski sürümden bir dump alıp yeni veri dizinine geri yüklemeyi, veriyi dump almadan dönüştüren ancak hem eski hem de yeni sunucu binary dosyalarının aynı anda mevcut olmasını gerektiren bir pg_upgrade çalıştırmayı veya yeni sürümü çalıştıran bir sunucuya mantıksal replikasyon yapıp ardından geçiş yapmayı gerektirir. Her yol planlı bir migrasyondur, bir imaj çekme işleminin yan etkisi değildir; mantıksal replikasyon, yeni sunucu yetişene kadar eski sunucunun çalışmaya devam etmesine olanak tanır.
Eğer sıfırdan başlamak yerine mevcut bir Planka 1.x kurulumunu taşıyorsanız, bu yükseltmenin proje belgelerinde kendi prosedürü mevcuttur ve önceden alınmış bir yedek olmadan 1. sürüme geri dönüş yolu yoktur.
Hata modları ve karşılaşacağınız dizgeler
Planka döngüsel olarak yeniden başlıyor ve günlük kayıtlarında veritabanı adı geçiyor. DATABASE_URL içindeki kimlik bilgileri Postgres ortamı ile eşleşmiyor. POSTGRES_PASSWORD değişkeninin yalnızca veri dizini ilk kez başlatıldığında uygulandığını unutmayın; bu nedenle hatalı bir ilk başlatmadan sonra değişkeni düzeltmek hiçbir şeyi değiştirmez. Veritabanı rolünün parolasını, yapılandırılmış parola ile eşleşecek şekilde ALTER ROLE ile değiştirin; db-data birimini (volume) kaldırmak yalnızca verisi tutulmayacak, geçici kurulumlar için bir seçenektir.
Giriş başarılı ancak pano yüklenmiyor. BASE_URL tarayıcı çubuğundaki adresle eşleşmiyor, bu nedenle sunucu soketin kaynağını reddediyor. Tarayıcı konsolu /socket.io/ adresine yapılan isteklerin başarısız olduğunu gösteriyor.
Diğer her şey çalışırken dosya yüklemeleri başarısız oluyor. Bir bind mount kök (root) dizin sahipliğinde kalmış. Ana makinedeki dizin üzerinde sudo chown -R 1000:1000 komutunu çalıştırın ve container'ı yeniden başlatın.
Yükseltme sonrasında ekler kayboldu. /app/data orijinal yükleme birimine bağlanmamış. O birimi yeniden bağlayın veya dosyaları yedekten geri yükleyin, ardından imaj etiketine tekrar dokunmadan önce adlandırılmış bir birim kullanın.
Traefik 404 hatası döndürüyor. İsteği karşılayan bir yönlendirici yok: Host() kuralı DNS kaydınızla eşleşmiyor veya etiketler Traefik'e ulaşmadı. docker compose config, değişken yerleştirmelerinden sonra etiketlerin son halini gösterir; yazım hataları burada görünür hale gelir. 502 hatası ise rotanın eşleştiğini ancak container'a ulaşılamadığını gösterir; bu nedenle container'ın proxy ağında olup olmadığını kontrol edin.
Bildirimler veya webhook'lar ulaşmıyor. Planka 2, giden HTTP isteklerini dahili bir filtreden geçirir ve varsayılan engelleme listesi localhost ve postgres adreslerini kapsar. localhost adresine yönlendirilen bir webhook tasarım gereği engellenir ve OUTGOING_ALLOWED_HOSTS ayarını yaptığınızda, bu listede olmayan her ana makine de engellenir. Webhook'u diğer container'ın servis adına yönlendirin ve filtreyi kaldırmak yerine, izin verilenler listesi kullanıyorsanız bu adı OUTGOING_ALLOWED_HOSTS içine ekleyin.
Sistem çalışmaya başladıktan sonra operasyonel yükü düşüktür. Sürüm notlarını takip edin ve her yükseltme öncesinde veritabanı yedeği alın. Docker servisi önyüklemede etkinleştirildiği sürece, restart: unless-stopped sayesinde bir yeniden başlatma işlemi yığını kendiliğinden ayağa kaldırır; Yeniden başlatma sonrası ayağa kalkan Compose yığınları belgesi, bunun gerçekleşmediği durumları ele alır.
FAQ
Planka giriş yaptıktan sonra neden sürekli yükleniyor?
Kimlik bilgileriniz kabul edilmiş ancak canlı bağlantı kurulamamıştır. Tarayıcı, soket bağlantısını sayfanın kaynak adresine açar; Planka ise izin verilen soket kaynaklarını BASE_URL değişkeninden türetir. Bu değişkeni http://localhost:3000 değerinde bırakıp siteye https://kanban.example.com üzerinden erişirseniz, sunucu bağlantıyı reddeder. Geliştirici konsolu, /socket.io/ adresine yapılan isteklerin başarısız olduğunu gösterir. BASE_URL değişkenini, sonunda eğik çizgi (slash) olmadan tam genel adresinizle ayarlayın, uygulamanın reverse proxy'nizden gelen X-Forwarded-Proto başlığını dikkate alması için TRUST_PROXY=true değerini ekleyin ve ardından docker compose up -d komutunu çalıştırın.
İlk Planka yönetici kullanıcısını nasıl oluştururum?
1.13 sürümünden itibaren otomatik olarak yönetici oluşturulmamaktadır. Ya DEFAULT_ADMIN_EMAIL değişkenini, eşleşen parola, isim ve kullanıcı adı değişkenleriyle birlikte ayarlayıp stack'i başlatın ya da docker compose run --rm planka npm run db:create-admin-user komutunu çalıştırıp soruları yanıtlayın. Etkileşimli komut, paylaşımlı bir sunucuda daha güvenlidir; çünkü parola, docker inspect aracının okuyabileceği container yapılandırma ortamına hiçbir zaman girmez. DEFAULT_ADMIN_EMAIL değişkenini kurulumdan sonra ayarlı tutmak, ilgili hesabın isminin, rolünün ve e-posta adresinin değiştirilmesini engeller ve arayüz üzerinden silinmesini kısıtlar. Kurulumdan sonra DEFAULT_ADMIN_PASSWORD değişkenini kaldırın; çünkü bu değişkenin ayarlı kalması, her başlatmada ilgili hesabın parolasını sıfırlar.
Planka ekleri ve avatarları nerede saklar?
Planka 2'de yüklenen tüm dosyalar, ekler, kullanıcı avatarları ve pano arka planları dahil olmak üzere container içerisinde /app/data dizininde yaşar. Bu yolu bir named volume üzerine mount edin. Açık bir mount işlemi yapılmazsa, Docker imajı anonim bir volume kullanır ve bu volume, docker compose down işleminden sonra gelen bir docker compose up komutuyla otomatik olarak yeniden bağlanmaz. Bind mount da çalışır ancak Node süreci UID 1000 ile çalıştığından, ana makinedeki dizin üzerinde sudo chown -R 1000:1000 komutunu çalıştırın, aksi takdirde yüklemeler izin hatası nedeniyle başarısız olur.
Kendi sunucumda barındırdığım Planka ne kadar RAM'e ihtiyaç duyar?
Projenin teknik SSS bölümü, küçük ekipler için en az 2 GB RAM ve 10 GB depolama alanı önermektedir. Varsayılan Docker dağıtımı bir Node süreci, açık bağlantı başına bir arka uç süreci olan bir Postgres sunucusu ve giden istek filtrelemesi için dahili bir Squid proxy çalıştırır. Normal bir haftanın ardından docker stats --no-stream komutunu çalıştırın ve boyutlandırmayı kendi verilerinize göre yapın. Diski bellekten daha yakından izleyin, çünkü büyüyen kısım ek dosyalardır.
Veri kaybetmeden Planka'yı nasıl yükseltirim?
Veritabanının yedeğini alın ve yükleme volume'unu yükseltmeden hemen önce arşivleyin; bunu bir önceki gecenin yedekleme planına bırakmayın. Yönlendirilen çıktı için sözde terminal (pseudo-terminal) tahsisini devre dışı bırakmak amacıyla -T parametresini koruyarak docker compose exec -T postgres pg_dump -U planka -d planka > planka-db.sql komutunu kullanın. Atladığınız her sürüm için sürüm notlarını okuyun, imaj etiketini latest yerine belirli bir sürüme değiştirin, ardından docker compose pull ve docker compose up -d komutlarını çalıştırın ve log kayıtlarından migrasyon sürecini izleyin. Postgres etiketini ana sürümüne sabitlenmiş şekilde bırakın, çünkü sunucu farklı bir ana sürüm tarafından yazılmış bir veri dizinini açmayı reddeder.