SETUP.ja.md
English | Español | 简体中文 | 日本語
ようこそ！このガイドでは、ローカル環境で Resume Matcher をセットアップする手順を説明します。開発に参加したい方も、手元でアプリを動かしたい方も、この手順で始められます。
<a id="prerequisites"></a>
開始前に、以下がインストールされていることを確認してください：
| ツール | 最低バージョン | 確認方法 | インストール |
|---|---|---|---|
| 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 |
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
<a id="quick-start"></a>
開発ツールに慣れていて、まず動かしたい方向け：
# 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 プロバイダの設定 を参照してください。
<a id="step-by-step-setup"></a>
<a id="1-clone-the-repository"></a>
まずはコードを取得します：
git clone https://github.com/srbhr/Resume-Matcher.git
cd Resume-Matcher
<a id="2-backend-setup"></a>
バックエンドは 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"]
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
このターミナルは起動したまま、フロントエンド用に別ターミナルを開きます。
<a id="3-frontend-setup"></a>
フロントエンドは Next.js で、UI を提供します。
cd apps/frontend
バックエンドを別ポートで動かす場合のみ必要です：
cp .env.sample .env.local
npm install
npm run dev
次のように表示されます：
▲ Next.js 16.x.x (Turbopack)
- Local: http://localhost:3000
ブラウザで http://localhost:3000 を開くと、Resume Matcher のダッシュボードが表示されます。
<a id="configuring-your-ai-provider"></a>
Resume Matcher は複数の AI プロバイダに対応しています。アプリ内の Settings ページ、またはバックエンドの .env を編集して設定できます。
<a id="option-a-cloud-providers"></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
<a id="option-b-local-ai-with-ollama-free"></a>
API コストなしでローカル実行したい場合は Ollama を使えます。
ollama.com からダウンロードしてインストールします。
ollama pull gemma3:4b
他の候補：mistral、codellama、neural-chat
.env を設定LLM_PROVIDER=ollama
LLM_MODEL=gemma3:4b
LLM_API_BASE=http://localhost:11434
# Ollama では LLM_API_KEY は不要です
ollama serve
通常はインストール後に自動起動します。
<a id="docker-deployment"></a>
コンテナで動かしたい場合、Resume Matcher は Docker に対応しています。
# コンテナをビルドして起動
docker-compose up -d
# ログを見る
docker-compose logs -f
# コンテナ停止
docker-compose down
.env ではありません）<a id="accessing-the-application"></a>
両方のサーバが起動したら、ブラウザで以下にアクセスします：
| URL | 内容 |
|---|---|
| http://localhost:3000 | メインアプリ（Dashboard） |
| http://localhost:3000/settings | AI プロバイダ設定 |
| http://localhost:8000 | バックエンド API ルート |
| http://localhost:8000/docs | 対話型 API ドキュメント |
| http://localhost:8000/health | バックエンドヘルスチェック |
<a id="common-commands-reference"></a>
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
<a id="troubleshooting"></a>
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
Error: Cannot connect to frontend for PDF generation
バックエンドからフロントエンドへ接続できません。以下を確認してください：
.env の FRONTEND_BASE_URL がフロントエンド URL と一致しているCORS_ORIGINS にフロントエンド URL が含まれているフロントエンドが 3001 の場合：
FRONTEND_BASE_URL=http://localhost:3001
CORS_ORIGINS=["http://localhost:3001", "http://127.0.0.1:3001"]
Error: Connection refused to localhost:11434
ollama listollama serveollama pull gemma3:4b<a id="project-structure-overview"></a>
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
<a id="getting-help"></a>
困ったときは次を参照してください：
| ドキュメント | 内容 |
|---|---|
| backend-guide.md | バックエンドのアーキテクチャと API 詳細 |
| frontend-workflow.md | ユーザーフローとコンポーネント構成 |
| style-guide.md | UI デザインシステム（Swiss International Style） |
楽しい履歴書づくりを！Resume Matcher が役立ったら、リポジトリに Star と Discord 参加 をぜひ。