メインコンテンツまでスキップ

環境構築

必要なもの​

開発を始める前に以下をインストールしておいてください。

ツールバージョン用途
Git最新ソースコード管理
Docker & Docker Compose最新API・DBの起動
Node.js22.xWeb・SPNフロントエンド
Python3.11API開発（直接触る場合）

リポジトリのクローン​

git clone --recurse-submodules https://github.com/chibafes-dev/happa.git
cd happa

:::caution サブモジュールを忘れずに --recurse-submodules が必要です。忘れた場合は git submodule update --init --recursive で補完できます。 :::

API（バックエンド）の起動​

1. 環境変数ファイルを作成する​

cd api
cp .env.sample .env

.env を開き、最低限以下を設定してください。ローカルでDockerを使う場合は DATABASE_URL だけ設定すれば動き始めます。

変数ローカル開発での値
DATABASE_URLmysql+aiomysql://happa_user:happa_password@localhost:3306/happa
CORS_ORIGINShttp://localhost:3000,http://localhost:3001
NODE_ENVdevelopment

Auth0・R2・Resendなど外部サービスの設定は、対応する機能を開発する際に追加してください。

2. DockerでAPIとDBを起動する​

# ローカルDB（MySQL）込みで起動
docker compose -f docker-compose.local.yml up -d

起動確認：

curl http://localhost:8000/health
# -> {"status":"ok"} が返ればOK

Swagger UI（APIドキュメント）は http://localhost:8000/docs で確認できます。

Makefile コマンド一覧​

api/ ディレクトリに Makefile があります。

make dev          # ホットリロードで開発サーバー起動
make test         # テスト実行
make lint         # flake8 でコードチェック
make format       # Black でフォーマット
make docker-up    # Dockerコンテナ起動
make docker-down  # コンテナ停止

データベースマイグレーション​

初回起動時と、スキーマが変更されたときに実行します。

# コンテナ内で実行
docker compose exec api alembic upgrade head

# またはMakefileで
make migrate

Web（フロントエンド）の起動​

1. 環境変数ファイルを作成する​

cd web
cp .env.local.example .env.local

最低限設定が必要な変数：

変数ローカル開発での値
FASTAPI_API_URLhttp://localhost:8000/api
NEXT_PUBLIC_PROJECT_PREFIXtarf（開発用プロジェクトのprefix）
NODE_ENVdevelopment

Auth0の設定（AUTH0_*）はログイン機能を使う場合に必要です。

2. 依存関係をインストールして起動する​

npm install
npm run dev

http://localhost:3000 で起動します。

コマンド一覧​

npm run dev           # 開発サーバー起動
npm run build         # Cloudflare Pages向けビルド
npm run lint          # ESLint
npm run typecheck     # TypeScriptの型チェック
npm run generate:api  # OpenAPIスキーマからAPIクライアントを自動生成

:::tip APIクライアントの再生成 バックエンドのAPIが変わったら npm run generate:api を実行して型を更新してください。 :::

SPN（協賛企業管理）の起動​

cd spn
cp .env.sample .env
npm install
npm run dev  # http://localhost:3001 で起動

VS Code Dev Container を使う場合​

.devcontainer/devcontainer.json が設定済みです。VS CodeでRemote Containersを使うとPython 3.11の環境が自動で立ち上がります。

  1. VS Code に「Dev Containers」拡張をインストール
  2. Cmd+Shift+P →「Dev Containers: Reopen in Container」を選択
  3. コンテナ起動後、api/requirements.txt の依存関係が自動インストールされます

全体の起動確認チェックリスト​

  • http://localhost:8000/health → {"status":"ok"}
  • http://localhost:8000/docs → Swagger UI が表示される
  • http://localhost:3000 → Webフロントエンドが表示される
  • http://localhost:3001 → SPNフロントエンドが表示される