# Local Setup — 30 분 퀵스타트

이 문서는 **본인 환경에서 hanarang-rails 를 처음부터 돌려 보는** 가장 짧은 경로다. 외부 인프라 (Gitea, OpenClaw, 4 개 LXC, MariaDB 전용 서버) 전혀 없어도 로컬에서 E2E 파이프라인을 한 번 돌리는 게 목표.

대상 독자: 이 리포를 처음 클론한 사람. Node 와 docker 를 쓸 줄 아는 사람.

---

## 0. 사전 요구

하나만 선택:

- **Option A — Docker 경로** (권장): `docker` + `docker compose` 만 있으면 끝. MariaDB 까지 컨테이너로 뜬다.
- **Option B — 네이티브 경로**: Node 22, pnpm 9, MariaDB 10.11+ 로컬 설치.

추가로 **LLM 제공자 하나**를 정해 둬야 한다.

| 제공자 | 필요한 것 | 비용 |
|---|---|---|
| `mock` | (없음) | 무료, 진짜 LLM 호출 없음 — FSM 만 확인 |
| `openai` | OpenAI API 키 | 사용량 기반 |
| `anthropic` | Anthropic API 키 | 사용량 기반 |
| `ollama` | 로컬 Ollama + 모델 pull | 무료, 로컬 GPU/CPU |
| `openclaw` | hanarang 내부 런타임 | 외부인 접근 불가 |

**처음이면 `mock` 으로 시작**하는 걸 권장한다. 실제 LLM 없이 파이프라인 전 구간이 동작하는지 먼저 확인하고, 그 다음 원하는 제공자로 바꿔도 늦지 않다.

---

## 1. Docker 경로 (권장)

### 1-1. 클론 + 환경 설정

```bash
git clone https://git.nabomhalang.co.kr/hanarang/hanarang-rails.git
cd hanarang-rails
cp .env.example .env
```

`.env` 에서 최소 이 두 줄만 만져 주면 된다:

```bash
# 모크 모드로 시작 (진짜 LLM 호출 안 함)
LLM_PROVIDER=mock

# Docker compose 가 쓸 DB URL
DATABASE_URL="mysql://rails:rails@mariadb:3306/hanarang_rails"
```

### 1-2. 기동

```bash
docker compose up --build
```

처음 빌드는 몇 분 걸린다. 완료되면 rails 컨테이너가 마이그레이션을 돌리고 HTTP 서버가 18800 포트에서 리스닝한다.

```bash
curl http://localhost:18800/health
# → {"ok":true,"service":"hanarang-rails"}
```

### 1-3. 파이프라인 첫 실행

다른 터미널에서:

```bash
curl -X POST http://localhost:18800/pipelines/start \
  -H 'content-type: application/json' \
  -d '{"project":"todo-app","requirements":"간단한 todo 웹앱"}'
```

응답으로 `pipelineId`, `finalState: done`, `transitions` 숫자가 돌아오면 성공. 파이프라인 상태는:

```bash
curl http://localhost:18800/pipelines/<ID>
```

### 1-4. 실제 LLM 로 갈아타기

`.env` 에서:

```bash
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...
LLM_MODEL_MANAGER=gpt-4o
LLM_MODEL_PRINCIPAL=gpt-4o
LLM_MODEL_LEAD=gpt-4o-mini
LLM_MODEL_JUNIOR=gpt-4o-mini
```

`docker compose up -d --build` 로 재시작. 같은 `curl` 명령을 또 날리면 이번에는 실제 LLM 이 호출되고, 각 junior 가 만든 코드 블록이 `rails-workspace` 볼륨 안으로 저장된다.

> **Anthropic / Ollama / OpenAI 호환 서버** 도 같은 패턴이다. `LLM_PROVIDER` 만 바꾸고 해당 API 키/URL 를 `.env` 에 채워 주면 된다. `.env.example` 파일 주석에 각 제공자별 키 이름이 정리돼 있다.

---

## 2. 네이티브 경로

Docker 없이 로컬 프로세스로 돌리는 경로.

### 2-1. MariaDB 준비

```bash
# brew / apt / 도커 중 편한 방법으로 MariaDB 10.11+ 기동
# 그 다음 DB/사용자 생성:
mysql -u root -p <<SQL
CREATE DATABASE hanarang_rails;
CREATE USER 'rails'@'localhost' IDENTIFIED BY 'rails';
GRANT ALL ON hanarang_rails.* TO 'rails'@'localhost';
SQL
```

### 2-2. 클론 + 빌드

