Skip to content

docs: Quick Start Guide を最新化 #41

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
Nov 16, 2025
Merged

docs: Quick Start Guide を最新化 #41

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
78 changes: 72 additions & 6 deletions docs/QUICKSTART.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,37 @@ make start-all
- Keycloak の Realm と Client の自動作成
- `.env.local` の作成（存在しない場合）

出力された環境変数を `.env.local` に設定してください。
出力された環境変数を `frontend/control-plane/.env.local` に設定してから、Control Plane UI を起動してください。

### 方法 2: 手動セットアップ
```bash
cd frontend/control-plane
bun run dev
```

ブラウザで <http://localhost:3000> を開いてログインしてください。

### 方法 2: Docker Compose で起動（本番環境に近い）

Docker イメージをビルドして、Keycloak と連携した環境で起動します。

```bash
# Docker イメージをビルドして起動
make docker-run

# アクセス先
# - Control Plane UI: http://localhost:3000
# - Keycloak: http://localhost:8080
```

停止する場合は次を実行します。

```bash
make docker-stop
```

この方法では `.env.local` ファイルが必要です。事前に `frontend/control-plane/.env.local` を作成してください。
Comment on lines +35 to +54

@coderabbitai coderabbitai Bot Nov 16, 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 | 🔴 Critical

🧩 Analysis chain

Verify Makefile targets and clarify .env.local setup discrepancy for Method 2.

Method 1 auto-creates .env.local via make start-all, but Method 2 requires pre-creating it. This inconsistency needs clarification:

  1. Should Method 2 also auto-create .env.local, or is there a reason users must create it manually?
  2. The guidance for Method 2 should either link to the manual setup instructions (Method 3, lines 136-164) or duplicate the key .env.local creation steps.
  3. Verify that make docker-run, make docker-stop, and make docker-build targets exist in the Makefile.

🏁 Script executed:

#!/bin/bash
# Verify that referenced Makefile targets exist
cd "$(git rev-parse --show-toplevel)" || exit 1

# Extract target names from the Makefile
echo "=== Checking for referenced Makefile targets ==="
for target in start-all docker-run docker-stop stop-all restart-all docker-build setup-keycloak; do
  if grep -q "^$target:" Makefile 2>/dev/null || grep -q "^\.PHONY:.*$target" Makefile 2>/dev/null; then
    echo "✓ Target '$target' exists"
  else
    echo "✗ Target '$target' NOT FOUND"
  fi
done

Length of output: 265

I found critical issues. The documentation references three Makefile targets that don't exist. Let me search for what docker-related targets actually exist in the Makefile:

🏁 Script executed:

#!/bin/bash
# Search for docker-related targets in Makefile
echo "=== All Docker-related targets in Makefile ==="
grep -E "^[a-zA-Z0-9_-]*docker" Makefile | head -20

echo ""
echo "=== All .PHONY targets ==="
grep "\.PHONY" Makefile

echo ""
echo "=== All targets in Makefile (first 50) ==="
grep "^[a-zA-Z0-9_-]*:" Makefile | sed 's/:$//' | head -50

Length of output: 244

Let me locate the Makefile first:

🏁 Script executed:

#!/bin/bash
# Find Makefile in repository
echo "=== Finding Makefile ==="
fd -t f "^Makefile$"

echo ""
echo "=== Searching for docker-related targets ==="
fd -t f "^Makefile$" --exec grep -E "^[a-zA-Z0-9_-]*docker" {} \;

echo ""
echo "=== Searching for all targets ==="
fd -t f "^Makefile$" --exec grep -E "^[a-zA-Z0-9_-]+:" {} \;

Length of output: 380

Replace non-existent Makefile targets in Method 2 (lines 42 and 49).

The documentation references three Makefile targets that don't exist:

  • make docker-run (line 42) — should be make start-all
  • make docker-stop (line 49) — should be make stop-all
  • make docker-build — no equivalent target exists

