ローカルクイックスタート

このガイドはローカル開発を目的としています。本番環境へのデプロイについては、 Kodusのデプロイガイドを参照してください。

前提条件

Node.js（LTSバージョン）
Docker
YarnまたはNPM
LLM APIキー

プロジェクトの実行

自動セットアップ（推奨）
手動セットアップ

クイックかつ自動化されたセットアップには、セットアップスクリプトを使用してください：

git clone https://github.com/kodustech/kodus-ai.git
cd kodus-ai
yarn setup

このスクリプトは自動的に以下を行います：

✅ 必要な依存関係（Node.js、Yarn、Docker、OpenSSL）をすべて確認
✅ プロジェクトの依存関係をインストール
✅ .envファイルを作成・設定
✅ 必要なセキュリティキーをすべて自動生成
✅ Dockerネットワークをセットアップ
✅ 次のステップを明確に提示

LLMモードの選択（必須）

モードを1つ選択し、サービスを開始する前に.envに入力してください。

Fixed Mode (Recommended for Self-Hosted)
Automatic Mode (High Quality)

This is the simplest mode and recommended for self-hosted installations. You only need to configure a single LLM model.

# Fixed Mode Configuration
API_LLM_PROVIDER_MODEL="gpt-3.5-turbo"     # Model you want to use
API_OPENAI_FORCE_BASE_URL="https://your-api.com/v1"  # Your API provider URL
API_OPEN_AI_API_KEY="your-api-key"          # Your API provider key

This mode is ideal for self-hosted because:

Requires only a single API key
Works with any OpenAI-compatible API provider
Easier to configure and maintain

Model Configuration Guides

Check our model-specific guides for detailed setup instructions with popular providers like Novita, OpenAI, Anthropic, and more.

This mode uses multiple LLM models to achieve the best possible results. Requires more configuration but offers the highest quality analysis.

# Automatic Mode Configuration
API_OPEN_AI_API_KEY=                       # OpenAI API key
API_GOOGLE_AI_API_KEY=                     # Google AI API key
API_ANTHROPIC_API_KEY=                     # Anthropic API key
API_NOVITA_AI_API_KEY=                     # Novita AI API key
API_VERTEX_AI_API_KEY=                     # Vertex AI API key

This mode offers the best quality because:

Uses multiple specialized models
Our pipeline is optimized to extract the best from each model
Ideal for enterprise installations prioritizing quality

次のステップ

基本セットアップ：

yarn docker:start
yarn migrate:dev
yarn seed

外部インテグレーション（Webhooksなど）を使用する場合：

yarn docker:start
yarn migrate:dev
yarn seed
yarn tunnel  # 外部サービス用のパブリックエンドポイントを作成

すべてが起動したら、ブラウザで http://localhost:3000 を開いてください。

すべてを手動で設定する場合：

1. リポジトリのクローン

git clone https://github.com/kodustech/kodus-ai.git

2. 依存関係のインストール

yarn install

3. 環境変数の設定

cp .env.example .env

4. LLMモードの選択（必須）

サービスを開始する前に、モードを1つ選択して.envに入力してください。

Fixed Mode (Recommended for Self-Hosted)
Automatic Mode (High Quality)

This is the simplest mode and recommended for self-hosted installations. You only need to configure a single LLM model.

# Fixed Mode Configuration
API_LLM_PROVIDER_MODEL="gpt-3.5-turbo"     # Model you want to use
API_OPENAI_FORCE_BASE_URL="https://your-api.com/v1"  # Your API provider URL
API_OPEN_AI_API_KEY="your-api-key"          # Your API provider key

This mode is ideal for self-hosted because:

Requires only a single API key
Works with any OpenAI-compatible API provider
Easier to configure and maintain

Model Configuration Guides

Check our model-specific guides for detailed setup instructions with popular providers like Novita, OpenAI, Anthropic, and more.

This mode uses multiple LLM models to achieve the best possible results. Requires more configuration but offers the highest quality analysis.

# Automatic Mode Configuration
API_OPEN_AI_API_KEY=                       # OpenAI API key
API_GOOGLE_AI_API_KEY=                     # Google AI API key
API_ANTHROPIC_API_KEY=                     # Anthropic API key
API_NOVITA_AI_API_KEY=                     # Novita AI API key
API_VERTEX_AI_API_KEY=                     # Vertex AI API key

