クイックスタート

必要環境

git clone https://github.com/kukan-project/kukan.git
cd kukan
git checkout vX.Y.Z   # 最新リリースを指定（開発版を試す場合は省略して main のまま）

リリース一覧は GitHub Releases を参照してください。

pnpm install

cp .env.example .env
# 認証用の秘密鍵を生成
sed -i.bak "s|^BETTER_AUTH_SECRET=.*|BETTER_AUTH_SECRET=$(openssl rand -base64 32)|" .env && rm .env.bak

BETTER_AUTH_SECRET（認証用の秘密鍵、32 文字以上）は必ず設定します。未設定のままでは Docker Compose が起動しません。

PostgreSQL、MinIO、OpenSearch、OpenSearch Dashboards、Ollama を Docker Compose で起動します。

docker compose up -d

同梱の ollama サービス（ベクトル検索・AI メタデータ提案に使用）は既定で CPU 実行です。GPU を使う場合:

NVIDIA GPU（Linux / Windows WSL2）: NVIDIA Container Toolkit を導入し、git-ignore されたサンプル override をコピーしてコンテナを再作成します。
ターミナルウィンドウ
```
cp compose.override.gpu.sample.yml compose.override.yml
docker compose up -d --force-recreate ollama
docker compose exec ollama ollama ps   # PROCESSOR が "100% GPU" になる
```
docker compose は compose.override.yml を自動マージします。削除すれば CPU に戻ります。
macOS: Docker Desktop は Apple GPU をコンテナに渡せないため、コンテナ内 ollama は CPU のみです。Metal で高速化するには Ollama をネイティブ実行し、.env の OLLAMA_URL=http://localhost:11434 でネイティブ側を参照します。

pnpm --filter @kukan/db db:migrate

pnpm dev

http://localhost:3000 でアクセスできます。

http://localhost:3000/auth/sign-up を開いて最初のユーザーを登録します。ユーザーが1人も存在しない間は自己登録が有効で、最初に登録したユーザーは自動的に sysadmin（システム管理者）になります。

CLI で作成することもできます（--role 省略時はデフォルトで user）。

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

パスワードは実行時に入力を求められます。15 文字以上で、推測されにくいものが必要です（例: harbor-lantern-quiet-42）。