PLANKA: self-hosted Kanban with a paid Pro tier bolted onto the same database

What PLANKA is and who it is aimed at

PLANKA is a Kanban board you host yourself. The repository describes it as "Elegant open source project tracking" and lists projects, boards, lists and cards with drag-and-drop, markdown descriptions, attachments, comments, custom fields, due dates and a stopwatch. Real-time updates are pushed to every connected user, so two people moving cards on the same board do not need to refresh.

The target user is a team that wants Trello-shaped workflows without handing the board to a vendor. The README's own topics include "trello-alternative" and "self-hosted", and the Community column of the feature table is where the free tier lives: boards, real-time collaboration, notifications through 100+ providers, webhooks, a documented REST API, two-factor authentication, and the promise that the database and backups stay yours. Everything a small team needs to run a sprint board is in that column.

The split matters more than the feature list. PLANKA ships two editions from one repository, and the boundary is drawn around mobility and reporting: phones and tablets, five themes, calendar, timeline, map and media views, recurring cards, templates, one card on multiple boards, guest roles, OIDC single sign-on, and PDF or HTML export are all Pro. If any of those is a hard requirement, you are evaluating a commercial product, not the Community edition.

How the server, database and client fit together

The Dockerfile is the clearest description of the architecture. It builds in three stages. The first copies server/ into a node:24-alpine image, runs npm install and npm run build, then prunes to production dependencies. The second copies client/ into a plain node:24 image and builds the front end with INDEX_FORMAT=ejs and DISABLE_ESLINT_PLUGIN=true. The third stage, also node:24-alpine, copies the compiled server into /app, the compiled client into /app/public, installs bash, python3 and squid, creates a Python virtual environment from requirements.txt, and moves public/index.ejs into views.

The final image runs as the node user, exposes port 1337, declares /app/data as a volume, and starts through ./start.sh. A healthcheck runs node ./healthcheck.js every ten seconds after a fifteen-second start period. That is the whole runtime: one Node process serving the API and the static client, one PostgreSQL database behind it, and a data volume for uploads.

The compose file confirms the shape. The service is ghcr.io/plankanban/planka:latest, mapped as 3000:1337, so the container listens on 1337 internally and you reach it on 3000 unless you change the mapping. Two environment variables are mandatory in that file: BASE_URL, set to http://localhost:3000, and DATABASE_URL, set to postgresql://postgres@postgres/planka. The data volume is mounted at /app/data. There is no separate worker or queue in the Community deployment, which is why the compose file is short enough to read in one sitting.

Installing PLANKA with Docker Compose and logging in

The README points at an installation guide rather than reproducing steps, but the repository ships a docker-compose.yml that is meant to be used as-is with two edits. The first is the database connection; the second is the secret. The file itself warns that SECRET_KEY signs every access token, that leaving the published example value means anyone can mint a token for any account, and that PLANKA will warn on every start until it is changed. It suggests generating one with openssl rand -hex 32.

Start from the repository's compose file, replace the secret, and bring the stack up:

openssl rand -hex 32
docker compose up -d

The first command prints a 64-character hex string; paste it into the SECRET_KEY line in docker-compose.yml before running the second. The compose file also shows an alternative where the value comes from a file instead, using SECRET_KEY__FILE=/run/secrets/secret_key, in which case SECRET_KEY should not be set at all. The same pattern exists for the database password: DATABASE_URL can reference $${DATABASE_PASSWORD} and the password can arrive through DATABASE_PASSWORD__FILE.

Once the container is healthy, the board is at the BASE_URL you configured, which in the shipped example is http://localhost:3000. The compose file sets restart: on-failure, so a crash loop is visible rather than silent, and the healthcheck gives the container a defined readiness signal to report.

For a local checkout rather than a container, package.json defines the script surface. npm run server:db:init, npm run server:db:migrate and npm run server:db:seed handle the database, npm run server:db:create-admin-user creates the first account, and npm start runs the server and client together through concurrently. Those names come straight from package.json; the development guide linked from the README is where the full sequence lives.

The SECRET_KEY default and other operational sharp edges

The most concrete failure mode in the repository is the secret. docker-compose.yml ships SECRET_KEY=notsecretkey and states plainly that leaving it means anyone can mint a token for any account on the instance. This is not a subtle misconfiguration; it is a comment in the file telling you the default is unsafe. A PLANKA instance put on a network before that line is edited is compromised by design.

