Introduction

This guide introduces how to self-host Kan. It starts with the minimal Docker Compose setup (web + migrate + 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.

Migrate

One-off service that runs database migrations before web starts.

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

Create a docker-compose.yml

Paste the following minimal configuration into a new docker-compose.yml file:

services:
  migrate:
    image: ghcr.io/opscape/kan-migrate:latest
    container_name: kan-migrate
    networks:
      - kan-network
    environment:
      POSTGRES_URL: postgresql://kan:your_postgres_password@postgres:5432/kan_db
    depends_on:
      postgres:
        condition: service_healthy
    restart: "no"

  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:
      migrate:
        condition: service_completed_successfully
    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
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U kan -d kan_db"]
      interval: 5s
      timeout: 5s
      retries: 10
    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.

Start the stack

Bring everything up in detached mode:

docker compose up -d

The migrate service runs the database migrations to completion before the web service starts, so once it’s up open http://localhost:3000.

Manage the containers

Useful commands while developing or testing:

Stop the containers: docker compose down
View logs: docker compose logs -f
View logs for a specific service: docker compose logs -f web or docker compose logs -f migrate
Restart: docker compose restart

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 <hello@mail.opscape.com>"
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.

Get Started

Guides

Import

What you’ll set up

Kan

Migrate

PostgreSQL 15

Prerequisites

Quick start

Reference

​What you’ll set up

Kan

Migrate

PostgreSQL 15

​Prerequisites

​Quick start

​Reference

What you’ll set up

Prerequisites

Quick start

Reference