SSD Nodes Learn Hosting plans →
How to do am Matt ConnorBy Matt Connor

How to Self-Host Planka with Docker Compose

Deploy Planka 2 on VPS with Docker Compose, Postgres, and Traefik. Avoid login failure caused by wrong BASE_URL and set admin bootstrap variables correctly.

Wetin you go gain when you self-host Planka

When you self-host Planka, your team go get Kanban board wey use the card, list, and label model people already know from Trello, but e go run for VPS wey you control. No seat limit or per-user billing dey, because na only the server cost you go pay. This guide deploys am with Docker Compose behind Traefik, using Postgres for the data and named volume for every file wey people upload.

Planka 2 dey ship under the project own Fair Use License. The project describes am as source-available, no be open source. You fit run am for your organisation internal projects. If you wan offer am to third parties as commercial hosted service, you need Pro or Enterprise licence.

The reader wey I get for mind na team of two to five people wey dey comot from Trello free tier. If you never decide which board to run, first read comparison of self-hosted Trello alternatives. This guide assume say you don already choose, and e cover only the deploy.

You need VPS wey dey run Docker Engine with Compose plugin, plus DNS A record wey point to am. You also need Traefik instance wey already dey terminate TLS (transport layer security) for that server. If Traefik never dey there, first set up Traefik reverse proxy in front of several Compose apps, and read Docker Compose basics for a VPS if the file below no clear to you.

How much VPS Planka need?

The project technical FAQ recommend at least 2 GB RAM and 10 GB storage for small teams, so take those numbers as starting point, no be exact measurement.

Wetin dey actually run small: one Node.js process wey dey serve the API and the built frontend, plus one Postgres server wey dey hold the data. Postgres dey run one supervising process and one backend process for each open connection. One small proxy process dey also run inside the Planka container to filter its outgoing requests. 2 GB plan match the project RAM recommendation for small teams. Board no dey use plenty resources, so if the same VPS go also hold your team documents, size the server based on that app first: running AFFiNE as a Notion-style workspace need a couple of gigabytes by itself before Planka add anything.

Size the disk before you size the memory, because attachments na the part wey dey grow. Measure your own instance instead of trusting this paragraph:

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

The first command dey show live memory and CPU usage for each container. The second one dey show how much space each volume get. Take both readings after one normal working week, no be on install day, because idle board no fit tell you anything about your team.

Write the Compose file

Create the directory and take ownership of it, so you no longer need to edit these files through sudo.

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

Generate the secrets into a .env file beside the Compose file. Compose go read that file automatically and substitute 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 .env

openssl rand -hex na intentional choice. A hex string get only digits and letters from a to f, so e no fit damage the DATABASE_URL connection string wey e enter. Standard Base64 fit contain slash, plus sign, and padding equals sign, but e no ever contain at sign; characters wey get special meaning for connection URL need percent-encoding. The wider pattern dey covered for keeping secrets out of the Compose file.

Now docker-compose.yml. Replace kanban.example.com with your own hostname for both places wey e appear.

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 for that file deserve explanation, because na dem people dey change and later regret.

  • No ports: block dey for the Planka service. Traefik reaches the container across the proxy network, so port 1337 no ever publish for the host. Publishing am go give anybody way to bypass your proxy and your certificate.
  • loadbalancer.server.port=1337 names the port inside the container. Planka dey listen on 1337, and the upstream example only reaches am on 3000 because e maps the port to the host. No host mapping dey here, so you must tell Traefik the container port.
  • condition: service_healthy dey work together with the Postgres healthcheck. Without am, Planka starts before the database accept connections, e fail for the first query and exit, which fit look like crash loop. The mechanics dey for Compose healthchecks and startup ordering.
  • The database service name na postgres deliberately. Planka 2 routes its own outgoing requests through an internal filter wey default block list na localhost,postgres. If you rename the service, you quietly remove your database from that list.

Check say Compose fit see your secrets before you start anything:

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

That command go print the file with .env values already substituted. Empty value mean say Compose no dey read the .env file, usually because you dey run the command from another directory.

Wetin admin bootstrap variables really dey do

Since Planka 1.13, no administrator dey created for you, so fresh database no get anybody wey fit log in. The DEFAULT_ADMIN_* group na one of the two ways to fix this.

