---
title: "Introduction"
description: "Overview and quick start to run Kan on your own infrastructure using Docker Compose."
mode: "wide"
tag: "NEW"
---

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

<CardGroup cols={2}>
  <Card title="Kan" icon="globe" color="#0284c7" horizontal>
    Next.js application served on port 3000.
  </Card>
  <Card title="PostgreSQL 15" icon="database" color="#65a30d" horizontal>
    Primary database for Kan data.
  </Card>
</CardGroup>

<Note>
  For file uploads (avatars), OAuth, and other advanced options, see the
  Environment Variables section in the README and the dedicated [S3
  guide](/guides/self-hosting/s3). The [full
  compose](https://github.com/kanbn/kan/blob/main/docker-compose.yml) in the
  repo includes a richer configuration via <code>.env</code>.
</Note>

## Prerequisites

- Docker and Docker Compose
- A long random string for <code>BETTER_AUTH_SECRET</code> (32+ chars)

## Quick start

<Steps>
  <Step title="Create a docker-compose.yml">
    Paste the following minimal configuration into a new <code>docker-compose.yml</code> file:

    ```yaml
    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:
    ```

    <Tip>
      The example above is intentionally minimal. The repository provides a more feature-complete compose file at [docker-compose.yml](https://github.com/kanbn/kan/blob/main/docker-compose.yml) if you want environment-based configuration, OAuth, S3, and more.
    </Tip>

  </Step>

  <Step title="Start the stack">
    Bring everything up in detached mode:

    ```bash
    docker compose up -d
    ```

    Once started, open [http://localhost:3000](http://localhost:3000).

  </Step>

  <Step title="Manage the containers">
    Useful commands while developing or testing:

    - Stop the containers: <code>docker compose down</code>
    - View logs: <code>docker compose logs -f</code>
    - Restart: <code>docker compose restart</code>

  </Step>

  <Step title="Configure environment (optional)">
    For a production-like setup and more features (email, OAuth, file uploads, etc.), create a <code>.env</code> file and set the relevant variables shown in the README’s Environment Variables section.

    <Accordion title="Common variables">
      ```bash
      # 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.kan.bn>"
      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
      ```

      <Note type="warning">
        If you plan to enable file uploads (avatars, etc.), you’ll also need S3 variables (<code>S3_ENDPOINT</code>, <code>S3_ACCESS_KEY_ID</code>, <code>S3_SECRET_ACCESS_KEY</code>, <code>NEXT_PUBLIC_STORAGE_URL</code>, <code>NEXT_PUBLIC_STORAGE_DOMAIN</code>, …). See the S3 guide linked at the top.
      </Note>
    </Accordion>

  </Step>
</Steps>

## Reference

- [GitHub README](https://github.com/kanbn/kan/blob/main/README.md#self-hosting-)
- [GitHub docker-compose.yml](https://github.com/kanbn/kan/blob/main/docker-compose.yml)