Skip to content

docs(quickstart): ドキュメントを簡潔化して分かりやすく改善 #139

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
susumutomita merged 1 commit into from
Dec 30, 2025
Merged

docs(quickstart): ドキュメントを簡潔化して分かりやすく改善 #139

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
270 changes: 73 additions & 197 deletions docs/QUICKSTART.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,190 +4,105 @@ TenkaCloud をローカル環境で起動するクイックスタートガイド

## 前提条件

- **Docker Desktop** がインストールされていること
- **Bun** (または Node.js) がインストールされていること
- **Git** がインストールされていること
- **Terraform** がインストールされていること（Auth0 セットアップ用）
以下がインストールされている必要があります。

## 🚀 クイックスタート（5分で起動）
| ツール | 用途 | インストール |
|--------|------|--------------|
| Docker Desktop | コンテナ実行 | [公式サイト](https://www.docker.com/products/docker-desktop/) |
| Bun | パッケージ管理・ランタイム | `brew install oven-sh/bun/bun` |
| AWS CLI | LocalStack 操作 | `brew install awscli` |
| Terraform | インフラ構築 | `brew install terraform` |

### ステップ 1: リポジトリのクローン
## 🚀 クイックスタート（3 ステップで起動）

### 1. クローンと依存関係インストール

```bash
git clone --recurse-submodules https://github.com/susumutomita/TenkaCloud.git
cd TenkaCloud
```

### ステップ 2: 依存関係のインストール

```bash
# ni は lock ファイルから自動でパッケージマネージャを選択
ni
# または
bun install
```

### ステップ 3: 認証の設定

TenkaCloud は認証に Auth0 を使用します。開発目的であれば、認証スキップモードを使用して Auth0 のセットアップをスキップできます。

#### オプション A: 認証スキップモード（開発用・推奨）

Auth0 のセットアップをせずにすぐに開発を開始したい場合は、認証スキップモードを使用できます。
### 2. 環境変数を設定

**Control Plane (`apps/control-plane/.env.local`)**:
以下のファイルを作成するだけで、Auth0 なしですぐに開発できます。

```env
```bash
# Control Plane
cat > apps/control-plane/.env.local << 'EOF'
AUTH_SKIP=1
AUTH_SECRET=dev-secret-for-local-development
AUTH_URL=http://localhost:3000
```
EOF

**Application Plane (`apps/application-plane/.env.local`)**:

```env
# Application Plane
cat > apps/application-plane/.env.local << 'EOF'
AUTH_SKIP=1
AUTH_SECRET=dev-secret-for-local-development
AUTH_URL=http://localhost:3001
EOF
```

認証スキップモードでは、自動的に以下のモックユーザーでログイン状態になります。

- **Control Plane**: Dev User (dev@example.com) / admin ロール
- **Application Plane**: Dev User (dev@example.com) / participant ロール

このモードは開発専用です。本番環境では必ず Auth0 を設定してください。

認証スキップモードを使用する場合は、**ステップ 4** に進んでください。

#### オプション B: Auth0 のセットアップ（本番同等環境）

TenkaCloud は認証に Auth0 を使用します。以下の手順で Auth0 を設定してください。

##### B.1 Auth0 Management API 認証情報の取得

1. [Auth0 Dashboard](https://manage.auth0.com) にログイン
2. 左サイドバーから **Applications** → **APIs** を選択
3. **Auth0 Management API** をクリック
4. **Machine to Machine Applications** タブを開く
5. **Create & Authorize** をクリックして新しい M2M アプリを作成
6. 以下の権限（Permissions）を付与:
- `read:clients`
- `create:clients`
- `update:clients`
- `delete:clients`
- `read:resource_servers`
- `create:resource_servers`
- `update:resource_servers`
- `read:client_credentials`
- `create:client_credentials`
7. **Authorize** をクリック
8. 作成したアプリの **Settings** タブから以下を取得:
- **Domain** (例: `your-tenant.auth0.com`)
- **Client ID**
- **Client Secret**

##### B.2 Terraform 変数ファイルの作成

```bash
# terraform.tfvars を作成
cp infrastructure/terraform/environments/dev/terraform.tfvars.example \
infrastructure/terraform/environments/dev/terraform.tfvars
```

`infrastructure/terraform/environments/dev/terraform.tfvars` を編集して、取得した認証情報を設定してください。

```hcl
auth0_domain = "your-tenant.auth0.com"
auth0_client_id = "取得した Client ID"
auth0_client_secret = "取得した Client Secret"
```

`terraform.tfvars` はシークレット情報を含むため、Git にコミットしないでください（`.gitignore` で除外済み）。
`AUTH_SKIP=1` で認証スキップモードが有効になり、モックユーザーで自動ログインします。

##### B.3 Auth0 リソースのプロビジョニング
### 3. 起動

```bash
# Auth0 をセットアップ（init + apply + 認証情報表示）
make auth0-setup
# Docker Desktop を起動してから実行
make start
```

このコマンドにより、Control Plane 用 Auth0 Application、Application Plane 用 Auth0 Application、TenkaCloud API (Resource Server) が作成されます。
起動後、以下の URL にアクセスできます。

##### B.4 環境変数の設定
- **Control Plane**: http://localhost:3000
- **Application Plane**: http://localhost:3001
- **LocalStack**: http://localhost:4566
Comment on lines +57 to +59

@coderabbitai coderabbitai Bot Dec 30, 2025

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Wrap bare URLs in Markdown link syntax to comply with MD034.

Bare URLs should be formatted as links for proper Markdown rendering and accessibility.

🔎 Proposed fix for bare URLs 
- **Control Plane**: http://localhost:3000
+ **Control Plane**: [http://localhost:3000](http://localhost:3000)
- **Application Plane**: http://localhost:3001
+ **Application Plane**: [http://localhost:3001](http://localhost:3001)
- **LocalStack**: http://localhost:4566
+ **LocalStack**: [http://localhost:4566](http://localhost:4566)
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

57-57: Bare URL used

(MD034, no-bare-urls)

58-58: Bare URL used

(MD034, no-bare-urls)

59-59: Bare URL used

(MD034, no-bare-urls)

🤖 Prompt for AI Agents 
In docs/QUICKSTART.md around lines 57 to 59 the three bare URLs are flagged by
MD034; replace each bare URL with Markdown link syntax (e.g. [Control
Plane](http://localhost:3000), [Application Plane](http://localhost:3001),
[LocalStack](http://localhost:4566)) so they are proper links and accessible,
preserving the same labels and URLs.


`make auth0-setup` の実行後に表示される認証情報を、各アプリの `.env.local` にコピーします。
## 📦 主な Makefile コマンド

**Control Plane (`apps/control-plane/.env.local`)**:
| コマンド | 説明 |
|----------|------|
| `make start` | LocalStack + フロントエンドを起動 |
| `make stop` | LocalStack を停止 |
| `make restart` | 再起動 |
| `make status` | サービス状態を表示 |
| `make dev` | Control Plane のみ起動（フロントエンド開発用） |
| `make test` | テスト実行（カバレッジ付き） |
| `make before-commit` | コミット前チェック（lint, format, typecheck, test, build） |
| `make help` | すべてのコマンドを表示 |

```env
# NextAuth.js Configuration
AUTH_SECRET=<openssl rand -base64 32 で生成>
AUTH_URL=http://localhost:3000
## 🔐 Auth0 セットアップ（本番同等環境を構築する場合）

# Auth0 Configuration
AUTH0_CLIENT_ID=<表示された control_plane_client_id>
AUTH0_CLIENT_SECRET=<表示された control_plane_client_secret>
AUTH0_ISSUER=https://your-tenant.auth0.com
```
開発時は認証スキップモードで十分ですが、本番同等の環境を構築したい場合は Auth0 を設定します。

**Application Plane (`apps/application-plane/.env.local`)**:
<details>
<summary>詳細手順を表示</summary>

```env
# NextAuth.js Configuration
AUTH_SECRET=<openssl rand -base64 32 で生成>
AUTH_URL=http://localhost:3001
### Auth0 Management API 認証情報の取得

# Auth0 Configuration
AUTH0_CLIENT_ID=<表示された application_plane_client_id>
AUTH0_CLIENT_SECRET=<表示された application_plane_client_secret>
AUTH0_ISSUER=https://your-tenant.auth0.com
```
1. [Auth0 Dashboard](https://manage.auth0.com) にログイン
2. **Applications** → **APIs** → **Auth0 Management API** を選択
3. **Machine to Machine Applications** タブで新しい M2M アプリを作成
4. 以下の権限を付与して **Authorize**:
- `read:clients`, `create:clients`, `update:clients`, `delete:clients`
- `read:resource_servers`, `create:resource_servers`, `update:resource_servers`
Comment on lines +87 to +88

@coderabbitai coderabbitai Bot Dec 30, 2025

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix double comma typographical errors (LanguageTool violations).

Static analysis detected double consecutive commas on lines 87–88. These appear to be formatting issues in the permission lists.

🔎 Proposed fix for double commas 
   - `read:clients`, `create:clients`, `update:clients`, `delete:clients`
-  - `read:resource_servers`, `create:resource_servers`, `update:resource_servers`
+  - `read:resource_servers`, `create:resource_servers`, `update:resource_servers`
   - `read:client_credentials`, `create:client_credentials`

(Note: Review the exact formatting in the original markdown to ensure commas are single, not double.)

Committable suggestion skipped: line range outside the PR's diff.

🧰 Tools
🪛 LanguageTool

[typographical] ~87-~87: ２つの連続するコンマ
Context: ...与して Authorize: - read:clients, create:clients, update:clients, delete:clients ...

(DOUBLE_PUNCTUATION)

[typographical] ~88-~88: ２つの連続するコンマ
Context: ...:clients -read:resource_servers, create:resource_servers, update:resourc...

(DOUBLE_PUNCTUATION)

🤖 Prompt for AI Agents 
In docs/QUICKSTART.md around lines 87 to 88 there are double consecutive commas
in the permission lists (typo/formatting issue); remove the extra commas so each
permission is separated by a single comma, ensure backtick-wrapped permissions
remain intact, and eliminate any trailing duplicate commas — then preview
markdown or run a linter to confirm no remaining double commas.

- `read:client_credentials`, `create:client_credentials`
5. **Settings** タブから Domain, Client ID, Client Secret を取得

### ステップ 4: ローカル環境の起動
### Terraform でセットアップ

```bash
# Docker Desktop を起動してから実行
make start
```

これにより、LocalStack（AWS ローカルエミュレーター）、DynamoDB（テナント・設定データ）、Tenant Management API（バックエンド）、Control Plane UI、Application Plane UI が自動的に起動します。

### ステップ 5: アプリケーションにアクセス

ブラウザで Control Plane（<http://localhost:3000>）と Application Plane（<http://localhost:3001>）にアクセスしてください。

## 📦 主な Makefile コマンド
# 変数ファイルを作成
cp infrastructure/terraform/environments/dev/terraform.tfvars.example \
infrastructure/terraform/environments/dev/terraform.tfvars

```bash
# ローカル環境管理
make start # ローカル環境を一括起動（推奨）
make stop # ローカル環境を一括停止
make restart # ローカル環境を再起動

# Auth0 セットアップ
make auth0-setup # Auth0 を Terraform でセットアップ（init + apply + output）
make auth0-init # Terraform 初期化
make auth0-plan # 変更プレビュー
make auth0-apply # 設定適用
make auth0-output # 認証情報を表示

# コード品質
make lint # Linter を実行
make format # コードを自動整形
make typecheck # TypeScript 型チェック
make before-commit # コミット前チェック（lint, format, typecheck, test, build）

# テスト
make test # テストを実行
make test-coverage # カバレッジレポート付きテスト（99% 以上必須）

# インフラ
make localstack-up # LocalStack を起動
make localstack-down # LocalStack を停止
# 取得した認証情報を terraform.tfvars に設定してから実行
make auth0-setup
```

詳細は `make help` を実行してください。
表示された認証情報を各アプリの `.env.local` に設定してください。

</details>

## 🛠 トラブルシューティング

Expand All @@ -200,27 +115,11 @@ docker ps
# エラーが出る場合は Docker Desktop を再起動
```

### Auth0 ログインでエラーが発生

**エラー: "Invalid redirect URI"**
- Auth0 Dashboard で Application の **Allowed Callback URLs** を確認
- `http://localhost:3000/api/auth/callback/auth0` が設定されているか確認

**エラー: "Invalid client or Invalid client credentials"**
- `.env.local` の `AUTH0_CLIENT_SECRET` が正しいか確認
- `make auth0-output` で再度認証情報を確認

**エラー: "Configuration error"**
- `.env.local` の `AUTH_SECRET` が設定されているか確認
- `openssl rand -base64 32` で再生成して設定

### ポートが既に使用されている

```bash
# 使用中のポートを確認
lsof -i :3000
lsof -i :3001
lsof -i :4566
lsof -i :3000 -i :3001 -i :4566

# プロセスを終了（PID を指定）
kill -9 <PID>
Expand All @@ -232,53 +131,30 @@ kill -9 <PID>
# LocalStack のログを確認
docker compose logs localstack

# LocalStack を再起動
make localstack-down
make localstack-up
# 再起動
make stop && make start
```

### Terraform エラー

**エラー: "terraform.tfvars が見つかりません"**
```bash
# terraform.tfvars を作成
cp infrastructure/terraform/environments/dev/terraform.tfvars.example \
infrastructure/terraform/environments/dev/terraform.tfvars
# ファイルを編集して認証情報を入力
```
### Auth0 関連のエラー（Auth0 を使用する場合のみ）

**エラー: "Auth0 API error"**
- Auth0 Management API の権限が正しく付与されているか確認
- M2M アプリが Auth0 Management API に対して Authorized されているか確認
| エラー | 対処 |
|--------|------|
| Invalid redirect URI | Auth0 Dashboard で Allowed Callback URLs に `http://localhost:3000/api/auth/callback/auth0` を設定 |
| Invalid client credentials | `.env.local` の `AUTH0_CLIENT_SECRET` を確認、`make auth0-output` で再取得 |
| Configuration error | `AUTH_SECRET` が設定されているか確認（`openssl rand -base64 32` で生成） |

## 🧹 環境のクリーンアップ

```bash
# すべて停止
make stop

# LocalStack のデータも削除
docker compose down -v
make stop # サービス停止
docker compose down -v # データも含めて完全削除
```

## 📚 次のステップ

- [README.md](../README.md) - プロジェクト概要
- [CLAUDE.md](../CLAUDE.md) - 開発ガイド（Claude Code/AI エージェント向け）
- [アーキテクチャ設計](./architecture.md)（予定）

## 🔐 セキュリティ注意事項

ローカル開発環境の設定です。本番環境では以下の点に注意してください。

- `.env.local` は Git にコミットしないこと（`.gitignore` で除外済み）
- `terraform.tfvars` も Git にコミットしないこと
- 本番環境では強力なシークレットを使用すること
- Auth0 の本番テナントでは厳格なアクセス制御を設定すること
- [CLAUDE.md](../CLAUDE.md) - 開発ガイド

---

**所要時間**: 約 10〜15 分
**難易度**: ⭐⭐☆☆☆（中級）

質問や問題があれば、[GitHub Issues](https://github.com/susumutomita/TenkaCloud/issues) で報告してください。
質問や問題があれば [GitHub Issues](https://github.com/susumutomita/TenkaCloud/issues) で報告してください。