When e start, Planka dey look for user wey match DEFAULT_ADMIN_EMAIL. If e no find any, e go create one with the password, display name, and username wey you set alongside am. For later starts, e still dey update matching account from these variables, including resetting the password when DEFAULT_ADMIN_PASSWORD remain set.

DEFAULT_ADMIN_EMAIL dey do another work wey dey catch people unaware. As long as the variable remain set, you no fit change the account name, role, or email address, and you no fit delete the account through the interface. This na lock-out guard. Na why you no fit rename that account or change its email address for the UI. Remove the variable and restart, then the account go become normal admin wey you fit edit like any other one.

Na the password line you need handle carefully. Anything under environment: anybody wey fit run docker inspect on the container fit read, so DEFAULT_ADMIN_PASSWORD no suppose remain there permanently. Log in, delete that line, run docker compose up -d again, then change your password for the interface.

The cleaner way na to skip the variables completely. Comment out the whole DEFAULT_ADMIN_* group, then create the account interactively:

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

E go ask for email, password, display name, and optional username, then write the user directly to the database. The password no go touch the Compose file or the container configured environment. Use this way if more than one person get shell access to the VPS. The command go start Postgres first because of depends_on, so e go work for stack wey never come up before.

Either way, you still go manage Planka passwords by hand. Up to version 2.1.1, Community edition fit hand logins over to OIDC provider like Authentik wey dey run as your own single sign-on server, but version 2.2.0, wey release for August 2026, move OIDC and SSO enter PLANKA Pro. Wetin Community edition gain for the same release na two-factor authentication (TOTP) for local accounts, so turn am on for admin account at least.

Why BASE_URL dey break logins when e no match hostname

BASE_URL na the exact address wey people dey type for browser, together with scheme and without trailing slash. For this stack, na https://kanban.example.com. Planka dey build its own links and list of allowed WebSocket origins from this value. So, wrong BASE_URL no go give you clear error. E go give you page wey load, then e no go ever finish loading.

The common case be say: you copy upstream example, leave BASE_URL=http://localhost:3000 as e be, then access site over HTTPS with your real domain. Login form dey submit and e accept your credentials. But board no dey show. Open browser developer console, and you go see requests to /socket.io/ dey fail. This one happen because socket dey connect to browser page origin, but server origin restriction allow the origin wey e derive from BASE_URL.

TRUST_PROXY=true na the other part of the same problem. Planka dey behind Traefik, so every request dey reach am from proxy address through plain HTTP inside Docker network. Without TRUST_PROXY, app dey ignore X-Forwarded-Proto and X-Forwarded-For headers wey Traefik set. So e believe say connection no secure, and e treat every client as one shared IP address. When you set am, app dey read those headers and agree with browser about the scheme.

Traefik dey proxy WebSockets without extra configuration, and na one reason why e good to use am here. For nginx, proxy must forward upgrade headers, proxy_set_header Upgrade $http_upgrade and proxy_set_header Connection "upgrade", or you go get the same stuck spinner from another cause. Dem fit dey inside general location / block. Separate block for /socket.io fit work too, but e no required.

If you move board go new hostname later, change two things together: the BASE_URL value and Traefik Host() rule. If you change one and forget the other, spinner go come back. Serving Planka from subpath like https://example.com/planka dey work from version 2.1.0 onward, wey release for March 2026. For older tags, give am subdomain of its own.

Where Planka dey keep attachments and avatars

Planka 2 dey store everything wey user upload under one path inside the container: /app/data. Attachments, user avatars and board background images all dey there. Version 1 use three separate directories, so Compose file wey dem copy from older write-up dey mount paths wey no longer exist, and the data mount wey dem intend no dey there.

That one mount na the difference between board wey go survive upgrade and bad afternoon. Docker image declare /app/data as a volume, so if you no put the mount for Compose, uploads go enter anonymous volume. Compose dey preserve am during normal up recreation, but later down followed by up no go reconnect am automatically. Board go come back looking fine, all cards go still dey there, and every attachment link go dead, because database rows still dey point to files for the old volume.

The named volume for the Compose file above prevent this problem. Bind mount dey work too and make files easier to back up with ordinary tools, but e need one extra step. The Node process inside the container dey run as UID 1000, so if host directory belong to root, first upload go fail with permission error:

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

The trade-off between the two dey explained for bind mounts against named volumes.

