hanarang/hanarang-rails
5
0
Fork 0
Code Issues Pull Requests 7 Actions Packages Projects Releases Wiki Activity
Files
main
hanarang-rails/docs/LOCAL-SETUP.md
이랑이 8c123cb03a feat(v0.1.3): LLM 어댑터 + in-process 모드 + docker-compose — 외부인 배포 친화 
## LLM 공급자 어댑터 (B)

- sister-agent/src/llm/ 에 LlmAdapter 인터페이스 신설. 어댑터 5종:
    openclaw (기존), openai, anthropic, ollama, mock
- 선택은 LLM_PROVIDER 환경변수로. 기본값 mock.
- 모델명은 LLM_MODEL_{MANAGER,PRINCIPAL,LEAD,JUNIOR} 로 외부화.
  OpenClaw 내부 네이밍이 기본값이지만 env 로 얼마든지 갈아끼움.
- openai 어댑터는 OPENAI_BASE_URL 로 OpenRouter / Azure / 로컬 llama.cpp
  서버까지 커버.

## In-process 단일 프로세스 모드 (C)

- sister-agent/src/core.ts 로 executeInvocation 을 library-export
- rails 에 InProcessTransport 추가. 동적 import 로 sister-agent core 를
  로드해 같은 Node 프로세스에서 함수 호출로 실행.
- DirectRailsClient 로 HTTP 루프백 없이 DB 에 직접 쓰기 — 단일
  프로세스에서도 observability 동일.
- RailsConfig 에 transport: "in-process" 추가.
- buildTransports 가 RAILS_TRANSPORT 와 per-stage override 를 지원하도록
  확장. 레거시 RAILS_TRANSPORT_MODE + RAILS_AGENT_*_HOST 도 그대로 호환.

## Git push 외부화 + allowlist env 화

- spawn.ts 의 ENABLE_GIT_PUSH 를 "GITEA_TOKEN 있으면 auto on" 으로 변경.
  기존 Dev 토폴로지는 sister LXC 들에 이미 토큰이 있어서 행동 변화 없음.
- rails.service.ts 의 파일 프록시 allowlist 를 GIT_RAW_ALLOWED_HOSTS
  env 로 외부화. 기본값은 기존 Gitea 호스트 유지.

## Docker / 배포

- Dockerfile 추가. 단일 이미지로 rails + sister-agent 둘 다 빌드.
- docker-compose.yml (기본): mariadb + rails 한 컨테이너 = in-process.
  docker compose up 한 줄로 로컬 E2E 가능.
- docker-compose.full.yml: rails + 4 개 독립 sister 컨테이너 = 분산.

## 설정 샘플 + 문서

- .env.example 완전 재작성: 필수/LLM/토폴로지/Gitea/Discord 5 섹션
- rails.config.local.yaml: in-process 샘플
- rails.config.distributed.yaml: http 분산 샘플
- docs/LOCAL-SETUP.md: 30분 퀵스타트 (Docker + 네이티브 두 경로)
- README 에 "5분 퀵스타트" + 토폴로지 표 + LLM 공급자 목록 추가

## 테스트

- tests/transport-build.test.ts (6 테스트): 기본값 / in-process /
  per-stage override / http 엔드포인트 누락 / env 기반 wiring / 레거시
  env 호환
- 전체 테스트 105 → 111 통과
2026-04-10 21:51:53 +09:00

219 lines
7.1 KiB
Markdown
Raw Permalink Blame History

# 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` 순으로 읽기
Reference in New Issue View Git Blame Copy Permalink