콘텐츠로 이동

Getting Started

Umbra 레포지토리에 처음 합류하는 개발자를 위한 환경 구성 가이드. 첫 PR 까지 걸리는 시간을 최소화하는 것이 목표다. 이 문서를 순서대로 따라가면 로컬에서 bot/api/worker/web 네 프로세스를 모두 실행할 수 있다.

Why this guide exists

Umbra 는 여러 기술 스택을 동시에 사용한다 (Go + TypeScript + PostgreSQL + Redis + Temporal + Toss API + Discord Gateway). 각 도구의 설치와 설정을 개인이 시행착오로 맞추면 첫 PR 까지 수 일이 걸릴 수 있다. 이 가이드는 그 시간을 한나절로 줄인다.

Prerequisites

하드웨어/OS:

  • macOS 13+ 또는 Ubuntu 22.04+ 또는 WSL2
  • 16GB RAM 이상 (Docker 실행 포함)
  • 50GB 여유 디스크

계정:

  • GitHub 계정 + luxtradev org 초대 승인
  • Discord Developer Portal 접근 (테스트 봇 발급용)
  • Neon 계정 (개인 dev branch 용, 선택 사항)
  • Toss Payments 테스트 키 발급 (결제 관련 작업 시)

1. Install tools

Required

# macOS (Homebrew)
brew install go bun mise atlas docker sqlc just golangci-lint
brew install --cask docker  # Docker Desktop

# Linux
curl -fsSL https://bun.sh/install | bash
# Go: https://go.dev/dl/
# Atlas: https://atlasgo.io/getting-started/#installation
# sqlc: https://docs.sqlc.dev/en/latest/overview/install.html
# mise: https://mise.jdx.dev/getting-started.html
# Docker: https://docs.docker.com/engine/install/
# golangci-lint: https://golangci-lint.run/usage/install/

air (Go hot reload) 와 swag (OpenAPI 생성) 은 mise.toml 이 자동 설치합니다 — 다음 단계 참조.

Version pinning

프로젝트 루트의 mise.toml 이 tool 버전을 고정한다. 디렉토리 진입 시 자동 적용:

mise install
# Go 1.23.x, Bun 1.x, Atlas, sqlc, air, swag, golangci-lint 등 설치

Optional

# GitHub CLI (PR 생성)
brew install gh
gh auth login

# Graphite CLI (stacked PR)
brew install withgraphite/tap/graphite
gt auth

# Fly CLI (배포 테스트)
brew install flyctl

2. Clone repository

git clone git@github.com:luxtradev/Umbra.git
cd Umbra

mise 가 자동으로 tool 버전을 맞추면 환경 준비 완료.

3. Environment variables

Copy example

cp .env.example .env

Required values

.env 를 열어 다음을 채운다.

# Database
DATABASE_URL=postgres://umbra:umbra@localhost:5432/umbra_dev?sslmode=disable

# Redis
REDIS_URL=redis://localhost:6379

# Temporal
TEMPORAL_HOST=localhost:7233
TEMPORAL_NAMESPACE=umbra-local

# Discord (팀 dev 봇, Pablo 에게 요청)
DISCORD_BOT_TOKEN=...
DISCORD_CLIENT_ID=...
DISCORD_CLIENT_SECRET=...

# Toss (test keys)
TOSS_SECRET_KEY=test_sk_...
TOSS_CLIENT_KEY=test_ck_...
TOSS_WEBHOOK_SECRET=...

# Encryption (dev 환경 전용)
BILLING_KEY_ENCRYPTION_KEY=<32 bytes hex>

# Session
SESSION_SECRET=<32 bytes hex>

# App (포트 정합: web 5173 / api 8080 / bot internal 8081 / worker internal 8082)
APP_BASE_URL=http://localhost:5173
API_BASE_URL=http://localhost:8080
BOT_API_BASE_URL=http://localhost:8081
WORKER_API_BASE_URL=http://localhost:8082

Discord dev 봇 token 은 Pablo 에게 DM 으로 요청. Toss 테스트 키는 https://docs.tosspayments.com/ 에서 sandbox 발급.

키 생성 (로컬만)

# 32 bytes hex
openssl rand -hex 32

프로덕션 키는 절대 로컬 .env 에 넣지 않는다. Fly secrets 로만 관리.

4. Start infrastructure

Docker Compose 로 PostgreSQL, Redis, Temporal 를 일괄 기동:

docker compose up -d

초기 기동 시간 ~30초. 확인:

docker compose ps
# postgres / redis / temporal / temporal-ui 모두 healthy

