> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kan.bn/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<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 theme={null}
    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 theme={null}
    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 theme={null}
      # 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)