Skip to content

SETUP.ja.md

Latest commit

 

History

History
502 lines (347 loc) · 14.4 KB

SETUP.ja.md

File metadata and controls

502 lines (347 loc) · 14.4 KB

Resume Matcher セットアップガイド

English | Español | 简体中文 | 日本語

ようこそ！このガイドでは、ローカル環境で Resume Matcher をセットアップする手順を説明します。開発に参加したい方も、手元でアプリを動かしたい方も、この手順で始められます。

目次

前提条件

開始前に、以下がインストールされていることを確認してください：

ツール 最低バージョン 確認方法 インストール
Python 3.13+ python --version python.org
Node.js 22+ node --version nodejs.org
npm 10+ npm --version Node.js に同梱
uv 最新 uv --version astral.sh/uv
Git 任意 git --version git-scm.com

uv のインストール（Python パッケージマネージャ）

Resume Matcher は Python 依存関係の管理に uv を使用します。インストール方法：

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# または pip
pip install uv

クイックスタート

開発ツールに慣れていて、まず動かしたい方向け：

# 1. リポジトリをクローン
git clone https://github.com/srbhr/Resume-Matcher.git
cd Resume-Matcher

# 2. バックエンド起動（ターミナル 1）
cd apps/backend
cp .env.example .env        # テンプレートから設定を作成
uv sync                      # Python 依存関係をインストール
uv run uvicorn app.main:app --reload --port 8000

# 3. フロントエンド起動（ターミナル 2）
cd apps/frontend
npm install                  # Node.js 依存関係をインストール
npm run dev                  # 開発サーバを起動

ブラウザで http://localhost:3000 を開けば OK です。

注意: 利用前に AI プロバイダの設定が必要です。下の AI プロバイダの設定 を参照してください。

手順どおりにセットアップ

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

まずはコードを取得します：

git clone https://github.com/srbhr/Resume-Matcher.git
cd Resume-Matcher

2. バックエンドのセットアップ

バックエンドは Python（FastAPI）で、AI 処理、履歴書の解析、データ保存を担当します。

バックエンドディレクトリへ移動

cd apps/backend

環境ファイルを作成

cp .env.example .env

.env を好みのエディタで編集

# macOS/Linux
nano .env

# 好みのエディタでも OK
code .env   # VS Code

最重要設定は AI プロバイダです。OpenAI の最小例：

LLM_PROVIDER=openai
LLM_MODEL=gpt-5-nano-2025-08-07
LLM_API_KEY=sk-your-api-key-here

# ローカル開発では既定のままで OK
HOST=0.0.0.0
PORT=8000
FRONTEND_BASE_URL=http://localhost:3000
CORS_ORIGINS=["http://localhost:3000", "http://127.0.0.1:3000"]

Python 依存関係をインストール

uv sync

仮想環境を作成し、必要なパッケージをインストールします。

バックエンドサーバを起動

uv run uvicorn app.main:app --reload --port 8000

次のような出力が表示されます：

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process

このターミナルは起動したまま、フロントエンド用に別ターミナルを開きます。

3. フロントエンドのセットアップ

フロントエンドは Next.js で、UI を提供します。

フロントエンドディレクトリへ移動

cd apps/frontend

（任意）フロントエンドの環境ファイルを作成

バックエンドを別ポートで動かす場合のみ必要です：

cp .env.sample .env.local

Node.js 依存関係をインストール

npm install

開発サーバを起動

npm run dev

次のように表示されます：

▲ Next.js 16.x.x (Turbopack)
- Local:        http://localhost:3000

ブラウザで http://localhost:3000 を開くと、Resume Matcher のダッシュボードが表示されます。

AI プロバイダの設定

Resume Matcher は複数の AI プロバイダに対応しています。アプリ内の Settings ページ、またはバックエンドの .env を編集して設定できます。

オプション A: クラウドプロバイダ

プロバイダ 設定 API キー取得先
OpenAI LLM_PROVIDER=openai
LLM_MODEL=gpt-5-nano-2025-08-07		 platform.openai.com
Anthropic LLM_PROVIDER=anthropic
LLM_MODEL=claude-haiku-4-5-20251001		 console.anthropic.com
Google Gemini LLM_PROVIDER=gemini
LLM_MODEL=gemini-3-flash-preview		 aistudio.google.com
OpenRouter LLM_PROVIDER=openrouter
LLM_MODEL=deepseek/deepseek-chat		 openrouter.ai
DeepSeek LLM_PROVIDER=deepseek
LLM_MODEL=deepseek-chat		 platform.deepseek.com

Anthropic の .env 例：

LLM_PROVIDER=anthropic
LLM_MODEL=claude-haiku-4-5-20251001
LLM_API_KEY=sk-ant-your-key-here

オプション B: Ollama によるローカル AI（無料）

API コストなしでローカル実行したい場合は Ollama を使えます。

ステップ 1: Ollama をインストール

ollama.com からダウンロードしてインストールします。

ステップ 2: モデルを取得

ollama pull gemma3:4b

他の候補：mistral、codellama、neural-chat

ステップ 3: .env を設定

LLM_PROVIDER=ollama
LLM_MODEL=gemma3:4b
LLM_API_BASE=http://localhost:11434
# Ollama では LLM_API_KEY は不要です