Temporal Web UI: http://localhost:8233

5. Initialize database

# Atlas 로 schema 적용
just db-migrate

# Seed data (Plan 마스터 등)
just db-seed

확인:

psql $DATABASE_URL -c "SELECT code FROM licensing.plans;"
# FREE / PRO / ENTERPRISE 세 row

6. Install code dependencies

# Go (bot/api/worker 공용)
go mod download

# TS (web)
bun install

7. Generate code

sqlc, OpenAPI 타입은 git 에 commit 되어 있지만 변경 후 재생성 필요:

# SQL → Go struct/queries
just sqlc

# OpenAPI → TS types (백엔드 실행 후 가능, skip 가능)
just openapi

8. Run processes

네 개의 프로세스를 각각 다른 터미널에서 실행.

# Terminal 1 — Bot
just dev-bot

# Terminal 2 — API
just dev-api

# Terminal 3 — Worker
just dev-worker

# Terminal 4 — Web
just dev-web

각 스크립트는 air 또는 bun vite 로 hot reload 지원.

확인:

  • API: curl http://localhost:8080/healthz → 200
  • Web: http://localhost:5173 → 대시보드 랜딩
  • Bot: Discord 테스트 서버에서 online 으로 표시
  • Worker: 로그에 "asynq worker started", "temporal worker started"

9. First request test

Invite bot to test guild

Pablo 에게 테스트 guild invite link 요청 또는 https://discord.com/api/oauth2/authorize?client_id=... 로 직접 초대.

봇 설치 후 DB 확인:

psql $DATABASE_URL -c "SELECT id, name, discord_guild_id FROM guild.guilds;"
# 새 row 확인

audit.events 에 BotInstalled 기록되었는지:

psql $DATABASE_URL -c "SELECT event_type, summary FROM audit.events ORDER BY recorded_at DESC LIMIT 5;"

Web login

  • http://localhost:5173 → "Login with Discord"
  • OAuth2 승인
  • 대시보드에 내 guild 목록 표시 확인

10. Running tests

# Go 전체 테스트
just test-go

# TS (web) 테스트
just test-web

# 전체
just test

테스트는 mock 을 주로 사용. integration test 는 별도 just test-integration (Docker 필요).

11. First PR workflow

Umbra 의 개발 프로세스 (luxtra-agent 컨벤션):

Issue 먼저

모든 변경은 GitHub Issue 로 시작한다. 이슈 없으면 PR 제출 불가 (루트 CONTRIBUTING.md 참조, 현재 미작성 상태).

gh issue create --title "..." --body "..."

Branch

<type>/<issue-number>/<description>
# 예: feat/42/add-subscription-cancel-endpoint

Commits (Conventional Commits)

  • 타이틀 ~45자, 기술 위주
  • body 는 Problem / Solution 구조 권장 (docs 커밋에서 확립)
  • footer 에 Fixes #42 또는 Closes #42
  • AI 기여 언급 금지 (커밋, PR, 이슈 모두)

PR

# Graphite 사용 시
gt submit

# gh 사용 시
gh pr create --title "..." --body "..."

리뷰

  • PR 은 최소 1명 리뷰 필요 (팀 2인 구조라 Pablo 또는 진욱)
  • CI green 후 merge

12. Troubleshooting

DATABASE_URL 연결 거부

docker compose logs postgres
# "listening on IPv4 address" 확인

포트 충돌 시 docker-compose.yml 에서 host port 변경.

Temporal worker register 실패

Temporal Server 가 먼저 떠 있어야 한다:

docker compose restart temporal
sleep 5
bun run dev:worker

Discord Gateway 401

  • DISCORD_BOT_TOKEN 유효성 확인 (Developer Portal)
  • Pablo 가 토큰 회전했을 수 있음 → 재요청

sqlc 재생성 후 빌드 실패

just sqlc-clean  # 기존 생성 파일 제거
just sqlc        # 재생성
go build ./...

Bun install 이 매우 느림

  • 한국 네트워크에서 npmjs registry 가 느릴 수 있음
  • .bunfig.toml 에 mirror 설정 (팀 기본값 반영)

Atlas migrate apply 실패

스키마 drift 감지:

atlas schema inspect --env local > /tmp/current.hcl
diff /tmp/current.hcl schema

불일치 시 atlas migrate apply --env local --allow-dirty (개발용만).

13. Next steps

환경 구성 완료 후 다음을 읽는다:

See also

  • project-structure.md
  • ../architecture/overview.md
  • ../architecture/tech-stack.md
  • deployment.md