Quick Start

Prerequisites

• Node.js 24+
• pnpm 9+
• Docker / Docker Compose

Setup

1. Clone the repository

git clone https://github.com/kukan-project/kukan.git
cd kukan
git checkout vX.Y.Z   # latest release (omit to stay on main for the development version)

See GitHub Releases for the list of releases.

2. Install dependencies

pnpm install

3. Start infrastructure

Start PostgreSQL, MinIO, ElasticMQ, OpenSearch, and Ollama with Docker Compose.

docker compose up -d

Ollama GPU acceleration (optional)

The bundled ollama service (used for vector search and AI metadata suggestions) runs on CPU by default. To use a GPU:

• NVIDIA GPU (Linux / Windows WSL2): install the NVIDIA Container Toolkit, then copy the git-ignored sample override and recreate the container.

  cp compose.override.gpu.sample.yml compose.override.yml
  docker compose up -d --force-recreate ollama
  docker compose exec ollama ollama ps   # PROCESSOR should read "100% GPU"

  docker compose auto-merges compose.override.yml; delete it to fall back to CPU.

• macOS: Docker Desktop cannot pass the Apple GPU into Linux containers, so the containerized ollama stays CPU-only. For Metal GPU acceleration, run Ollama natively and point KUKAN at it with OLLAMA_URL=http://localhost:11434 in .env.

4. Environment variables

cp .env.example .env

5. Run database migrations

pnpm db:migrate

6. Start the development server

pnpm dev

Access the application at http://localhost:3000.

7. Register the initial user

Open http://localhost:3000/auth/sign-up and register the first user. While no users exist, self-registration is enabled and the first registered user automatically becomes a sysadmin (system administrator).

You can also create users via the CLI (--role defaults to user when omitted).

pnpm db:create-user --email admin@example.com --name admin --password <password> --role sysadmin