Update lines 35-54 to use the correct commands:

  • Replace make docker-run with make start-all
  • Replace make docker-stop with make stop-all
  • Remove or clarify the docker-build reference since no such target exists
🤖 Prompt for AI Agents 
In docs/QUICKSTART.md around lines 35 to 54, the Makefile targets referenced are
incorrect: replace the non-existent "make docker-run" with "make start-all" and
replace "make docker-stop" with "make stop-all"; remove any mention of "make
docker-build" (or replace it with a note that no equivalent target exists) and
update the accompanying example commands and sentences to reflect these correct
targets so the instructions match the project's Makefile.


### 方法 3: 手動セットアップ

#### 1. Docker Desktop を起動

Expand Down Expand Up @@ -241,7 +269,19 @@ PORT=3001 bun run dev

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

### Keycloak を停止
### すべて停止（推奨）

```bash
make stop-all
```

### Docker Compose 環境を停止

```bash
make docker-stop
```

### Keycloak のみ停止

```bash
cd infrastructure/docker/keycloak
Expand All @@ -251,12 +291,13 @@ docker compose down
### データも削除する場合

```bash
cd infrastructure/docker/keycloak
docker compose down -v
```

### Next.js を停止

ターミナルで `Ctrl + C` を押す。
開発サーバーを起動しているターミナルで `Ctrl + C` を押す。

## 📚 次のステップ

Expand All @@ -266,13 +307,32 @@ docker compose down -v

## 💡 開発時のヒント

### 環境を再起動

```bash
# 全体を再起動
make restart-all

# Docker Compose 環境のみ再起動
make docker-stop
make docker-run
```

### Keycloak のデータをリセット

```bash
cd infrastructure/docker/keycloak
docker compose down -v
docker compose up -d
# 再度 Realm と Client を作成
# 再度 Realm と Client を作成（または make setup-keycloak を実行）
```

### Docker イメージを再ビルド

コードを変更した後、Docker イメージを再ビルドする場合は次を実行します。

```bash
make docker-build
```

### Next.js のキャッシュをクリア
Expand All @@ -291,7 +351,13 @@ cd infrastructure/docker/keycloak
docker compose logs -f keycloak
```

**Next.js**:
**Control Plane UI (Docker Compose)**:
```bash
cd frontend/control-plane
docker compose logs -f control-plane-ui
```
Comment on lines +354 to +358

@coderabbitai coderabbitai Bot Nov 16, 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

🧩 Analysis chain

Verify Control Plane UI Docker Compose logging path and service name.

The documentation references docker compose logs -f control-plane-ui, but this assumes:

  1. The Control Plane UI service is managed via Docker Compose in the same stack as described in Method 2.
  2. The service is named control-plane-ui in the docker-compose.yml.

Verify that this path and service name match the actual configuration. If this only applies to Method 2 (Docker Compose), consider adding a clarifying note (e.g., "when using Method 2").

🏁 Script executed:

#!/bin/bash
# Verify docker-compose service names and structure
cd "$(git rev-parse --show-toplevel)" || exit 1

# Search for docker-compose.yml files and check service names
echo "=== Checking docker-compose.yml files for control-plane-ui service ==="
for compose_file in $(find . -name "docker-compose.yml" -o -name "docker-compose.yaml" | grep -v node_modules); do
  echo "File: $compose_file"
  if grep -q "control-plane-ui" "$compose_file"; then
    echo "  ✓ Found 'control-plane-ui' service"
    grep -A 5 "control-plane-ui:" "$compose_file" | head -10
  else
    echo "  ℹ 'control-plane-ui' not found in this file"
  fi
done

Length of output: 174

I need to search more thoroughly for docker-compose files, particularly in the frontend/control-plane directory mentioned in the documentation.

I need to search more thoroughly for docker-compose files, particularly in the frontend/control-plane directory mentioned in the documentation.

🏁 Script executed:

#!/bin/bash
# More comprehensive search for docker-compose files
cd "$(git rev-parse --show-toplevel)" || exit 1