If attachments don pass the disk capacity for your plan, Planka fit write dem to S3-compatible storage instead, through S3_ENDPOINT, S3_BUCKET and the matching key variables. E fit point to hosted bucket or self-hosted MinIO object store for another box. Decide this before the team fill the board, because enabling S3 go switch file reads and writes to that backend without migrating uploads wey already dey there.

Start the stack and check say e work

docker compose pull
docker compose up -d
docker compose ps

docker compose ps suppose show postgres as healthy and planka as running. If Planka dey restart for loop, database connection na the first thing to check, no be the app.

docker compose logs -f planka

Healthy first boot dey run database migrations, but production configuration set noShip: true and suppress the startup message wey dey report port 1337. Confirm say schema really land by asking Postgres directly instead of trusting the log:

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

Table list wey include board and card mean say migrations run. "Did not find any relations" mean say Planka never connect, so compare DATABASE_URL against POSTGRES_USER and POSTGRES_PASSWORD values for your .env.

Then check the route from your own machine, no be from the VPS:

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

HTTP/2 200 mean say Traefik get certificate and e dey reach the container. 404 wey Traefik serve mean say no router match the request: Host() rule no match the hostname wey you request, or Traefik never pick up the labels. 502 mean say router match but Traefik no fit reach the container, for example because e no attach to proxy network. Now open the site and log in with the admin account.

Take pg_dump before every version bump

Two separate stores hold your board, so backup must cover both: the Postgres database and the planka-data volume. Dump the database while the stack dey run.

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

The -T dey disable Compose default pseudo-terminal allocation, so the dump go remain for plain output stream.

Then handle the uploads. First find the real volume name, because Compose dey add the project directory name as prefix.

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 get docker-backup.sh and docker-restore.sh for its repository, and the official documentation dey put dem for nightly cron job. Any of the two approaches dey okay. But backup wey you never restore no good, so restore one for scratch VPS once. Confirm say you fit log in and open attachment. This same pair of stores dey show for every Compose app wey accepts uploads. So if later you put Chatwoot for the same box as your support desk, the routine wey you build here go carry over with only small change to the volume names.

Run the dump immediately before every version change. Backup from last night no be the same as backup wey you take before the migration wey you dey about to run.

Pin the tags and read the release notes

Both image tags for that file dey pinned on purpose.

ghcr.io/plankanban/planka:2.2.1 na specific release, current as of October 2026. Community 2.3.0 release on November 4, 2026, with security fixes, and upstream recommend update. Community 2.3.1 follow on November 5, 2026, fixing crash wey happen when you edit card descriptions for boards wey get member without username. latest dey change whenever upstream publish, so routine docker compose pull fit bring schema migration at time wey you no choose. Read the release notes before you change that number, because na there dem describe breaking changes and security fixes. Version 2.0.3 publish as security release, and na exactly the kind thing wey you suppose read instead of absorbing by mistake. Same thing happen with 2.2.1, released August 2026: e fix path traversal flaw wey allow logged-in user read arbitrary files for instances wey use local file storage, na the setup for this guide, and the advisory list 2.1.1 and earlier as affected. If you dey come from 2.1.x, read 2.2.0 notes first, because that release deactivate users wey only ever sign in through SSO until admin give dem password and reactivate dem. Pinning easy here because upstream dey publish images at all, and where project no ship any, you still owe am the same discipline with one extra step, like openGym wey you build on the box from a checked-out git tag.

postgres:16-alpine pin to major version for a stronger reason. Postgres write its data directory in format wey tie to the major version, and server refuse to open directory wey another version write. Write postgres:latest, allow the tag pass 16, and the container no go start. The 17 image, for example, stop 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 dey lost, and restarting no go fix anything either. Moving to new Postgres major mean dump from the old version and restore into fresh data directory for the new one, a pg_upgrade run, wey convert the data without dump but need old and new server binaries available together, or logical replication to server wey dey run the new version, followed by switchover. Each route na planned migration, no be side effect of image pull; logical replication allow the old server continue running while the new one catch up.

If you dey move existing Planka 1.x install instead of starting fresh, that upgrade get its own documented procedure for the project documentation, and no way dey go back to version 1 without backup wey you take beforehand.

Failure mode and the strings wey you go see

