Quick Start

Prerequisites

Node.js 24 LTS
pnpm 10+
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. Environment variables

cp .env.example .env
# Generate the auth secret
sed -i.bak "s|^BETTER_AUTH_SECRET=.*|BETTER_AUTH_SECRET=$(openssl rand -base64 32)|" .env && rm .env.bak

BETTER_AUTH_SECRET (the auth secret, 32 characters or more) must be set; Docker Compose refuses to start without it.

4. Start infrastructure

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

docker compose up -d

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.

5. Run database migrations

pnpm --filter @kukan/db 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 --role sysadmin

The command prompts for the password. It needs at least 15 characters and must be hard to guess (e.g. harbor-lantern-quiet-42).