This guide introduces how to self-host Kan. It starts with the minimal Docker Compose setup (web + PostgreSQL) and points you to optional features like email and S3-based file storage.

​
What you’ll set up

Kan

Next.js application served on port 3000.

PostgreSQL 15

Primary database for Kan data.
For file uploads (avatars), OAuth, and other advanced options, see the Environment Variables section in the README and the dedicated S3 guide. The full compose in the repo includes a richer configuration via .env.

​
Prerequisites

  • Docker and Docker Compose
  • A long random string for BETTER_AUTH_SECRET (32+ chars)

​
Quick start

1

Create a docker-compose.yml

Paste the following minimal configuration into a new docker-compose.yml file:
services:
  web:
    image: ghcr.io/kanbn/kan:latest
    container_name: kan-web
    ports:
      - "3000:3000"
    networks:
      - kan-network
    environment:
      NEXT_PUBLIC_BASE_URL: http://localhost:3000
      BETTER_AUTH_SECRET: your_auth_secret
      POSTGRES_URL: postgresql://kan:your_postgres_password@postgres:5432/kan_db
      NEXT_PUBLIC_ALLOW_CREDENTIALS: true
    depends_on:
      - postgres
    restart: unless-stopped

  postgres:
    image: postgres:15
    container_name: kan-db
    environment:
      POSTGRES_DB: kan_db
      POSTGRES_USER: kan
      POSTGRES_PASSWORD: your_postgres_password
    ports:
      - 5432:5432
    volumes:
      - kan_postgres_data:/var/lib/postgresql/data
    restart: unless-stopped
    networks:
      - kan-network

networks:
  kan-network:

volumes:
  kan_postgres_data:
The example above is intentionally minimal. The repository provides a more feature-complete compose file at docker-compose.yml if you want environment-based configuration, OAuth, S3, and more.
2

Start the stack

Bring everything up in detached mode:
docker compose up -d
Once started, open http://localhost:3000.
3

Manage the containers

Useful commands while developing or testing:
  • Stop the containers: docker compose down
  • View logs: docker compose logs -f
  • Restart: docker compose restart
4

Configure environment (optional)

For a production-like setup and more features (email, OAuth, file uploads, etc.), create a .env file and set the relevant variables shown in the README’s Environment Variables section.

​
Reference