kanbn/kan: a self-hosted Trello alternative built on Next.js and tRPC

The problem Kan targets: Trello's model without Trello's hosting

Kan is a board-based project management tool. Cards move between lists, boards carry visibility settings, workspaces hold members, and cards collect labels, comments and an activity log. That is the Trello vocabulary almost verbatim, and the README says so directly: Kan is "The open-source project management alternative to Trello." The audience is therefore narrow and specific. It is for a team that already thinks in boards and cards, wants the data on hardware it controls, and is willing to run a web application plus a database to get that. It is not a general-purpose issue tracker and it is not a document tool. The feature list is deliberately board-centric: board visibility, workspace members, Trello imports, labels and filters, comments, activity log, and reusable board templates. If your workflow does not map onto lists of cards, the product has little to offer you.

Architecture: a Turborepo monorepo with a migration gate in front of the web app

The repository is a pnpm workspace driven by Turborepo, with an apps/ directory and a packages/ directory. The web application is Next.js, the API layer is tRPC, authentication is Better Auth, the ORM is Drizzle, and the schema validation library is Zod. Those are the topics the repository declares, and the README's "Made With" list matches them. The deployment shape is the interesting part. The compose file defines three services: postgres, migrate, and web. The migrate service runs the ghcr.io/kanbn/kan-migrate image and depends on Postgres reporting healthy through pg_isready. The web service then declares depends_on with condition: service_completed_successfully against migrate, so the application container does not start until migrations have exited cleanly. That ordering is the whole reason the compose file exists in the form it does, and it means a failed migration stops the deployment rather than serving a web app against a half-migrated schema. The database package is separate, which is why the root package.json exposes a db:migrate script that changes into packages/db before running the migration.

Installing Kan with Docker Compose and reaching the first board

The README offers two paths. Railway hosts an official one-click template, and Docker Compose is the self-managed path. Start by creating a .env file. The .env.example file names two required values: NEXT_PUBLIC_BASE_URL and BETTER_AUTH_SECRET. The example suggests generating the secret with a shell pipeline, and it also defines POSTGRES_PASSWORD, which the compose file needs because the bundled Postgres service reads it.

openssl rand -base64 26 | tr -dc 'a-zA-Z0-9' | head -c 32

The README's compose configuration wires the web container to port 3000 and maps it through WEB_PORT, defaulting to 3000. The migrate service receives POSTGRES_URL and waits for the Postgres healthcheck. Bring everything up in detached mode.

docker compose up -d

Migrations run first, then the web container starts. The application should be reachable at http://localhost:3000, or at whatever port you set in WEB_PORT. To follow startup, use docker compose logs -f, or narrow it with docker compose logs -f migrate to confirm the migration step finished before the web service came up.

If you prefer to run from source, the README's local development steps are a clone, then pnpm install, then copying .env.example to .env, then pnpm db:migrate, then pnpm dev. The root package.json pins the toolchain: Node >=20.18.1 and pnpm 9.14.2. That constraint is enforced through the engines field, so an older Node will fail before anything useful happens.

pnpm install
pnpm db:migrate
pnpm dev

Once you are in, the README points at Trello imports as a way to bring existing boards across, which is the fastest route to a first real board rather than an empty one you build by hand.

Environment variables decide which features exist at all

Kan is not one binary with optional flags. Several capabilities are compiled into behaviour by presence or absence of configuration. Email is the clearest case: SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD and EMAIL_FROM are all optional, and NEXT_PUBLIC_DISABLE_EMAIL switches email features off entirely. If you set nothing, you get an instance that cannot send mail, which matters for anything that depends on notifications or verification. Redis is similarly optional: REDIS_URL enables rate limiting, and the .env.example states that without it, rate limiting falls back to in-memory storage. That fallback is fine for a single process and wrong for a multi-replica deployment, where each replica would keep its own counters. S3 storage is optional too, with S3_ENDPOINT for S3-compatible providers such as MinIO, R2 and Spaces, and S3_REGION described as required for AWS S3 but ignored by most compatible providers. The .env.example also carries NEXT_API_BODY_SIZE_LIMIT, defaulting to 1mb, which is the kind of default you only notice when an upload fails. Treat the .env.example file as the real feature matrix for a self-hosted install.

Where Kan is the wrong tool

The README lists "Integrations (coming soon)" as a feature, which is a frank way of saying the integration surface does not exist yet. If your team's workflow assumes a Trello Power-Up, a calendar sync, or a chat bridge, Kan will not carry it today, and the roadmap link is where the project tracks what is planned. A second limitation is operational. The compose file runs a floating latest tag for both the web and migrate images, and the repository does not document a rollback procedure. There is no described downgrade path if a migration succeeds and the new version misbehaves. A third point is the licence. AGPL-3.0 is a strong copyleft licence, and it is a different proposition from a permissively licensed tool if you intend to modify Kan and expose it to users over a network. Finally, the documentation is thin in places: the README does not document rollback, and it does not describe a backup or restore procedure for the Postgres volume, even though the compose file creates a named volume for exactly that data.

How Kan differs from Planka and from Trello itself

The closest comparison in the same category is Planka, another open source, self-hosted board tool. The practical difference visible here is the stack and the deployment ritual. Kan ships a dedicated migration container and refuses to start the web service until migrations complete, which encodes schema discipline into the compose file rather than leaving it to an operator. Kan's stack is also unambiguously a TypeScript monorepo: Next.js, tRPC, Drizzle, Better Auth, Tailwind, Turborepo. That matters if you plan to contribute or fork, because the codebase will feel familiar to a Next.js developer and foreign to someone who prefers a smaller server-rendered application. Against Trello, the difference is not features but ownership. Trello gives you an ecosystem, hosted upgrades and an integration directory. Kan gives you the database file, the containers and the responsibility. The README's own framing, an "open-source project management alternative to Trello," is honest about which half of that trade you are taking.

Maintenance, upgrades and licence cost

The repository is not archived, and the last push was on 2026-09-22. Releases are tagged and dated: v0.6.0 on 2026-06-29, v0.5.6 on 2026-03-19 and v0.5.5 on 2026-03-12. The version numbering sits below 1.0, which is worth weighing if you are putting a team's daily work into it. Upgrading means pulling new images, letting the migrate container run, and starting the web container again; the compose file's dependency ordering enforces the sequence, but nothing in the README describes how to reverse it. The repository does carry a CHANGELOG.md at the top level, so reading the entry for the version you are moving to is the concrete pre-upgrade step. On licensing, Kan is AGPL-3.0. That is a copyleft licence with a network clause, and it is a materially different obligation from MIT or Apache-2.0 if you modify the code and let users interact with it over a network. Whether that affects your organisation is a question for your own counsel, not for this article.

Editorial conclusion

Adopt Kan if you want a Trello-shaped board on infrastructure you control and you are comfortable running Postgres plus two containers. Do not adopt it if you depend on third-party integrations or on a vendor handling upgrades for you, because the README still lists integrations as coming soon and there is no documented rollback path. Before committing, verify that the ghcr.io/kanbn/kan and ghcr.io/kanbn/kan-migrate images you pull match a release tag you can name, and check the current CHANGELOG.md entry rather than trusting a floating latest tag.

Frequently asked questions

Official sources

1. kanbn/kan on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases