Self-host Planka: source-available Kanban board
Deploy Planka on a VPS with Docker Compose: Postgres, Traefik, the admin bootstrap variables, and the BASE_URL setting that breaks your logins.
What you get by self-hosting Planka
Self-hosting Planka gives your team a Kanban board with the card, list and label model people already know from Trello, running on a VPS you control. There are no seat limits and no per-user billing, because the only cost is the server. This guide deploys it with Docker Compose behind Traefik, using Postgres for the data and a named volume for every file people upload.
Planka 2 ships under the project's own Fair Use License, which the project describes as source-available rather than open source. Running it for your own organisation's internal projects is allowed. Offering it to third parties as a commercial hosted service needs a Pro or Enterprise licence.
The reader I have in mind is a team of two to five leaving Trello's free tier. If you are still deciding which board to run, read the comparison of self-hosted Trello alternatives first. This guide assumes the choice is already made and covers only the deploy.
You need a VPS running Docker Engine with the Compose plugin, and a DNS A record pointing at it. You also need a Traefik instance already terminating TLS (transport layer security) on that box. If Traefik is not there yet, set up a Traefik reverse proxy in front of several Compose apps first, and read the Docker Compose basics for a VPS if the file below looks unfamiliar.
How much VPS does Planka need?
The project's technical FAQ recommends at least 2 GB RAM and 10 GB storage for small teams, so treat those numbers as a starting point rather than a measurement.
What actually runs is small: one Node.js process serving the API and the built frontend, and a Postgres server holding the data, which runs a supervising process plus one backend process for each open connection. A small proxy process also runs inside the Planka container to filter its outgoing requests. A 2 GB plan matches the project's RAM recommendation for small teams. A board is a light neighbour, so if the same VPS is also meant to hold your team's documents, size for that app first: running AFFiNE as a Notion-style workspace wants a couple of gigabytes on its own before Planka asks for anything.
Size the disk before you size the memory, because attachments are the part that grows. Measure your own instance instead of trusting this paragraph:
docker stats --no-stream
docker system df -vThe first prints live memory and CPU per container. The second shows how much space each volume holds. Take both readings after a normal working week, not on install day, because an idle board tells you nothing about your team.
Write the Compose file
Create the directory and take ownership of it, so you never have to edit these files through sudo.
sudo mkdir -p /opt/planka
sudo chown "$USER":"$USER" /opt/planka
cd /opt/plankaGenerate the secrets into a .env file beside the Compose file. Compose reads that file automatically and substitutes the values.
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 is deliberate. A hex string holds only digits and the letters a to f, so it cannot break the DATABASE_URL connection string it gets pasted into. Standard Base64 can contain a slash, plus sign and padding equals sign, but never an at sign; characters with special meaning in a connection URL need percent-encoding. The wider pattern is covered in keeping secrets out of the Compose file.
Now docker-compose.yml. Replace kanban.example.com with your own hostname in both places it appears.
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:Four decisions in that file are worth explaining, because they are the ones people change and then regret.
- There is no
ports:block on the Planka service. Traefik reaches the container across theproxynetwork, so port 1337 is never published on the host. Publishing it would give anyone a way around your proxy and your certificate. loadbalancer.server.port=1337names the port inside the container. Planka listens on 1337, and the upstream example only reaches it on 3000 because it maps the port to the host. There is no host mapping here, so Traefik has to be told the container port.condition: service_healthypairs with the Postgres healthcheck. Without it Planka starts before the database accepts connections, fails its first query and exits, which looks like a crash loop. The mechanics are in Compose healthchecks and startup ordering.- The database service is named
postgreson purpose. Planka 2 routes its own outgoing requests through an internal filter whose default block list islocalhost,postgres. Rename the service and you quietly remove your database from that list.
Check that Compose can see your secrets before you start anything:
docker compose config | grep -E 'image:|BASE_URL|POSTGRES_USER'That prints the file with .env values already substituted. An empty value means Compose is not reading the .env file, usually because you are running the command from a different directory.
What the admin bootstrap variables actually do
Since Planka 1.13 no administrator is created for you, so a fresh database has nobody who can log in. The DEFAULT_ADMIN_* group is one of the two ways to fix that.
On startup Planka looks for a user matching DEFAULT_ADMIN_EMAIL. If there is none, it creates one using the password, display name and username set alongside it. On later starts it also updates a matching account from these variables, including resetting its password when DEFAULT_ADMIN_PASSWORD remains set.
DEFAULT_ADMIN_EMAIL does a second job that catches people out. While the variable stays set, the account it names cannot have its name, role or email address changed, or be deleted, through the interface. That is a lock-out guard, and it is also why you cannot rename that account or change its email address in the UI. Remove the variable and restart, and the account becomes an ordinary admin you can edit like any other.
The password line is the one to be careful with. Anything under environment: is readable by anyone who can run docker inspect on the container, so DEFAULT_ADMIN_PASSWORD should not live there permanently. Log in, delete that line, run docker compose up -d again, then change your password in the interface.
The cleaner route skips the variables entirely. Comment out the whole DEFAULT_ADMIN_* group, then create the account interactively:
docker compose run --rm planka npm run db:create-admin-userIt prompts for email, password, display name and an optional username, and writes the user straight to the database. The password never touches the Compose file or the container's configured environment. Use this route if more than one person has shell access to the VPS. The command starts Postgres first because of depends_on, so it works on a stack that has never been up.
Either route leaves you managing Planka passwords by hand. Up to version 2.1.1 the Community edition could hand logins to an OIDC provider such as Authentik running as your own single sign-on server, but version 2.2.0, released August 2026, moved OIDC and SSO into PLANKA Pro. What the Community edition gained in the same release is two-factor authentication (TOTP) for local accounts, so turn that on for the admin account at least.
Why BASE_URL breaks logins when it does not match the hostname
BASE_URL is the exact address people type into the browser, with the scheme and without a trailing slash. For this stack that is https://kanban.example.com. Planka builds its own links and its list of allowed WebSocket origins from that value, which means a wrong BASE_URL does not give you a clean error. It gives you a page that loads and then never finishes loading.
The common version: you copy the upstream example, leave BASE_URL=http://localhost:3000 in place, and reach the site over HTTPS on your real domain. The login form submits and your credentials are accepted. The board never appears. Open the browser developer console and you will see requests to /socket.io/ failing, because the socket connects to the browser page's origin but the server's origin restriction allows the origin derived from BASE_URL.
TRUST_PROXY=true is the other half of the same problem. Planka sits behind Traefik, so every request reaches it from the proxy's address over plain HTTP inside the Docker network. Without TRUST_PROXY, the app ignores the X-Forwarded-Proto and X-Forwarded-For headers that Traefik sets, so it believes the connection is insecure and treats every client as one shared IP address. With it set, the app reads those headers and agrees with the browser about the scheme.
Traefik proxies WebSockets with no extra configuration, which is one reason to prefer it here. On nginx, the proxy has to forward the upgrade headers, proxy_set_header Upgrade $http_upgrade and proxy_set_header Connection "upgrade", or you get the same stuck spinner from a different cause. They can sit in the general location / block; a separate block for /socket.io also works but is not required.
Moving the board to a new hostname later means changing two things together: the BASE_URL value and the Traefik Host() rule. Change one and forget the other, and you are back at the spinner. Serving Planka from a subpath such as https://example.com/planka works from version 2.1.0 onward, released March 2026. On older tags, give it a subdomain of its own.
Where Planka keeps attachments and avatars
Planka 2 stores everything a user uploads under a single path inside the container: /app/data. Attachments, user avatars and board background images all live under it. Version 1 used three separate directories, so a Compose file copied from an older write-up mounts paths that no longer exist, and the intended data mount is missing.
That single mount is the difference between a board that survives an upgrade and a bad afternoon. The Docker image declares /app/data as a volume, so omitting the mount from Compose puts uploads in an anonymous volume. Compose preserves it during an ordinary up recreation, but a later down followed by up does not automatically reconnect it. The board comes back looking fine, the cards are all there, and every attachment link is dead, because the database rows still point at files in the old volume.
The named volume in the Compose file above prevents this. A bind mount works too and makes the files easier to back up with ordinary tools, but it needs one extra step. The Node process inside the container runs as UID 1000, so a host directory owned by root gives a permission error on the first upload:
sudo chown -R 1000:1000 /opt/planka/dataThe trade-off between the two is worked through in bind mounts against named volumes.
If attachments outgrow the disk on your plan, Planka can write them to S3-compatible storage instead, through S3_ENDPOINT, S3_BUCKET and the matching key variables. That can point at a hosted bucket or at a self-hosted MinIO object store on another box. Decide this before the team fills the board, because enabling S3 switches file reads and writes to that backend without migrating existing uploads.
Start the stack and check it worked
docker compose pull
docker compose up -d
docker compose psdocker compose ps should show postgres as healthy and planka as running. If Planka is restarting in a loop, the database connection is the first thing to check, not the app.
docker compose logs -f plankaA healthy first boot runs the database migrations, but the production configuration sets noShip: true and suppresses the startup message that reports port 1337. Confirm the schema really landed by asking Postgres directly instead of trusting the log:
docker compose exec postgres psql -U planka -d planka -c '\dt'A table list that includes board and card means the migrations ran. "Did not find any relations" means Planka never connected, so compare DATABASE_URL against the POSTGRES_USER and POSTGRES_PASSWORD values in your .env.
Then check the route from your own machine, not from the VPS:
curl -I https://kanban.example.comHTTP/2 200 means Traefik holds a certificate and is reaching the container. A 404 served by Traefik means no router matched the request: the Host() rule does not match the hostname you asked for, or Traefik never picked up the labels. A 502 means the router matched but Traefik could not reach the container, for example because it is not attached to the proxy network. Now open the site and log in with the admin account.
Take a pg_dump before every version bump
Two separate stores hold your board, so a backup has to cover both: the Postgres database and the planka-data volume. Dump the database while the stack is running.
docker compose exec -T postgres pg_dump -U planka -d planka > "planka-db-$(date +%F).sql"The -T disables Compose's default pseudo-terminal allocation, keeping the dump on a plain output stream.
Then the uploads. Find the real volume name first, because Compose prefixes it with the project directory name.
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 .The project also ships docker-backup.sh and docker-restore.sh in its repository, and the official documentation puts them on a nightly cron job. Either approach is fine. What is not fine is a backup you have never restored, so restore one onto a scratch VPS once and confirm you can log in and open an attachment. The same pair of stores turns up in every Compose app that accepts uploads, so if you later put Chatwoot on the same box as your support desk, the routine you build here carries over with little more than the volume names changed.
Run the dump immediately before every version change. A backup from last night is not the same thing as a backup from before the migration you are about to run.
Pin the tags and read the release notes
Both image tags in that file are pinned on purpose.
ghcr.io/plankanban/planka:2.2.1 is a specific release, current as of October 2026. Community 2.3.0 was released on November 4, 2026, with security fixes, and upstream recommends updating. Community 2.3.1 followed on November 5, 2026, fixing a crash when editing card descriptions on boards with a member who has no username. latest moves whenever upstream publishes, so a routine docker compose pull can bring in a schema migration at a moment you did not choose. Read the release notes before you change that number, because that is where breaking changes and security fixes are described. Version 2.0.3 was published as a security release, which is exactly the kind of thing you want to read rather than absorb by accident. So was 2.2.1, released August 2026: it fixes a path traversal flaw that let a logged-in user read arbitrary files on instances using local file storage, which is the setup in this guide, and the advisory lists 2.1.1 and earlier as affected. If you are coming from 2.1.x, read the 2.2.0 notes first, because that release deactivates users who only ever signed in through SSO until an admin gives them a password and reactivates them. Pinning is easy here because upstream publishes images at all, and where a project ships none you owe it the same discipline with an extra step, as with openGym built on the box from a checked-out git tag.
postgres:16-alpine is pinned to a major version for a harder reason. Postgres writes its data directory in a format tied to the major version, and the server refuses to open a directory written by a different one. Write postgres:latest, let the tag roll past 16, and the container will not start. The 17 image, for example, stops with:
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.Nothing is lost, and nothing is fixed by restarting either. Moving to a new Postgres major means a dump from the old version and a restore into a fresh data directory on the new one, a pg_upgrade run, which converts the data without a dump but needs the old and new server binaries available together, or logical replication to a server running the new version followed by a switchover. Each route is a planned migration, not a side effect of an image pull; logical replication lets the old server keep running while the new one catches up.
If you are moving an existing Planka 1.x install rather than starting fresh, that upgrade has its own documented procedure in the project documentation, and there is no way back to version 1 without a backup taken beforehand.
Failure modes and the strings you will see
Planka restarts in a loop and the log names the database. The credentials in DATABASE_URL do not match the Postgres environment. Note that POSTGRES_PASSWORD is only applied when the data directory is first initialised, so fixing the variable after a bad first boot changes nothing. Change the database role's password with ALTER ROLE to match the configured password; removing the db-data volume is only an option for a disposable installation with no data to keep.
Login succeeds and the board never loads. BASE_URL does not match the address in the browser bar, so the server rejects the socket's origin. The browser console shows failing requests to /socket.io/.
Uploads fail while everything else works. A bind mount owned by root. Run sudo chown -R 1000:1000 on the host directory and restart the container.
Attachments disappeared after an upgrade. /app/data was not attached to the original uploads volume. Reattach that volume or restore the files from a backup, then use a named volume before you touch the image tag again.
Traefik returns 404. No router matched the request: the Host() rule does not match your DNS record, or the labels never reached Traefik. docker compose config shows the labels after substitution, which is where typos become visible. A 502 instead means the route matched and the container could not be reached, so check that it is on the proxy network.
Notifications or webhooks never arrive. Planka 2 sends its outgoing HTTP requests through an internal filter, and the default block list covers localhost and postgres. A webhook aimed at localhost is blocked by design, and once you set OUTGOING_ALLOWED_HOSTS, every host not on that list is blocked too. Point the webhook at the other container's service name, and add that name to OUTGOING_ALLOWED_HOSTS if you use an allow list, rather than removing the filter.
Once it is running the operational load is small. Watch the release notes, and dump the database before every upgrade. A reboot brings the stack back on its own because of restart: unless-stopped, as long as the Docker service itself is enabled at boot, and Compose stacks that come back after a reboot covers the cases where it does not.
FAQ
Why does Planka load forever after I log in?
The credentials were accepted and the live connection was not. The browser opens its socket to the page's origin, while Planka derives its allowed socket origins from BASE_URL, so leaving that variable at http://localhost:3000 while you reach the site at https://kanban.example.com makes the server reject the connection. The developer console shows failing requests to /socket.io/. Set BASE_URL to the exact public address with no trailing slash, add TRUST_PROXY=true so the app honours the X-Forwarded-Proto header from your reverse proxy, then run docker compose up -d.
How do I create the first Planka admin user?
Since version 1.13 no administrator is created automatically. Either set DEFAULT_ADMIN_EMAIL with its matching password, name and username variables and start the stack, or run docker compose run --rm planka npm run db:create-admin-user and answer the prompts. The interactive command is the safer one on a shared server, because the password never enters the container's configured environment where docker inspect can read it. Keeping DEFAULT_ADMIN_EMAIL set afterwards prevents changes to that account's name, role and email address, and blocks its deletion from the interface. Remove DEFAULT_ADMIN_PASSWORD after setup, because leaving it set resets the matching account's password on startup.
Where does Planka store attachments and avatars?
All uploaded files live under /app/data inside the container in Planka 2, including attachments, user avatars and board backgrounds. Mount that path on a named volume. Without an explicit mount, the Docker image uses an anonymous volume, which a subsequent docker compose up does not automatically reconnect after docker compose down. A bind mount works too, but the Node process runs as UID 1000, so run sudo chown -R 1000:1000 on the host directory or uploads fail with a permission error.
How much RAM does a self-hosted Planka need?
The project's technical FAQ recommends at least 2 GB RAM and 10 GB storage for small teams. The default Docker deployment runs a Node process, a Postgres server with a backend process per open connection, and an internal Squid proxy for outgoing request filtering. Run docker stats --no-stream after a normal week and size from your own numbers. Watch the disk more closely than the memory, because attachments are what grows.
How do I upgrade Planka without losing data?
Dump the database and archive the uploads volume immediately before the upgrade, not on last night's schedule. Use docker compose exec -T postgres pg_dump -U planka -d planka > planka-db.sql, keeping the -T to disable pseudo-terminal allocation for the redirected output. Read the release notes for every version you skip, change the image tag to a specific release rather than latest, then run docker compose pull and docker compose up -d and watch the log for the migration. Leave the Postgres tag pinned to its major version, because the server refuses to open a data directory written by a different major.