The second sharp edge is the Pro upgrade. The README describes it as an in-place upgrade of an existing Community installation: your database, your volume, your data. It is "a real migration rather than a new image", adding a Valkey service and a one-off schema promote. The promote only accepts certain Community releases as a starting point, currently 2.1.x and 2.2.x, and from any other version it stops without changing anything. The upgrade is one-way. There is no documented downgrade back to Community, and the README says to take a backup first or try it on a copy. Anyone who treats the trial as reversible should read that sentence twice.

The third is licensing. PLANKA is fair-code under the Fair Use License and the PLANKA Pro/Enterprise License, not an OSI-approved licence. The README frames this as source available, self-hostable and extensible, with enterprise licences available for additional features and support. That is a deliberate position, and it means the usual assumptions about forking and redistributing do not automatically hold.

Finally, support runs through GitHub and a Discord server. The README states that public support is not offered by email, and that security issues should be reported privately to [email protected] rather than as a public issue. If you need a contract with a response time, that is what the Pro tier is selling.

PLANKA against Trello and Vikunja

Trello is the comparison the project invites, and the difference is custody rather than features. Trello is hosted, so you get no database to back up, no volume to mount, and no SECRET_KEY to rotate. PLANKA gives you all three plus the obligation that comes with them. The trade is not close in either direction: Trello removes operational work and keeps the data; PLANKA removes the vendor and keeps the work. For a team without anyone who wants to own a PostgreSQL instance, hosted Trello is the honest answer.

Vikunja is the more interesting comparison because it is also self-hosted and open source. The difference is scope. PLANKA is a Kanban board first, with lists, cards, drag-and-drop and real-time sync as the centre of the product, and the Pro tier extends that into calendar, timeline and map views. Vikunja is a task manager that presents tasks in several layouts, including Kanban. If your team thinks in boards and wants the board to be the primary surface, PLANKA's model is closer to that; if you want one task list rendered as a list, a table or a board depending on the day, a general task manager is the better fit. Both put you in charge of the database, so the self-hosting cost is comparable and the decision comes down to which mental model your team already has.

Maintenance, releases and what an upgrade costs

The repository is not archived, and the last push was on 2026-09-10. Releases are frequent enough to matter: v2.2.0 and the planka-2.2.0 tag landed on 2026-08-09, and v2.2.1 followed on 2026-08-10. A patch release one day after a minor release is a normal pattern and suggests the maintainers are responding to what the minor broke.

Upgrade cost splits by edition. Community runs as a container against PostgreSQL, so the routine is pulling a new image and starting it; the compose file mounts /app/data and connects to an external database, and the repository ships docker-backup.sh and docker-restore.sh alongside it, which tells you the maintainers expect you to snapshot the volume and the database before changing anything. The server package exposes npm run server:db:migrate and npm run server:db:upgrade for the non-container path.

Pro is the expensive upgrade. It is a one-way schema promote that accepts only 2.1.x and 2.2.x Community releases as a starting point, adds a Valkey service, and has no documented path back. The step-by-step guide lives in the customer center once you hold a key, and it lists the releases the promote accepts. That means the accepted-version list is not fully visible in the repository, and a team planning a Pro migration should treat the customer center as the source of truth for whether their current version can move.

On licensing, the practical implication is that PLANKA is source available rather than OSI open source. Reading and self-hosting the Community edition is what the Fair Use License is for; anything beyond that, including the Pro and Enterprise terms, is a question for the licence guide in the LICENSES directory and, if it matters commercially, for your own counsel. Nothing here is legal advice.

Editorial conclusion

PLANKA Community is a reasonable fit for a team that already runs PostgreSQL, wants the board data on its own volume, and is willing to read the compose file before starting the container. It is the wrong choice if you need a downgrade path after trying Pro, if you want an OSI-approved licence rather than fair-code, or if mobile use is a requirement, since phones and tablets are listed as Pro-only. Before committing, check the SECRET_KEY value in docker-compose.yml, confirm your PostgreSQL connection string, and read the Pro migration notes to see which Community releases the schema promote accepts.

Frequently asked questions

Official sources

1. Issues
2. plankanban/planka on GitHub
3. Project website
4. README
5. Releases