開発環境

環境について

https://coder.akarinext.org/ で開発を行う。

Desktop 版クライアントは学内 LAN（Wi-Fi は可）では接続できないため、その場合は code-server（ブラウザ版）を使用すること。

ディレクトリ構成

/
├── apps/
│   ├── api/        # Rust バックエンド (Axum)
│   └── web/        # フロントエンド (TanStack Start)
├── docs/           # 仕様書・ドキュメント
└── infrastructure/ # インフラ設定

前提条件

Coder 環境には以下がプリインストールされている。

ツール	用途
Rust (rustup)	バックエンドのビルド
cargo	Rust パッケージマネージャ
Node.js	フロントエンドのビルド
pnpm	フロントエンドのパッケージマネージャ
PostgreSQL	DB（ソケット経由でローカル接続）
Valkey	セッション管理（Redis 互換）

S3互換ストレージ（MinIO / RustFS 等）・Qdrant は別途起動が必要（後述）。S3なしの場合はローカルストレージが自動使用される。

初回セットアップ

1. バックエンドの環境変数を設定

cp apps/api/.env.example apps/api/.env

.env.example からコピーした後、必要に応じて値を編集する。
Coder 環境でのデフォルト値は以下の通り。

DATABASE_URL=postgres://coder@localhost/coder?host=/var/run/postgresql
REDIS_URL=redis://localhost:6379

LOCAL_STORAGE_PATH=./data/uploads
LOCAL_BASE_URL=http://localhost:3400
LOCAL_SIGNED_URL_SECRET=local-dev-secret-change-this-in-production

S3互換ストレージ（MinIO / RustFS 等）を使う場合は代わりに以下を設定する。

S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
S3_BUCKET=hyperdrive
S3_FORCE_PATH_STYLE=true

2. フロントエンドの環境変数を設定

cp apps/web/.env.example apps/web/.env.local

.env.local に開発用の API エンドポイントを追加する。

SERVER_URL=http://localhost:8080
API_BASE_URL=http://localhost:8080

VITE_API_BASE_URL は本番のみ設定する（開発時は Vite proxy が /v1 を転送するため不要）。

3. フロントエンドの依存関係をインストール

cd apps/web
sudo corepack enable pnpm  # 初回のみ
pnpm install

4. DBマイグレーションを実行

cd apps/api
cargo run -p migration -- up

マイグレーションの状態確認や巻き戻しは以下のコマンドを使用する。

cargo run -p migration -- status   # 適用済みマイグレーションの一覧
cargo run -p migration -- down     # 最新1件を巻き戻す
cargo run -p migration -- fresh    # 全件リセット後に全件適用（データ消去）

5. OpenAPI スキーマを生成

フロントエンドの型定義を生成する。バックエンドのサーバー起動は不要。

cd apps/web
pnpm generate:api

起動手順（日常的な開発）

バックエンドとフロントエンドを別ターミナルで起動する。

バックエンド

cd apps/api
cargo run

起動後、http://localhost:8080 でアクセスできる。
API ドキュメント（Scalar UI）は http://localhost:8080/scalar で確認できる。

注意: Rust はホットリロード非対応。コードを変更したら Ctrl+C で停止し、再度 cargo run を実行すること。
ホットリロードが必要な場合は cargo-watch を使用する（cargo watch -x run）。

フロントエンド

cd apps/web
pnpm dev

起動後、http://localhost:3400 でアクセスできる。
ファイルを保存すると自動でリロードされる。

API の型定義を再生成する

バックエンドのエンドポイントや型を変更したときに実行する。

cd apps/web
pnpm generate:api

生成される src/api/schema.d.ts は .gitignore に登録されており、コミットしない。
詳細は OpenAPIクライアントを参照。

ポート一覧

サービス	URL
フロントエンド	http://localhost:3400
バックエンド API	http://localhost:8080
API ドキュメント (Scalar)	http://localhost:8080/scalar
PostgreSQL	localhost:5432
Valkey	localhost:6379
S3互換ストレージ（MinIO等）	http://localhost:9000
Qdrant	http://localhost:6333

トラブルシューティング

`pnpm dev` が起動しない

依存関係が古いか未インストールの可能性が高い。

cd apps/web
pnpm install

`cargo run` でコンパイルエラーが出る

Rust のツールチェーンが古い場合は更新する。

rustup update

DB 接続エラー

PostgreSQL が起動しているか確認する。

pg_isready

マイグレーションが未適用の場合は実行する。

cd apps/api
cargo run -p migration -- up

`generate:api` でエラーが出る

Rust のビルドキャッシュが壊れている可能性がある。

cd apps/api
cargo clean
cd ../web
pnpm generate:api