```bash
git clone https://git.nabomhalang.co.kr/hanarang/hanarang-rails.git
cd hanarang-rails
pnpm install

# sister-agent 도 별도 install
cd sister-agent && pnpm install && cd ..
```

### 2-3. 환경 설정

```bash
cp .env.example .env
# 편집:
#   DATABASE_URL="mysql://rails:rails@localhost:3306/hanarang_rails"
#   LLM_PROVIDER=mock
#   RAILS_TRANSPORT=in-process

cp rails.config.local.yaml rails.config.yaml
```

### 2-4. DB 마이그레이션 + 빌드

```bash
pnpm prisma migrate deploy
pnpm prisma generate
pnpm build
cd sister-agent && pnpm build && cd ..
```

### 2-5. 기동 + 테스트

```bash
pnpm rails serve -c rails.config.yaml
```

다른 터미널:

```bash
curl -X POST http://localhost:18800/pipelines/start \
  -H 'content-type: application/json' \
  -d '{"project":"hello","requirements":"Say hi"}'
```

---

## 3. 파일은 어디로 가나?

- Docker 경로: rails 컨테이너의 `/app/rails-projects/<pipelineId>/<stage>/files/` 에 저장되고, `rails-workspace` named volume 에 영속화된다. 컨테이너 밖에서 보려면 `docker compose run --rm rails ls /app/rails-projects/<pipelineId>` 또는 볼륨 mount 변경.
- 네이티브 경로: `$HOME/rails-projects/<pipelineId>/<stage>/files/`.

Gitea auto-push 는 기본적으로 꺼져 있다. 켜고 싶으면 `.env` 에 `GITEA_TOKEN`, `GITEA_BASE_URL`, `GITEA_ORG` 를 채우면 자동으로 켜진다.

---

## 4. 대시보드도 띄우려면

대시보드 (`hanarang-dashboard`) 는 별도 리포다. rails 가 돌아가고 있는 상태에서 같은 MariaDB 를 바라보도록 설정하면 `/rails` 페이지에서 파이프라인 트리가 시각화된다.

```bash
git clone https://git.nabomhalang.co.kr/hanarang/hanarang-dashboard.git
cd hanarang-dashboard/backend
cp .env.example .env
# DATABASE_URL 을 rails 와 같게
# RAILS_API_URL=http://localhost:18800
# GIT_RAW_ALLOWED_HOSTS=git.example.com (optional, for MD viewer)
pnpm install && pnpm build && pnpm start:prod
```

프론트엔드는 별도 프로세스:

```bash
cd ../frontend
pnpm install && pnpm dev
# → http://localhost:3000/rails
```

---

## 5. 자주 막히는 부분

**Q. `pnpm rails run` 이 "DATABASE_URL not set" 에러.**
`.env` 가 rails 의 작업 디렉토리에 있어야 한다. `loadEnv()` 는 `process.cwd()` 기준으로 찾는다.

**Q. Mock 모드인데 LLM 응답이 텅 비어 있다.**
정상이다. Mock 은 결정론 스켈레톤만 확인하려고 있는 거라 파일도 안 만들고 내용도 거의 없다. 실제 LLM 로 바꿔야 의미 있는 산출물이 나온다.

**Q. In-process 모드인데 `sister-agent core module not found`.**
`sister-agent/dist/core.js` 가 빌드되지 않은 상태다. `cd sister-agent && pnpm build`. 또는 `SISTER_AGENT_CORE_PATH` 로 절대 경로 명시.

**Q. OpenAI 대신 OpenRouter / Azure OpenAI / 로컬 llama.cpp 서버를 쓸 수 있나?**
된다. `LLM_PROVIDER=openai` 로 두고 `OPENAI_BASE_URL` 을 바꿔 주면 OpenAI Chat Completions 프로토콜을 말하는 모든 서버에 붙는다.

**Q. 4 개 자매를 진짜 분리된 컨테이너로 돌리고 싶다.**
`docker-compose.full.yml` 을 써라. rails 1 개 + 각 자매 1 개씩 총 6 개 서비스가 뜨고, rails 가 HTTP 로 각 자매에게 invoke 를 보낸다.

---

## 6. 다음 단계

- **구조 전체를 이해하고 싶다면**: [`docs/GUIDE.md`](GUIDE.md) 또는 PDF 버전
- **실제로 코드를 건드리고 싶다면**: [`.plans/design/`](../.plans/design/) 의 설계 문서
- **프롬프트/역할을 본인 도메인에 맞추고 싶다면**: `sister-agent/src/prompts.ts`, `sister-agent/src/roles.ts`, `rails.config.local.yaml` 순으로 읽기