ステップ 4: Ollama が起動していることを確認

ollama serve

通常はインストール後に自動起動します。

Docker デプロイ

コンテナで動かしたい場合、Resume Matcher は Docker に対応しています。

Docker Compose を使う（推奨）

# コンテナをビルドして起動
docker-compose up -d

# ログを見る
docker-compose logs -f

# コンテナ停止
docker-compose down

Docker の注意点

  • API キーは UI から設定：http://localhost:3000/settings（.env ではありません）
  • データは Docker volume に永続化されます
  • フロントエンド（3000）とバックエンド（8000）のポートが公開されます

アプリへのアクセス

両方のサーバが起動したら、ブラウザで以下にアクセスします：

URL 内容
http://localhost:3000 メインアプリ（Dashboard）
http://localhost:3000/settings AI プロバイダ設定
http://localhost:8000 バックエンド API ルート
http://localhost:8000/docs 対話型 API ドキュメント
http://localhost:8000/health バックエンドヘルスチェック

初回セットアップチェックリスト

  1. http://localhost:3000/settings を開く
  2. AI プロバイダを選択
  3. API キーを入力（または Ollama を設定）
  4. "Save Configuration" をクリック
  5. "Test Connection" をクリックして確認
  6. Dashboard に戻り、最初の履歴書をアップロード

よく使うコマンド

バックエンド

cd apps/backend

# 開発サーバ（自動リロード）
uv run uvicorn app.main:app --reload --port 8000

# 本番サーバ
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000

# 依存関係のインストール
uv sync

# 開発用依存関係も含める（テスト用）
uv sync --group dev

# テスト実行
uv run pytest

# DB の状態確認（JSON ファイル）
ls -la data/

フロントエンド

cd apps/frontend

# 開発サーバ（Turbopack）
npm run dev

# 本番ビルド
npm run build

# 本番起動
npm run start

# Lint
npm run lint

# Prettier で整形
npm run format

# 別ポートで起動
npm run dev -- -p 3001

データベース管理

Resume Matcher は TinyDB（JSON ファイル保存）を使用します。データは apps/backend/data/ にあります：

# DB ファイルを見る
ls apps/backend/data/

# バックアップ
cp -r apps/backend/data apps/backend/data-backup

# 全リセット（初期化）
rm -rf apps/backend/data

トラブルシューティング

バックエンドが起動しない

Error: ModuleNotFoundError

uv で起動していることを確認してください：

uv run uvicorn app.main:app --reload

Error: LLM_API_KEY not configured

.env に選択したプロバイダ用の API キーが設定されているか確認してください。

フロントエンドが起動しない

Error: ページ読み込み時に ECONNREFUSED

バックエンドが起動していません。先に起動してください：

cd apps/backend && uv run uvicorn app.main:app --reload

Error: build または TypeScript エラー

Next.js のキャッシュを削除します：

rm -rf apps/frontend/.next
npm run dev

PDF のダウンロードに失敗する

Error: Cannot connect to frontend for PDF generation

バックエンドからフロントエンドへ接続できません。以下を確認してください：

  1. フロントエンドが起動している
  2. .env の FRONTEND_BASE_URL がフロントエンド URL と一致している
  3. CORS_ORIGINS にフロントエンド URL が含まれている

フロントエンドが 3001 の場合：

FRONTEND_BASE_URL=http://localhost:3001
CORS_ORIGINS=["http://localhost:3001", "http://127.0.0.1:3001"]

Ollama の接続に失敗する

Error: Connection refused to localhost:11434

  1. Ollama の稼働確認：ollama list
  2. 必要なら起動：ollama serve
  3. モデルが取得済みか確認：ollama pull gemma3:4b

プロジェクト構成

Resume-Matcher/
├─ apps/
│  ├─ backend/                 # Python FastAPI backend
│  │  ├─ app/
│  │  │  ├─ main.py            # Application entry point
│  │  │  ├─ config.py          # Environment configuration
│  │  │  ├─ database.py        # TinyDB wrapper
│  │  │  ├─ llm.py             # AI provider integration
│  │  │  ├─ routers/           # API endpoints
│  │  │  ├─ services/          # Business logic
│  │  │  └─ schemas/           # Data models
│  │  ├─ prompts/              # LLM prompt templates
│  │  ├─ data/                 # Database storage (auto-created)
│  │  ├─ .env.example          # Environment template
│  │  └─ pyproject.toml        # Python dependencies
│  └─ frontend/                # Next.js React frontend
│     ├─ app/                  # Pages (dashboard, builder, etc.)
│     ├─ components/           # Reusable React components
│     ├─ lib/                  # Utilities and API client
│     ├─ .env.sample           # Environment template
│     └─ package.json          # Node.js dependencies
├─ docs/                        # Additional documentation
├─ docker-compose.yml           # Docker configuration
├─ Dockerfile                   # Container build instructions
└─ README.md                    # Project overview

ヘルプ

困ったときは次を参照してください：

参考ドキュメント

ドキュメント 内容
backend-guide.md バックエンドのアーキテクチャと API 詳細
frontend-workflow.md ユーザーフローとコンポーネント構成
style-guide.md UI デザインシステム（Swiss International Style）

楽しい履歴書づくりを！Resume Matcher が役立ったら、リポジトリに Star と Discord 参加 をぜひ。