Introduction

Overview and quick start to run Kan on your own infrastructure using Docker Compose.

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/opscape/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.

   Common variables

   # Required
   NEXT_PUBLIC_BASE_URL=http://localhost:3000
   BETTER_AUTH_SECRET=replace_with_long_random_string
   POSTGRES_URL=postgresql://kan:your_postgres_password@postgres:5432/kan_db
   
   # Optional: Email
   EMAIL_FROM="Kan <[e-mail]>"
   SMTP_HOST=smtp.resend.com
   SMTP_PORT=465
   SMTP_USER=resend
   SMTP_PASSWORD=re_xxxx
   SMTP_SECURE=true
   
   # Optional: Auth toggles
   NEXT_PUBLIC_ALLOW_CREDENTIALS=true
   NEXT_PUBLIC_DISABLE_SIGN_UP=false
   

   If you plan to enable file uploads (avatars, etc.), you’ll also need S3 variables (S3_ENDPOINT, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, NEXT_PUBLIC_STORAGE_URL, NEXT_PUBLIC_STORAGE_DOMAIN, …). See the S3 guide linked at the top.

Reference

• GitHub README
• GitHub docker-compose.yml