This mode offers the best quality because:

Uses multiple specialized models
Our pipeline is optimized to extract the best from each model
Ideal for enterprise installations prioritizing quality

5. セキュリティキーの生成

環境変数を設定する前に、JWTトークンとその他のセキュリティ関連の設定のためにセキュアなキーを生成する必要があります：

# ほとんどのセキュリティキー（JWTシークレットなど）
openssl rand -base64 32

# 暗号化キーとコード管理シークレット
openssl rand -hex 32

# Webhookトークン（URLセーフ）
openssl rand -base64 32 | tr -d '=' | tr '/+' '_-'

以下のセキュリティキーの値を生成する必要があります：

JWT_SECRET（openssl rand -base64 32を使用）
JWT_REFRESH_SECRET（openssl rand -base64 32を使用）
CODE_MANAGEMENT_SECRET（openssl rand -hex 32を使用）
CODE_MANAGEMENT_WEBHOOK_TOKEN（openssl rand -base64 32 | tr -d '=' | tr '/+' '_-'を使用）

6. Dockerネットワークのセットアップ

必要なDockerネットワークを作成します：

docker network create kodus-backend-services || true
docker network create shared-network || true

7. 開発環境の起動

Dockerを使用してサービスを起動します：

yarn docker:start

このコマンドは以下を起動します：

Kodus API
Worker（非同期ジョブ）
Webhooksサービス
Kodus Webアプリケーション
PostgreSQLデータベース
MongoDBデータベース
RabbitMQ
必要なネットワーク設定

外部サービス用のパブリックエンドポイントも作成する場合：

yarn tunnel

8. 初回セットアップ

プロジェクトを初めて実行する場合は、以下のコマンドを実行してください：データベースマイグレーションの実行：

yarn migrate:dev

初期データのシード：

yarn seed

9. サービスエンドポイント

以下のURLでサービスにアクセスできます：

Web UI: http://localhost:3000
API: http://localhost:3001
RabbitMQ管理コンソール: http://localhost:15672
デバッグポート: 9229

開発ワークフロー

基本的なローカル開発

サービスの起動: yarn docker:start
マイグレーションの実行: yarn migrate:dev
シードデータの読み込み: yarn seed
アプリを開く: http://localhost:3000にアクセス
ヘルスチェック: yarn dev:health-check

外部インテグレーションを使用した開発

外部サービス（GitのWebhookなど）とのインテグレーションをテストする必要がある場合：

サービスの起動: yarn docker:start && yarn migrate:dev && yarn seed
トンネルの作成: yarn tunnel（パブリックエンドポイントを作成）
Webhook URLの更新: トンネルコマンドが.envを自動的に更新します
Gitプロバイダーの設定: Gitプロバイダーの設定でトンネルURLを使用
インテグレーションのテスト: WebhookをトリガーしてログをモニタリングJP

トンネルのメリット：

本物のWebhookインテグレーションをローカルでテスト
外部サービス通信のデバッグ
チームメンバーとの開発環境の共有
モバイルアプリやその他の外部クライアントのテスト

トラブルシューティング

クイックヘルスチェック

yarn dev:health-check

この包括的なヘルスチェックは以下を検証します：

✅ サービス: Kodus API、Worker、Webhooks、Web、PostgreSQL、MongoDB、RabbitMQ
🔌 ポートの可用性: Web（3000）、API（3001）、PostgreSQL（5432）、MongoDB（27017）、RabbitMQ（5672/15672）
🗄️ データベースセットアップ: マイグレーションとシードデータ
🌐 APIエンドポイント: ヘルスエンドポイントと基本的な接続性

手動での確認

Web UIの確認: ブラウザでhttp://localhost:3000にアクセス
APIヘルスの確認: http://localhost:3001/healthにアクセス
RabbitMQの確認: http://localhost:15672にアクセス（デフォルト認証情報: guest/guest）
データベース接続の確認: ログでデータベース接続の成功を確認
Webhookエンドポイントのテスト: Gitプロバイダーの設定でhttp://localhost:3332/[provider]/webhookを指定（またはリバースプロキシが/.../webhookをWebhooksサービスにルーティングする場合はAPIドメインを使用）

