README.md

metadata

title: CD
sdk: docker
app_port: 7860

Tranimal Run Workspace

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

구조

main/                    # Next.js frontend
api/
  api-gateway/           # 단일 진입 API
  auth-service/          # 인증/회원/런 세션 저장
  ai-service/            # 경로 생성/CLIP 점수화
router/ai/               # OSM + CLIP 파이프라인 스크립트
docker-compose.yml
.env

빠른 시작

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

docker compose up -d --build

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

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을 먼저 등록합니다.

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

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

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

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

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 같은 실행 산출물은 보통 버전관리 제외를 권장합니다.