Planka restart for loop and log mention the database. The credentials for DATABASE_URL no match the Postgres environment. Note say POSTGRES_PASSWORD only dey apply when e initialise the data directory for the first time, so if you fix the variable after the first boot fail, e no go change anything. Change the database role password with ALTER ROLE so e match the configured password; you fit only remove the db-data volume if na disposable installation and no data dey inside wey you need keep.

Login succeed but the board no ever load. BASE_URL no match the address for the browser bar, so the server reject the socket origin. The browser console go show failed requests to /socket.io/.

Uploads fail while every other thing dey work. A bind mount dey owned by root. Run sudo chown -R 1000:1000 for the host directory, then restart the container.

Attachments disappear after upgrade. /app/data no attach to the original uploads volume. Attach that volume again or restore the files from backup, then use a named volume before you touch the image tag again.

Traefik return 404. No router match the request: the Host() rule no match your DNS record, or the labels no reach Traefik. docker compose config show the labels after substitution, and na there typo dey show. If e return 502 instead, e mean say the route match but the container no fit reach; check say e dey on the proxy network.

Notifications or webhooks no ever arrive. Planka 2 dey send outgoing HTTP requests through an internal filter, and the default block list cover localhost and postgres. Webhook wey target localhost dey blocked by design, and once you set OUTGOING_ALLOWED_HOSTS, every host wey no dey that list go dey blocked too. Point the webhook to the other container service name, and add that name to OUTGOING_ALLOWED_HOSTS if you dey use an allow list, instead of removing the filter.

Once e dey run, the operational load small. Monitor the release notes, and dump the database before every upgrade. Reboot go bring the stack back by itself because of restart: unless-stopped, as long as the Docker service itself dey enabled at boot, and Compose stacks wey come back after reboot cover the cases where e no do so.

FAQ

Planka login dey load forever. Why?

Credentials accept, but live connection no connect. Browser dey open socket go the page origin, while Planka dey derive allowed socket origins from BASE_URL. So, if you leave that variable as http://localhost:3000 while you dey reach the site through https://kanban.example.com, server go reject the connection. Developer console go show failed requests to /socket.io/. Set BASE_URL to the exact public address without trailing slash. Add TRUST_PROXY=true so the app go honour the X-Forwarded-Proto header from your reverse proxy. Then run docker compose up -d.

How I fit create the first Planka admin user?

From version 1.13, system no dey create administrator automatically. You fit either set DEFAULT_ADMIN_EMAIL with the matching password, name, and username variables, then start the stack; or run docker compose run --rm planka npm run db:create-admin-user and answer the prompts. The interactive command safer for shared server, because the password no dey enter the container environment wey docker inspect fit read. If you leave DEFAULT_ADMIN_EMAIL set afterwards, nobody fit change that account name, role, or email address, and dem no fit delete am from the interface. Remove DEFAULT_ADMIN_PASSWORD after setup, because if you leave am set, e go reset the matching account password whenever startup happen.

Where Planka dey store attachments and avatars?

All uploaded files dey under /app/data inside the container for Planka 2. This one include attachments, user avatars, and board backgrounds. Mount that path on a named volume. If you no mount am explicitly, Docker image go use anonymous volume. A later docker compose up no go reconnect that volume automatically after docker compose down. Bind mount dey work too, but Node process dey run as UID 1000. So run sudo chown -R 1000:1000 on the host directory, or uploads go fail with permission error.

How much RAM self-hosted Planka need?

The project technical FAQ recommend at least 2 GB RAM and 10 GB storage for small teams. Default Docker deployment dey run one Node process, Postgres server with one backend process for every open connection, and internal Squid proxy for filtering outgoing requests. Run docker stats --no-stream after one normal week, then size the system from your own numbers. Monitor disk more closely than memory, because attachments na wetin dey grow.

How I fit upgrade Planka without losing data?

Dump the database and archive the uploads volume immediately before the upgrade. No use last night's scheduled backup. Use docker compose exec -T postgres pg_dump -U planka -d planka > planka-db.sql, and keep the -T so redirected output no go allocate pseudo-terminal. Read the release notes for every version wey you skip. Change the image tag to a specific release instead of latest. Then run docker compose pull and docker compose up -d, and monitor the log for the migration. Keep the Postgres tag pinned to its major version, because the server no go open data directory wey another major version write.

Dis article help you?