네이티브 개발 가이드
네이티브 개발 가이드 (Native Development Guide)
Docker 없이 AgentOps 백엔드 서비스를 네이티브로 실행하는 완전한 가이드를 소개해요. 개요부터 설치, 환경 설정, 테스트, 디버깅, IDE 설정까지 알아볼게요.
출처: 문서
본문
네이티브 개발 가이드
이 가이드는 Docker 없이 로컬 머신에서 AgentOps 백엔드 서비스를 네이티브로 실행하는 방법을 다룹니다. 네이티브 개발은 가장 빠른 반복 주기를 제공하며 활발한 개발 작업에 이상적입니다.
개요 (Overview)
네이티브로 실행한다는 것은 다음을 의미합니다.
- 더 빠른 시작 시간 - 컨테이너 오버헤드 없음
- 직접적인 파일 시스템 접근 - 즉시 코드 변경
- 네이티브 디버깅 - 선호하는 IDE 디버거 사용
- 리소스 효율성 - 더 낮은 메모리와 CPU 사용
사전 요구사항 (Prerequisites)
시스템 요구사항 (System Requirements)
- Python 3.12+ (pip 또는 uv 포함)
- Node.js 18+ (npm, yarn, 또는 bun 포함)
- Git 버전 관리용
- Just (선택) 편의 명령어용
외부 서비스 (External Services)
다음 외부 서비스가 설정되어 있어야 합니다.
- Supabase - 데이터베이스와 인증
- ClickHouse - 분석 데이터베이스
- Stripe (선택) - 결제 처리
퀵 스타트 (Quick Start)
1. 클론과 설정 (Clone and Setup)
git clone https://github.com/AgentOps-AI/AgentOps.Next.git
cd AgentOps.Next/app
# Copy environment files
cp .env.example .env
cp api/.env.example api/.env
cp dashboard/.env.example dashboard/.env.local
2. 의존성 설치 (Install Dependencies)
루트 의존성 (Root Dependencies)
# Install shared tools (linting, formatting)
bun install
# Install Python development tools
uv pip install -r requirements-dev.txt
API 의존성 (API Dependencies)
cd api
# Using uv (recommended)
uv pip install -e .
# Or using pip
pip install -e .
cd ..
대시보드 의존성 (Dashboard Dependencies)
cd dashboard
# Using bun (recommended)
bun install
# Or using npm
npm install
cd ..
3. 환경 변수 설정 (Configure Environment Variables)
서비스 자격 증명으로 환경 파일을 업데이트하세요. 아래의 외부 서비스 설정을 참조하세요.
4. 서비스 시작 (Start Services)
# Terminal 1: API Server
cd api && uv run python run.py
# Terminal 2: Dashboard (in a new terminal)
cd dashboard && bun dev
# Terminal 3: Landing Page (optional, in a new terminal)
cd landing && bun dev
5. 설정 검증 (Verify Setup)
- API Health: http://localhost:8000/health
- API Documentation: http://localhost:8000/redoc
- Dashboard: http://localhost:3000
- Landing Page: http://localhost:3001
외부 서비스 설정 (External Services Setup)
Supabase 설정
- supabase.com에서 새 프로젝트 생성
- Settings → API에서 프로젝트 자격 증명 가져오기
- 데이터베이스 스키마 설정:
cd supabase npx supabase db push api/.env와dashboard/.env.local업데이트:# API environment SUPABASE_URL=https://your-project-id.supabase.co SUPABASE_KEY=your-service-role-key # Dashboard environment NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
ClickHouse 설정
- ClickHouse Cloud에 가입하거나 자체 호스팅
- 데이터베이스를 만들고 연결 정보 가져오기
- 스키마 적용:
# Use the schema from clickhouse/schema_dump.sql clickhouse-client --host your-host --query "$(cat clickhouse/schema_dump.sql)" api/.env업데이트:CLICKHOUSE_HOST=your-host.clickhouse.cloud CLICKHOUSE_PORT=8123 CLICKHOUSE_USER=default CLICKHOUSE_PASSWORD=your-password CLICKHOUSE_DATABASE=your-database CLICKHOUSE_SECURE=true
API 서버 설정 (API Server Setup)
환경 설정 (Environment Configuration)
api/.env의 핵심 변수:
# Database Connections
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-service-role-key
CLICKHOUSE_HOST=your-clickhouse-host
CLICKHOUSE_PASSWORD=your-password
# Application Settings
APP_URL=http://localhost:3000
LOGGING_LEVEL=INFO
JWT_SECRET_KEY=your-jwt-secret-key
# Optional Integrations
SENTRY_DSN=your-sentry-dsn
SENTRY_ENVIRONMENT=development
API 서버 실행 (Running the API Server)
Just 사용 (권장)
just api-native
수동 명령어 (Manual Command)
cd api
uv run python run.py
대체 방법 (Alternative Methods)
# Using pip and python directly
cd api
pip install -e .
python run.py
# Using uvicorn directly
cd api
uvicorn agentops.main:app --host 0.0.0.0 --port 8000 --reload
API 개발 기능 (API Development Features)
- 파일 변경 시 자동 리로드
- http://localhost:8000/docs에서 대화형 API 문서
- http://localhost:8000/redoc에서 ReDoc 문서
- http://localhost:8000/health에서 헬스 체크
대시보드 설정 (Dashboard Setup)
환경 설정 (Environment Configuration)
dashboard/.env.local의 핵심 변수:
# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
# Application URLs
NEXT_PUBLIC_APP_URL=http://localhost:8000
NEXT_PUBLIC_SITE_URL=http://localhost:3000
# Feature Flags
NEXT_PUBLIC_ENVIRONMENT_TYPE=development
NEXT_PUBLIC_PLAYGROUND=true
# Optional Services
NEXT_PUBLIC_POSTHOG_KEY=your-posthog-key
NEXT_PUBLIC_SENTRY_DSN=your-sentry-dsn
대시보드 실행 (Running the Dashboard)
Just 사용 (권장)
just fe-run
수동 명령어 (Manual Commands)
cd dashboard
# Using bun
bun install
bun dev
# Using npm
npm install
npm run dev
# Using yarn
yarn install
yarn dev
대시보드 개발 기능 (Dashboard Development Features)
- 파일 변경 시 핫 리로드
- React 컴포넌트용 Fast Refresh
- 개발 도구 통합
- 디버깅용 소스 맵
개발 워크플로우 (Development Workflow)
일일 개발 루틴 (Daily Development Routine)
- 서비스 시작:
# Terminal 1 just api-native # Terminal 2 just fe-run - 코드를 변경하세요
- 변경사항을 테스트 - 서비스가 자동 리로드됩니다
- 커밋 전에 테스트 실행:
just test
코드 품질 워크플로우 (Code Quality Workflow)
# Format code
just format
# Run linting
just lint
# Run tests
just test
# All-in-one quality check
just format && just lint && just test
데이터베이스 개발 (Database Development)
# Apply Supabase migrations
cd supabase
npx supabase db push
# Reset database (development only)
npx supabase db reset
# Generate TypeScript types
npx supabase gen types typescript --local > types/database.types.ts
테스트 (Testing)
API 테스트 (API Testing)
cd api
# Run all tests
pytest
# Run with coverage
pytest --cov=agentops
# Run specific test file
pytest tests/test_auth.py
# Run with verbose output
pytest -v
대시보드 테스트 (Dashboard Testing)
cd dashboard
# Run all tests
bun test
# Run tests in watch mode
bun test --watch
# Run tests with coverage
bun test --coverage
통합 테스트 (Integration Testing)
# Run full test suite
just test
# Test API and dashboard separately
just api-test
just fe-test
디버깅 (Debugging)
API 디버깅 (API Debugging)
- IDE에서 중단점 설정
- 디버거로 실행:
cd api python -m debugpy --listen 5678 --wait-for-client run.py - IDE 디버거를 포트 5678에 연결
대시보드 디버깅 (Dashboard Debugging)
- 브라우저 개발 도구 사용 (F12)
- Next.js 디버깅:
cd dashboard NODE_OPTIONS='--inspect' bun dev - chrome://inspect에서 디버거 연결
로그 디버깅 (Log Debugging)
# API logs with debug level
cd api
LOGGING_LEVEL=DEBUG uv run python run.py
# Dashboard logs
cd dashboard
DEBUG=* bun dev
성능 최적화 (Performance Optimization)
API 성능 (API Performance)
- 가장 빠른 개발을 위해 네이티브 Python 사용
- uvicorn으로 핫 리로드 활성화
- py-spy로 프로파일링:
pip install py-spy py-spy top --pid $(pgrep -f "python run.py")
대시보드 성능 (Dashboard Performance)
- 더 빠른 패키지 관리를 위해 bun 사용
- Fast Refresh 활성화 (기본 활성화)
- 번들 크기 분석:
cd dashboard ANALYZE=true bun run build
문제 해결 (Troubleshooting)
일반적인 문제 (Common Issues)
Python import 오류:
# Reinstall in editable mode
cd api
uv pip install -e .
Node.js 모듈을 찾을 수 없음:
# Clear and reinstall
cd dashboard
rm -rf node_modules package-lock.json
bun install
포트 이미 사용 중:
# Find and kill process
lsof -i :8000 # API port
lsof -i :3000 # Dashboard port
kill -9 <PID>
데이터베이스 연결 문제:
.env파일의 자격 증명을 확인하세요- 네트워크 연결을 확인하세요
- 외부 서비스가 실행 중인지 확인하세요
성능 문제 (Performance Issues)
느린 API 시작:
# Use uv for faster Python package management
uv pip install -e .
느린 대시보드 리로드:
# Use bun instead of npm
cd dashboard
rm -rf node_modules
bun install
개발 환경 리셋 (Development Environment Reset)
# Clean everything and start fresh
rm -rf api/.venv dashboard/node_modules node_modules
just setup
IDE 설정 (IDE Configuration)
VS Code
권장 확장:
- Python
- Pylance
- ES7+ React/Redux/React-Native snippets
- Tailwind CSS IntelliSense
- Prettier - Code formatter
설정 (.vscode/settings.json):
{
"python.defaultInterpreterPath": "./api/.venv/bin/python",
"python.linting.enabled": true,
"python.linting.ruffEnabled": true,
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll.eslint": true
}
}
PyCharm
- Python 인터프리터를
./api/.venv/bin/python으로 설정 - Python 린팅용 Ruff 활성화
- 대시보드용 Node.js 인터프리터 설정
- API와 대시보드용 실행 설정 구성
고급 설정 (Advanced Configuration)
커스텀 환경 변수 (Custom Environment Variables)
.env 파일에 커스텀 변수를 추가하세요.
# Custom API settings
CUSTOM_FEATURE_FLAG=true
DEBUG_SQL_QUERIES=false
# Custom dashboard settings
NEXT_PUBLIC_CUSTOM_FEATURE=enabled
개발 프록시 (Development Proxy)
개발에서 API 호출용 프록시 설정:
// dashboard/next.config.js
module.exports = {
async rewrites() {
return [
{
source: '/api/:path*',
destination: 'http://localhost:8000/:path*',
},
]
},
}
핫 리로드 설정 (Hot Reload Configuration)
핫 리로드 동작을 미세 조정:
# api/run.py
if __name__ == "__main__":
import uvicorn
uvicorn.run(
"agentops.main:app",
host="0.0.0.0",
port=8000,
reload=True,
reload_dirs=["agentops"], # Only watch specific directories
reload_excludes=["*.pyc", "*.log"], # Exclude certain files
)
다음 단계 (Next Steps)
네이티브 개발 환경이 실행되면:
api/agentops/main.py와dashboard/pages/index.tsx부터 코드베이스를 탐색하세요- 간단한 컴포넌트나 API 엔드포인트 수정으로 첫 변경을 해보세요
- 변경사항에 대한 테스트를 작성하세요
- 디버깅과 린팅을 위해 IDE를 설정하세요
- 커뮤니티에 참여하세요 - 다른 개발자와 연결
프로덕션 배포에 대해서는 배포 가이드를 참조하세요.