Tự host Planka với Docker Compose trên VPS
Triển khai Planka trên VPS với Docker Compose, Postgres và Traefik; kiểm tra biến bootstrap admin và lỗi BASE_URL khiến bạn không đăng nhập được.
Những gì bạn nhận được khi tự host Planka
Tự host Planka cung cấp cho team của bạn một Kanban board với mô hình card, list và label quen thuộc từ Trello, chạy trên VPS do bạn kiểm soát. Không có giới hạn số seat và không tính phí theo từng user, vì chi phí duy nhất là máy chủ. Hướng dẫn này triển khai Planka bằng Docker Compose phía sau Traefik, sử dụng Postgres để lưu dữ liệu và một named volume cho mọi file người dùng upload.
Planka 2 được phát hành theo Fair Use License riêng của dự án. Dự án mô tả giấy phép này là source-available thay vì open source. Bạn được phép chạy Planka cho các project nội bộ của tổ chức mình. Nếu cung cấp Planka cho bên thứ ba dưới dạng hosted service thương mại, bạn cần license Pro hoặc Enterprise.
Đối tượng của hướng dẫn này là một team gồm hai đến năm người đang rời khỏi free tier của Trello. Nếu bạn vẫn đang quyết định nên dùng board nào, hãy đọc bài so sánh các lựa chọn thay thế Trello tự host trước. Hướng dẫn này giả định bạn đã chọn xong và chỉ tập trung vào phần deploy.
Bạn cần một VPS chạy Docker Engine cùng Compose plugin, và một bản ghi DNS A trỏ đến VPS đó. Bạn cũng cần một instance Traefik đã thực hiện TLS termination (transport layer security) trên máy chủ đó. Nếu Traefik chưa được cài đặt, trước tiên hãy thiết lập reverse proxy Traefik phía trước nhiều ứng dụng Compose, và đọc những kiến thức cơ bản về Docker Compose trên VPS nếu file bên dưới chưa quen thuộc với bạn.
Planka cần VPS cấu hình thế nào?
FAQ kỹ thuật của dự án khuyến nghị ít nhất 2 GB RAM và 10 GB storage cho các nhóm nhỏ. Hãy xem đây là điểm bắt đầu, không phải con số đo chính xác.
Thành phần thực sự chạy khá ít: một tiến trình Node.js phục vụ API và frontend đã build, cùng một server Postgres lưu dữ liệu. Postgres chạy một tiến trình giám sát và một tiến trình backend cho mỗi connection đang mở. Một proxy process nhỏ cũng chạy bên trong container Planka để lọc các request gửi ra ngoài. Gói 2 GB đáp ứng khuyến nghị RAM của dự án cho nhóm nhỏ. Một board tiêu tốn ít tài nguyên, nên nếu VPS này cũng dùng để lưu tài liệu của nhóm, hãy chọn cấu hình dựa trên ứng dụng đó trước: chạy AFFiNE làm workspace kiểu Notion cần riêng vài gigabyte trước khi Planka cần thêm tài nguyên.
Hãy tính dung lượng disk trước khi tính RAM, vì attachments là phần tăng nhanh nhất. Hãy đo trên instance của bạn thay vì chỉ dựa vào đoạn này:
docker stats --no-stream
docker system df -vLệnh đầu tiên hiển thị memory và CPU hiện tại của từng container. Lệnh thứ hai cho biết mỗi volume đang sử dụng bao nhiêu dung lượng. Hãy thực hiện cả hai lần đo sau một tuần làm việc bình thường, không phải ngay sau khi cài đặt, vì một board không hoạt động không cho biết gì về nhu cầu của nhóm bạn.
Tạo file Compose
Tạo thư mục và chuyển quyền sở hữu thư mục đó cho bạn, để bạn không phải chỉnh sửa các file này thông qua sudo.
sudo mkdir -p /opt/planka
sudo chown "$USER":"$USER" /opt/planka
cd /opt/plankaTạo các secret trong file .env nằm cạnh file Compose. Compose tự động đọc file đó và thay thế các giá trị.
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 là lựa chọn có chủ đích. Chuỗi hex chỉ chứa chữ số và các chữ cái từ a đến f, nên không thể làm hỏng chuỗi kết nối DATABASE_URL mà nó được chèn vào. Base64 chuẩn có thể chứa dấu gạch chéo, dấu cộng và dấu bằng dùng để padding, nhưng không bao giờ chứa dấu @; các ký tự có ý nghĩa đặc biệt trong connection URL cần được mã hóa phần trăm. Mẫu tổng quát hơn được trình bày trong không đưa secret vào file Compose.
Bây giờ hãy docker-compose.yml. Thay kanban.example.com bằng hostname của bạn ở cả hai vị trí xuất hiện trong file.
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:Có 4 quyết định trong file này cần giải thích, vì đây là những chỗ mọi người thường thay đổi rồi phải hối tiếc.
- Service Planka không có block
ports:. Traefik truy cập container qua networkproxy, nên port 1337 không bao giờ được publish trên host. Nếu publish port này, bất kỳ ai cũng có thể bỏ qua proxy và certificate của bạn. loadbalancer.server.port=1337chỉ định port bên trong container. Planka lắng nghe trên 1337, còn ví dụ upstream chỉ truy cập được port này qua 3000 vì đã map port đó lên host. Ở đây không có host mapping, nên phải chỉ cho Traefik biết port của container.condition: service_healthykết hợp với healthcheck của Postgres. Nếu thiếu thiết lập này, Planka sẽ khởi động trước khi database chấp nhận kết nối, thực hiện query đầu tiên bị lỗi rồi thoát, trông giống như đang crash loop. Cơ chế này được trình bày trong healthcheck và thứ tự khởi động trong Compose.- Service database được đặt tên là
postgrescó chủ đích. Planka 2 chuyển các request đi qua một bộ lọc nội bộ có block list mặc định làlocalhost,postgres. Nếu đổi tên service, bạn sẽ âm thầm xóa database khỏi danh sách đó.
Kiểm tra để chắc chắn Compose có thể đọc các secret trước khi khởi động bất kỳ thứ gì:
docker compose config | grep -E 'image:|BASE_URL|POSTGRES_USER'Lệnh này in ra file với các giá trị .env đã được thay thế. Giá trị trống có nghĩa là Compose không đọc file .env, thường là vì bạn đang chạy lệnh từ một thư mục khác.
Các biến bootstrap tài khoản admin thực sự làm gì
Từ Planka 1.13, hệ thống không còn tự tạo administrator, nên database mới sẽ không có ai đăng nhập được. Nhóm DEFAULT_ADMIN_* là một trong hai cách xử lý việc này.
Khi khởi động, Planka tìm user khớp với DEFAULT_ADMIN_EMAIL. Nếu không có, hệ thống tạo user đó bằng password, display name và username được cấu hình cùng nhóm biến. Ở các lần khởi động sau, hệ thống cũng cập nhật account khớp với các biến này, bao gồm reset password khi DEFAULT_ADMIN_PASSWORD vẫn còn được đặt.
DEFAULT_ADMIN_EMAIL còn có một tác dụng khác dễ gây nhầm lẫn. Khi biến này vẫn được đặt, account mà nó chỉ định không thể đổi tên, role hoặc địa chỉ email, cũng không thể bị xóa qua giao diện. Đây là cơ chế bảo vệ khỏi việc tự khóa quyền truy cập. Vì vậy, bạn cũng không thể đổi tên account hoặc đổi địa chỉ email của account đó trong UI. Xóa biến này rồi restart, account sẽ trở thành một admin thông thường và bạn có thể chỉnh sửa như các account khác.
Dòng password cần được xử lý cẩn thận. Bất kỳ giá trị nào trong environment: đều có thể bị đọc bởi người chạy được docker inspect trên container, nên DEFAULT_ADMIN_PASSWORD không nên được giữ ở đó lâu dài. Đăng nhập, xóa dòng đó, chạy lại docker compose up -d, rồi đổi password trong giao diện.
Cách sạch hơn là bỏ qua toàn bộ các biến này. Comment toàn bộ nhóm DEFAULT_ADMIN_*, rồi tạo account ở chế độ tương tác:
docker compose run --rm planka npm run db:create-admin-userLệnh yêu cầu nhập email, password, display name và username tùy chọn, sau đó ghi user trực tiếp vào database. Password không bao giờ xuất hiện trong Compose file hoặc environment đã cấu hình cho container. Hãy dùng cách này nếu có hơn một người có quyền shell trên VPS. Lệnh khởi động Postgres trước nhờ depends_on, nên vẫn hoạt động trên stack chưa từng được khởi động.
Cả hai cách đều yêu cầu bạn tự quản lý password của Planka. Đến phiên bản 2.1.1, Community edition có thể chuyển việc đăng nhập cho OIDC provider như Authentik chạy như một server single sign-on do bạn tự quản lý, nhưng phiên bản 2.2.0, phát hành vào August 2026, đã chuyển OIDC và SSO sang PLANKA Pro. Trong cùng bản phát hành, Community edition được bổ sung xác thực hai yếu tố (TOTP) cho các account local, nên ít nhất hãy bật tính năng này cho account admin.
BASE_URL làm hỏng đăng nhập khi không khớp với hostname
BASE_URL là địa chỉ chính xác mà người dùng nhập vào trình duyệt, bao gồm scheme và không có dấu gạch chéo ở cuối. Với stack này, giá trị đó là https://kanban.example.com. Planka dùng giá trị này để tự tạo các liên kết và danh sách origin WebSocket được phép. Vì vậy, BASE_URL sai không tạo ra một lỗi rõ ràng. Trang vẫn tải được nhưng không bao giờ tải xong.
Trường hợp thường gặp là bạn sao chép ví dụ từ upstream, giữ nguyên BASE_URL=http://localhost:3000, rồi truy cập trang qua HTTPS trên domain thật. Form đăng nhập được gửi đi và thông tin xác thực được chấp nhận. Nhưng board không xuất hiện. Mở developer console của trình duyệt, bạn sẽ thấy các request đến /socket.io/ bị lỗi, vì socket kết nối đến origin của trang trong trình duyệt, còn giới hạn origin trên server lại cho phép origin được suy ra từ BASE_URL.
TRUST_PROXY=true là nửa còn lại của cùng vấn đề. Planka nằm sau Traefik, nên mọi request đến ứng dụng từ địa chỉ của proxy qua HTTP thuần bên trong Docker network. Nếu không đặt TRUST_PROXY, app bỏ qua các header X-Forwarded-Proto và X-Forwarded-For mà Traefik thiết lập. Khi đó, app cho rằng kết nối không an toàn và xem mọi client như cùng một địa chỉ IP. Khi đặt giá trị này, app đọc các header đó và thống nhất scheme với trình duyệt.
Traefik proxy WebSocket mà không cần cấu hình thêm. Đây là một lý do nên dùng Traefik trong trường hợp này. Với nginx, proxy phải chuyển tiếp các header upgrade, proxy_set_header Upgrade $http_upgrade và proxy_set_header Connection "upgrade". Nếu không, bạn sẽ gặp cùng một spinner bị treo nhưng do nguyên nhân khác. Các header này có thể nằm trong block location / chung. Tạo block riêng cho /socket.io cũng được nhưng không bắt buộc.
Nếu sau này chuyển board sang hostname mới, bạn phải thay đổi đồng thời 2 thứ: giá trị BASE_URL và rule Host() của Traefik. Chỉ thay đổi một trong hai rồi quên phần còn lại sẽ khiến spinner xuất hiện trở lại. Từ version 2.1.0, phát hành vào tháng 3 năm 2026, Planka hỗ trợ chạy dưới subpath như https://example.com/planka. Với các tag cũ hơn, hãy dùng một subdomain riêng cho Planka.
Planka lưu tệp đính kèm và avatar ở đâu
Planka 2 lưu mọi thứ người dùng tải lên dưới một đường dẫn duy nhất bên trong container: /app/data. Tệp đính kèm, avatar người dùng và ảnh nền của board đều nằm trong đó. Version 1 dùng ba thư mục riêng, nên file Compose được sao chép từ một bài hướng dẫn cũ sẽ mount các đường dẫn không còn tồn tại, còn mount dữ liệu cần thiết lại bị thiếu.
Mount duy nhất đó quyết định board có tồn tại sau khi nâng cấp hay không. Docker image khai báo /app/data là một volume, nên nếu bỏ mount này khỏi Compose, các tệp tải lên sẽ nằm trong một anonymous volume. Compose vẫn giữ volume đó khi thực hiện thao tác up thông thường, nhưng down rồi up sau đó sẽ không tự động kết nối lại volume. Board khởi động lại trông vẫn bình thường, toàn bộ card vẫn còn, nhưng mọi liên kết đến tệp đính kèm đều hỏng vì các bản ghi trong database vẫn trỏ đến các tệp trong volume cũ.
Named volume trong file Compose ở trên ngăn lỗi này. Bind mount cũng dùng được và giúp sao lưu tệp dễ hơn bằng các công cụ thông thường, nhưng cần thêm một bước. Node process bên trong container chạy với UID 1000, nên một thư mục trên host thuộc sở hữu của root sẽ gây lỗi quyền ngay lần tải tệp đầu tiên:
sudo chown -R 1000:1000 /opt/planka/dataSự đánh đổi giữa hai cách này được phân tích trong bind mount và named volume.
Nếu tệp đính kèm vượt quá dung lượng disk trong gói của bạn, Planka có thể ghi chúng vào storage tương thích với S3 thông qua S3_ENDPOINT, S3_BUCKET và các biến key tương ứng. Storage này có thể trỏ đến bucket được host sẵn hoặc object store MinIO tự host trên một máy khác. Hãy quyết định trước khi team đưa quá nhiều dữ liệu vào board, vì bật S3 sẽ chuyển việc đọc và ghi tệp sang backend đó mà không migrate các tệp đã tải lên trước đây.
Khởi động stack và kiểm tra kết quả
docker compose pull
docker compose up -d
docker compose psdocker compose ps phải hiển thị postgres là healthy và planka là running. Nếu Planka liên tục restart, hãy kiểm tra kết nối database trước, không phải ứng dụng.
docker compose logs -f plankaLần boot đầu tiên bình thường sẽ chạy các migration của database, nhưng cấu hình production đặt noShip: true và ẩn thông báo startup cho biết cổng 1337. Hãy xác nhận schema thực sự đã được tạo bằng cách truy vấn trực tiếp Postgres thay vì chỉ tin vào log:
docker compose exec postgres psql -U planka -d planka -c '\dt'Danh sách table có board và card cho biết migration đã chạy. Thông báo "Did not find any relations" nghĩa là Planka chưa từng kết nối được, vì vậy hãy so sánh DATABASE_URL với các giá trị POSTGRES_USER và POSTGRES_PASSWORD trong .env của bạn.
Tiếp theo, kiểm tra route từ chính máy của bạn, không phải từ VPS:
curl -I https://kanban.example.comHTTP/2 200 nghĩa là Traefik đã giữ certificate và đang kết nối được đến container. HTTP 404 do Traefik trả về nghĩa là không có router nào khớp với request: rule Host() không khớp với hostname bạn đã yêu cầu, hoặc Traefik chưa nhận được các label. HTTP 502 nghĩa là router đã khớp nhưng Traefik không thể kết nối đến container, chẳng hạn vì container chưa được gắn vào network proxy. Bây giờ hãy mở site và đăng nhập bằng tài khoản admin.
Thực hiện pg_dump trước mỗi lần nâng phiên bản
Bảng của bạn được lưu ở hai nơi riêng biệt, nên bản backup phải bao gồm cả hai: database Postgres và volume planka-data. Dump database khi stack đang chạy.
docker compose exec -T postgres pg_dump -U planka -d planka > "planka-db-$(date +%F).sql"-T tắt cơ chế cấp pseudo-terminal mặc định của Compose, để dump được ghi vào một output stream thuần.
Tiếp theo là các file upload. Trước tiên, hãy tìm tên volume thực tế vì Compose thêm tiền tố là tên thư mục của project.
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 .Project cũng cung cấp docker-backup.sh và docker-restore.sh trong repository, đồng thời tài liệu chính thức hướng dẫn chạy chúng bằng cron hằng đêm. Cách nào cũng được. Điều không thể chấp nhận là có một bản backup mà bạn chưa từng restore, vì vậy hãy restore một bản lên một VPS tạm để xác nhận bạn có thể đăng nhập và mở một file đính kèm. Hai nơi lưu trữ này cũng xuất hiện trong mọi ứng dụng Compose nhận file upload, nên nếu sau này bạn cài Chatwoot trên cùng máy với hệ thống hỗ trợ của bạn, quy trình xây dựng ở đây gần như được giữ nguyên, chỉ cần đổi tên volume.
Hãy chạy dump ngay trước mỗi lần thay đổi phiên bản. Bản backup từ tối qua không giống với bản backup được tạo trước migration mà bạn sắp chạy.
Cố định tag và đọc release note
Cả hai image tag trong file đó đều được cố định có chủ ý.
ghcr.io/plankanban/planka:2.2.1 là một release cụ thể, hiện tại là tháng 10 năm 2026. Community 2.3.0 được phát hành vào ngày 4 tháng 11 năm 2026, kèm các bản sửa lỗi bảo mật, và upstream khuyến nghị cập nhật. Community 2.3.1 được phát hành tiếp vào ngày 5 tháng 11 năm 2026, sửa lỗi crash khi chỉnh sửa mô tả card trên các board có thành viên không có username. latest thay đổi mỗi khi upstream phát hành, vì vậy một lần docker compose pull định kỳ có thể đưa vào schema migration tại thời điểm bạn không chủ động chọn. Hãy đọc release note trước khi đổi con số đó, vì breaking change và bản sửa lỗi bảo mật được mô tả ở đó. Version 2.0.3 được phát hành dưới dạng security release. Đây chính xác là loại thay đổi bạn cần đọc trước, thay vì vô tình nhận được khi cập nhật. 2.2.1 cũng vậy. Bản này được phát hành vào tháng 8 năm 2026 và sửa lỗi path traversal cho phép user đã đăng nhập đọc các file tùy ý trên những instance sử dụng local file storage, đúng với cấu hình trong hướng dẫn này. Advisory liệt kê 2.1.1 và các version cũ hơn là bị ảnh hưởng. Nếu bạn đang nâng cấp từ 2.1.x, hãy đọc ghi chú của 2.2.0 trước, vì release đó vô hiệu hóa những user chỉ từng đăng nhập qua SSO cho đến khi admin cấp password và kích hoạt lại tài khoản. Việc cố định version ở đây khá dễ vì upstream có publish image. Với project không publish image, bạn vẫn phải tuân thủ kỷ luật tương tự và thêm một bước, như với openGym được build trên máy từ một git tag đã checkout.
postgres:16-alpine được cố định ở major version vì một lý do nghiêm trọng hơn. Postgres ghi data directory theo format gắn với major version, và server sẽ từ chối mở directory được ghi bởi major version khác. Hãy ghi postgres:latest, để tag tự chuyển qua 16, và container sẽ không khởi động. Chẳng hạn, image 17 sẽ dừng với lỗi:
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.Không có dữ liệu nào bị mất, và restart cũng không khắc phục được vấn đề. Chuyển sang một major version mới của Postgres cần dump từ version cũ rồi restore vào data directory mới trên version mới; chạy pg_upgrade, phương pháp chuyển đổi dữ liệu mà không cần dump nhưng yêu cầu binary của server cũ và mới cùng có sẵn; hoặc dùng logical replication đến một server đang chạy version mới rồi thực hiện switchover. Mỗi cách đều là một migration có kế hoạch, không phải tác động phụ của việc pull image. Logical replication cho phép server cũ tiếp tục chạy trong khi server mới bắt kịp dữ liệu.
Nếu bạn đang chuyển một cài đặt Planka 1.x hiện có thay vì cài mới, quá trình nâng cấp đó có procedure riêng được ghi trong tài liệu của project. Không có cách quay lại version 1 nếu trước đó bạn chưa tạo backup.
Các tình huống lỗi và chuỗi bạn sẽ thấy
Planka khởi động lại liên tục và log nhắc đến database. Thông tin xác thực trong DATABASE_URL không khớp với môi trường Postgres. Lưu ý rằng POSTGRES_PASSWORD chỉ được áp dụng khi data directory được khởi tạo lần đầu, nên sửa biến này sau lần boot đầu tiên bị lỗi sẽ không thay đổi gì. Đổi mật khẩu của database role bằng ALTER ROLE để khớp với mật khẩu đã cấu hình; chỉ nên xóa volume db-data nếu đây là bản cài đặt tạm thời và không có dữ liệu cần giữ.
Đăng nhập thành công nhưng board không bao giờ tải. BASE_URL không khớp với địa chỉ trong thanh địa chỉ của trình duyệt, nên server từ chối origin của socket. Console của trình duyệt hiển thị các request lỗi đến /socket.io/.
Upload lỗi trong khi mọi thứ khác vẫn hoạt động. Bind mount đang thuộc sở hữu của root. Chạy sudo chown -R 1000:1000 trên thư mục của host rồi restart container.
Attachment biến mất sau khi upgrade. /app/data không được gắn vào uploads volume ban đầu. Gắn lại volume đó hoặc khôi phục các file từ backup, sau đó dùng named volume trước khi thay đổi image tag lần nữa.
Traefik trả về 404. Không có router nào khớp với request: rule Host() không khớp với DNS record của bạn, hoặc các label chưa bao giờ đến được Traefik. docker compose config hiển thị các label sau khi substitution, đây là nơi dễ thấy lỗi gõ sai. Nếu nhận 502 thì route đã khớp nhưng không thể truy cập container, vì vậy hãy kiểm tra container đã ở trên network proxy chưa.
Notification hoặc webhook không bao giờ đến nơi. Planka 2 gửi các HTTP request đi qua một filter nội bộ, và block list mặc định bao gồm localhost và postgres. Webhook trỏ đến localhost sẽ bị chặn theo thiết kế. Sau khi đặt OUTGOING_ALLOWED_HOSTS, mọi host không có trong danh sách đó cũng bị chặn. Trỏ webhook đến service name của container còn lại, và thêm tên đó vào OUTGOING_ALLOWED_HOSTS nếu bạn dùng allow list, thay vì xóa filter.
Khi đã chạy ổn định, việc vận hành không nhiều. Theo dõi release notes và dump database trước mỗi lần upgrade. Sau khi reboot, stack sẽ tự khởi động lại nhờ restart: unless-stopped, với điều kiện Docker service được enable khi boot. Các Compose stack tự khởi động lại sau khi reboot trình bày các trường hợp stack không tự khởi động.
FAQ
Planka tải vô hạn sau khi tôi đăng nhập, vì sao?
Thông tin đăng nhập đã được chấp nhận nhưng kết nối realtime thì chưa. Trình duyệt mở socket đến origin của trang, còn Planka lấy các origin socket được phép từ BASE_URL. Vì vậy, nếu bạn để biến này là http://localhost:3000 nhưng truy cập site tại https://kanban.example.com, server sẽ từ chối kết nối. Developer console sẽ hiển thị các request lỗi đến /socket.io/. Đặt BASE_URL thành địa chỉ public chính xác, không có dấu gạch chéo ở cuối. Thêm TRUST_PROXY=true để app sử dụng header X-Forwarded-Proto từ reverse proxy. Sau đó chạy docker compose up -d.
Làm cách nào để tạo user admin Planka đầu tiên?
Từ version 1.13, Planka không còn tự động tạo administrator. Bạn có thể đặt DEFAULT_ADMIN_EMAIL cùng các biến password, name và username tương ứng rồi khởi động stack, hoặc chạy docker compose run --rm planka npm run db:create-admin-user và trả lời các prompt. Lệnh tương tác an toàn hơn trên server dùng chung, vì password không xuất hiện trong environment đã cấu hình của container, nơi docker inspect có thể đọc được. Giữ DEFAULT_ADMIN_EMAIL sau khi thiết lập sẽ ngăn thay đổi name, role và email address của account đó, đồng thời chặn việc xóa account này từ interface. Xóa DEFAULT_ADMIN_PASSWORD sau khi thiết lập, vì nếu vẫn đặt biến này, Planka sẽ reset password của account tương ứng mỗi lần startup.
Planka lưu attachment và avatar ở đâu?
Tất cả file đã upload được lưu dưới /app/data trong container ở Planka 2, gồm attachment, avatar của user và background của board. Hãy mount path này vào một named volume. Nếu không mount rõ ràng, Docker image sẽ dùng anonymous volume. Một lần docker compose up sau đó sẽ không tự động kết nối lại volume này sau docker compose down. Bạn cũng có thể dùng bind mount, nhưng Node process chạy với UID 1000. Vì vậy, hãy chạy sudo chown -R 1000:1000 trên thư mục của host, nếu không thao tác upload sẽ lỗi quyền truy cập.
Planka tự host cần bao nhiêu RAM?
Technical FAQ của dự án khuyến nghị tối thiểu 2 GB RAM và 10 GB storage cho các team nhỏ. Docker deployment mặc định chạy một Node process, một Postgres server với một backend process cho mỗi connection đang mở, cùng một Squid proxy nội bộ để lọc request đi ra ngoài. Hãy chạy docker stats --no-stream sau một tuần vận hành bình thường và sizing dựa trên số liệu thực tế của bạn. Theo dõi disk sát hơn memory, vì attachment mới là thành phần tăng dần theo thời gian.
Làm cách nào để upgrade Planka mà không mất dữ liệu?
Hãy dump database và archive uploads volume ngay trước khi upgrade, không dùng bản schedule của đêm trước. Dùng docker compose exec -T postgres pg_dump -U planka -d planka > planka-db.sql và giữ -T để tắt việc cấp pseudo-terminal cho output được redirect. Đọc release notes của mọi version bị bỏ qua. Đổi image tag sang một release cụ thể thay vì latest. Sau đó chạy docker compose pull và docker compose up -d, rồi monitor log để theo dõi migration. Giữ Postgres tag ở major version hiện tại, vì server sẽ từ chối mở data directory được ghi bởi một major version khác.