セットアップスクリプトの問題

自動セットアップスクリプト（yarn setup）が失敗した場合： 依存関係が見つからない場合：

# 必要なツールがすべてインストールされているか確認
node --version
yarn --version
docker --version
openssl version

Dockerのパーミッション問題：

# ユーザーをdockerグループに追加（Linux/macOS）
sudo usermod -aG docker $USER
# その後、ログアウトして再度ログイン

ネットワーク作成エラー：

# ネットワークが既に存在するか確認
docker network ls | grep kodus
# 必要に応じて競合するネットワークを削除
docker network rm kodus-backend-services shared-network

よくある問題

ポートの競合：

ポート3000（Web）、3001（API）、5432（PostgreSQL）、27017（MongoDB）、5672/15672（RabbitMQ）が使用可能であることを確認
Kodusを起動する前にこれらのポートを使用している他のサービスを停止

環境変数が読み込まれない：

プロジェクトルートに.envファイルが存在することを確認
変数の代入にトレーリングスペースがないことを確認
必要なセキュリティキーがすべて正しく生成されたことを確認

ヘルスチェックの失敗：

yarn dev:health-checkを実行して詳細な診断を確認
コンテナが完全に起動しているか確認（yarn docker:start後、1〜2分待機）
データベースマイグレーションとシードデータが読み込まれていることを確認
yarn docker:logsでAPIのログを確認して起動エラーを確認

APIが応答しない：

APIはコンテナ起動後に完全に初期化されるまでに時間がかかります
マイグレーションとシードデータが読み込まれているか確認
.envファイルに必要な変数がすべて含まれていることを確認
ヘルスチェックを実行して、どの特定のコンポーネントが失敗しているかを確認

外部サービスとのWebhookの問題：

yarn tunnelを使用して外部Webhook用のパブリックエンドポイントを作成
GitプロバイダーのWebhook URLをトンネルURLに更新
Webhookインテグレーションのテスト中はトンネルNが稼働していることを確認
トンネルのログで接続の問題を確認

概念

ローカルクイックスタート

Dockerでデプロイ

Gitプロバイダーの設定

ローカルクイックスタート

前提条件

プロジェクトの実行

LLMモードの選択（必須）

Model Configuration Guides

次のステップ

1. リポジトリのクローン

2. 依存関係のインストール

3. 環境変数の設定

4. LLMモードの選択（必須）

Model Configuration Guides

5. セキュリティキーの生成

6. Dockerネットワークのセットアップ

7. 開発環境の起動

8. 初回セットアップ

9. サービスエンドポイント

開発ワークフロー

基本的なローカル開発

外部インテグレーションを使用した開発

トラブルシューティング

クイックヘルスチェック

手動での確認

セットアップスクリプトの問題

よくある問題

概念

ローカルクイックスタート

Dockerでデプロイ

Gitプロバイダーの設定

​前提条件

​プロジェクトの実行

​LLMモードの選択（必須）

Model Configuration Guides

​次のステップ

​1. リポジトリのクローン

​2. 依存関係のインストール

​3. 環境変数の設定

​4. LLMモードの選択（必須）

Model Configuration Guides

​5. セキュリティキーの生成

​6. Dockerネットワークのセットアップ

​7. 開発環境の起動

​8. 初回セットアップ

​9. サービスエンドポイント

​開発ワークフロー

​基本的なローカル開発

​外部インテグレーションを使用した開発

​トラブルシューティング

​クイックヘルスチェック

​手動での確認

​セットアップスクリプトの問題

​よくある問題

前提条件

プロジェクトの実行

LLMモードの選択（必須）

次のステップ

1. リポジトリのクローン

2. 依存関係のインストール

3. 環境変数の設定

4. LLMモードの選択（必須）

5. セキュリティキーの生成

6. Dockerネットワークのセットアップ

7. 開発環境の起動

8. 初回セットアップ

9. サービスエンドポイント

開発ワークフロー

基本的なローカル開発

外部インテグレーションを使用した開発

トラブルシューティング

クイックヘルスチェック

手動での確認

セットアップスクリプトの問題

よくある問題