README.md

---
title: CD
sdk: docker
app_port: 7860
---

# Tranimal Run Workspace

MSA 기반 로컬 개발용 워크스페이스입니다.

## 구조

```text
main/                    # Next.js frontend
api/
  api-gateway/           # 단일 진입 API
  auth-service/          # 인증/회원/런 세션 저장
  ai-service/            # 경로 생성/CLIP 점수화
router/ai/               # OSM + CLIP 파이프라인 스크립트
docker-compose.yml
.env
```
<!-- 요청하신 정책에 맞춰 모든 서비스는 로컬 DB를 사용하지 않고, 외부 DB(RDS)만 사용하도록 구성했습니다. AI 기능은 api-gateway -> ai-service -> ai/ 순서로만 호출됩니다. -->

## 빠른 시작

1. 루트 `.env` 준비
2. 컨테이너 실행

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

3. 마이그레이션 (최초 1회 또는 스키마 변경 시)

```bash
docker compose exec auth-service alembic upgrade head
```

접속:
- Frontend: `http://localhost:3000`
- API Gateway: `http://localhost:8000`
- Auth Service: `http://localhost:8001`
- AI Service: `http://localhost:8002`

## Hugging Face Spaces 배포

무료 임시 시연용 Docker Space 배포 구성입니다.

Space 설정:
- SDK: `Docker`
- Template: `Blank`
- Hardware: `CPU Basic (Free)`
- Storage Bucket: `Off`
- Dev Mode: `Off`
- App port: `7860`

Space의 `Settings > Variables and secrets`에 값을 등록합니다. DB URL, SMTP 비밀번호, JWT 키는 반드시 `Secret`으로 넣고 저장소에 커밋하지 않습니다.

Secrets:
- `AUTH_DATABASE_URL`
- `PROTOTYPE_PGVECTOR_URL`
- `TEXT_PROTOTYPE_PGVECTOR_URL`
- `JWT_SECRET_KEY`
- `GOOGLE_OAUTH_CLIENT_ID` (Google 로그인을 쓰는 경우)
- `SMTP_USERNAME`, `SMTP_PASSWORD`, `SMTP_FROM_EMAIL` (메일 발송을 쓰는 경우)

Variables:
- `NEXT_PUBLIC_API_BASE_URL=https://<account>-<space>.hf.space`
- `NEXT_INTERNAL_API_PROXY_TARGET=http://127.0.0.1:8000`
- `CORS_ORIGINS=https://<account>-<space>.hf.space`
- `PASSWORD_RESET_FRONTEND_URL=https://<account>-<space>.hf.space/password-reset`
- `AUTH_SERVICE_URL=http://127.0.0.1:8001`
- `AI_SERVICE_URL=http://127.0.0.1:8002`
- `AI_WORKSPACE_DIR=/app/router/ai`
- `TTS_DEVICE=cpu`
- `TTS_SPEED=1.0`
- `TTS_CACHE_DIR=/tmp/runnimal-tts-cache`

GitHub 저장소의 `DemoService` 브랜치가 Hugging Face Space와 동기화됩니다. GitHub 저장소 설정에서 `HUGGINGFACE_TOKEN` secret을 먼저 등록합니다.

```text
GitHub repository > Settings > Secrets and variables > Actions > New repository secret
Name: HUGGINGFACE_TOKEN
Value: Hugging Face write token
```

그 다음 `DemoService` 브랜치를 GitHub에 push합니다.

```bash
git switch DemoService
git push -u origin DemoService
```

이 브랜치에 포함된 `.github/workflows/sync-huggingface-space.yml`가 `tkadkghdlf/CD` Space로 파일을 동기화합니다. Hugging Face 쪽 하드웨어는 계속 `CPU Basic (Free)`로 유지하고, Storage Bucket/Dev Mode/Custom Hardware는 켜지 않습니다.

RDS를 사용하는 경우, Hugging Face 컨테이너가 DB에 접속할 수 있도록 RDS 보안 그룹의 PostgreSQL `5432` 포트를 허용해야 합니다. 임시 시연을 위해 `0.0.0.0/0`을 열었다면 시연이 끝난 뒤 바로 닫습니다.

## 환경변수 (.env)

루트 `.env`에 아래 키를 설정합니다.

### 필수

- `AUTH_DATABASE_URL`
  - auth-service가 사용하는 PostgreSQL URL
  - 예: `postgresql+psycopg://USER:PASS@HOST:5432/DB?sslmode=require`

### AI 라우트/pgvector 사용 시 권장

- `PROTOTYPE_PGVECTOR_URL`
- `PROTOTYPE_PGVECTOR_TABLE` (기본: `quickdraw_prototypes`)
- `PROTOTYPE_PGVECTOR_SOURCE` (기본: `quickdraw_avg_v1`)
- `TEXT_PROTOTYPE_PGVECTOR_URL`
- `TEXT_PROTOTYPE_PGVECTOR_TABLE` (기본: `quickdraw_text_prototypes`)
- `TEXT_PROTOTYPE_PGVECTOR_SOURCE` (기본: `clip_text_prompt_avg_v1`)
- `EMBEDDING_PGVECTOR_URL`
- `EMBEDDING_PGVECTOR_TABLE` (기본: `quickdraw_embeddings`)
- `EMBEDDING_PGVECTOR_SOURCE` (기본: `quickdraw_train_v1`)
- `IMAGE_PROTO_WEIGHT` (예: `0.8`)
- `TEXT_PROTO_WEIGHT` (예: `0.2`)

### 비밀번호 재설정 메일 사용 시

- `PASSWORD_RESET_FRONTEND_URL` (예: `http://localhost:3000/password-reset`)
- `SMTP_HOST`
- `SMTP_PORT`
- `SMTP_USERNAME`
- `SMTP_PASSWORD`
- `SMTP_USE_TLS` (`true`/`false`)
- `SMTP_FROM_EMAIL`
- `SMTP_FROM_NAME`

> SMTP를 설정하지 않으면, 비밀번호 재설정 링크는 메일 대신 auth-service 로그에 출력됩니다.

## AI 경로 생성 API

프론트는 아래 경로를 호출합니다.

```text
POST http://localhost:8000/api/v1/ai/routes/generate
```

주요 파라미터:
- `source`: `place` | `current`
- `place` 또는 `latitude`/`longitude`
- `routeCount`
- `targetDistanceKm`
- `labels`
- `selectedLabel`
- `selectedTopK`

## 성능 메모

현재 ai-service는 시작 시 CLIP 파이프라인을 prewarm 합니다.
- 첫 요청보다 두 번째 요청부터 빠릅니다.
- 이유: 모델/프로토타입 메모리 캐시 재사용

## 주의

- `.env`의 실제 비밀번호/토큰은 커밋하지 마세요.
- `generated_routes`, `cache`, `*.tsbuildinfo` 같은 실행 산출물은 보통 버전관리 제외를 권장합니다.