hanarang-rails/docs/LOCAL-SETUP.md

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. 클론 + 환경 설정

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

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

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

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

1-2. 기동

docker compose up --build

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

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

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

다른 터미널에서:

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

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

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

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

.env 에서:

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 준비

# 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. 클론 + 빌드

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. 환경 설정

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 마이그레이션 + 빌드

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

2-5. 기동 + 테스트

pnpm rails serve -c rails.config.yaml

다른 터미널:

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 페이지에서 파이프라인 트리가 시각화된다.

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

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

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 또는 PDF 버전
• 실제로 코드를 건드리고 싶다면: .plans/design/ 의 설계 문서
• 프롬프트/역할을 본인 도메인에 맞추고 싶다면: sister-agent/src/prompts.ts, sister-agent/src/roles.ts, rails.config.local.yaml 순으로 읽기