echo "=== Searching all docker-compose files in the repository ==="
find . -type f \( -name "docker-compose.yml" -o -name "docker-compose.yaml" \) 2>/dev/null | sort

echo ""
echo "=== Checking frontend/control-plane directory ==="
ls -la frontend/control-plane/ 2>/dev/null || echo "frontend/control-plane directory not found or not accessible"

echo ""
echo "=== Searching for 'control-plane' references in docker-compose files ==="
find . -type f \( -name "docker-compose.yml" -o -name "docker-compose.yaml" \) -exec grep -l "control-plane" {} \; 2>/dev/null

echo ""
echo "=== Searching for 'ui' service references in docker-compose files ==="
find . -type f \( -name "docker-compose.yml" -o -name "docker-compose.yaml" \) -exec grep -E "^\s*(control-|.*-ui):" {} + 2>/dev/null

Length of output: 1330

🏁 Script executed:

#!/bin/bash
# More comprehensive search for docker-compose files
cd "$(git rev-parse --show-toplevel)" || exit 1

echo "=== Searching all docker-compose files in the repository ==="
find . -type f \( -name "docker-compose.yml" -o -name "docker-compose.yaml" \) 2>/dev/null | sort

echo ""
echo "=== Checking frontend/control-plane directory ==="
ls -la frontend/control-plane/ 2>/dev/null || echo "frontend/control-plane directory not found or not accessible"

echo ""
echo "=== Searching for 'control-plane' references in docker-compose files ==="
find . -type f \( -name "docker-compose.yml" -o -name "docker-compose.yaml" \) -exec grep -l "control-plane" {} \; 2>/dev/null

echo ""
echo "=== Checking all service names defined in docker-compose files ==="
find . -type f \( -name "docker-compose.yml" -o -name "docker-compose.yaml" \) -exec grep -E "^\s+[a-z0-9\-]+:\s*$" {} + 2>/dev/null | head -30

Length of output: 1507

I need to examine the documentation context to understand what Method 2 is and what the actual deployment setup should be.

🏁 Script executed:

#!/bin/bash
cd "$(git rev-parse --show-toplevel)" || exit 1

echo "=== Checking docs/QUICKSTART.md around lines 354-358 ==="
sed -n '340,370p' docs/QUICKSTART.md

echo ""
echo "=== Checking for any root-level or infrastructure docker-compose files ==="
find . -maxdepth 2 -type f \( -name "docker-compose.yml" -o -name "docker-compose.yaml" \)

echo ""
echo "=== Searching for 'Method 2' or Docker Compose references in QUICKSTART.md ==="
grep -n "Method\|Docker\|docker-compose\|docker compose" docs/QUICKSTART.md | head -20

Length of output: 1351

Correct the Control Plane UI logging documentation—the referenced service and deployment method do not exist.

The documentation references a control-plane-ui Docker Compose service that does not exist in the repository. The only docker-compose setup is for Keycloak at infrastructure/docker/keycloak/. The frontend/control-plane directory is a Next.js application that runs via bun run dev in development, not via Docker Compose. The logging command docker compose logs -f control-plane-ui will fail.

Change the Control Plane UI section to reference the actual development method (logs displayed in the terminal where bun run dev is running) or remove the section if it's not applicable to the current deployment architecture.

🤖 Prompt for AI Agents 
In docs/QUICKSTART.md around lines 354 to 358, the Control Plane UI subsection
incorrectly instructs users to tail logs from a non-existent docker-compose
service `control-plane-ui`; update this section to reflect reality by either (A)
replacing the docker-compose command with guidance that the
frontend/control-plane is a Next.js app run via `bun run dev` and that logs
appear in the terminal where that command is run (add brief steps: cd
frontend/control-plane && bun run dev), or (B) remove the Control Plane UI
docker-compose logging snippet entirely if the project will not support a Docker
deployment for the UI; ensure the text clearly states the correct development
workflow and removes any reference to `control-plane-ui` docker compose service.


**Next.js (開発サーバー)**:
ターミナルに表示される。

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