DOCS/_archive/docs/setups/setup-guide.md

로빙 MVP 설정 가이드

📋 목차

1. 환경 설정
2. Slack 앱 설정
3. OpenAI API 설정
4. 데이터베이스 설정
5. 서버 실행
6. 테스트

🔧 환경 설정

1. 시스템 요구사항

• Python 3.12+
• PostgreSQL 13+
• Git

2. 프로젝트 클론 및 설정

# 저장소 클론
git clone https://github.com/happybell80/ivada.git
cd ivada

# 가상환경 생성
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate  # Windows

# 의존성 설치
pip install -r requirements.txt

3. 환경변수 설정

.env 파일을 생성하고 다음 내용을 입력:

# Slack Configuration
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_SIGNING_SECRET=your-signing-secret
SLACK_APP_TOKEN=xapp-your-app-token

# OpenAI Configuration
OPENAI_API_KEY=your-openai-api-key

# Database Configuration
DATABASE_URL=postgresql://user:password@localhost/ivada_db
TEST_DATABASE_URL=postgresql://user:password@localhost/ivada_test_db

# JWT Configuration
JWT_SECRET_KEY=your-jwt-secret-key-change-in-production
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30

# Application Configuration
DEBUG=True
LOG_LEVEL=INFO
MAX_MEMORY_SIZE=1000

📱 Slack 앱 설정

1. Slack 앱 생성

1. https://api.slack.com/apps 접속
2. "Create New App" 클릭
3. "From scratch" 선택
4. App Name: "Roving" 입력
5. 워크스페이스 선택 후 "Create App" 클릭

2. Bot Token 권한 설정

OAuth & Permissions 페이지에서 다음 Bot Token Scopes 추가:

필수 권한

• app_mentions:read - 앱 멘션 읽기
• channels:read - 채널 정보 읽기
• chat:write - 메시지 전송
• chat:write.public - 공개 채널에 메시지 전송
• im:read - DM 읽기
• im:write - DM 전송
• users:read - 사용자 정보 읽기

선택 권한

• mpim:read - 그룹 DM 읽기
• mpim:write - 그룹 DM 전송
• files:read - 파일 읽기
• files:write - 파일 업로드

3. 앱 설치 및 토큰 획득

1. "Install to Workspace" 클릭
2. 권한 승인
3. Bot User OAuth Token 복사 (xoxb-로 시작)
4. "Basic Information" 페이지에서 Signing Secret 복사

4. 연동 방식 선택

방법 A: HTTP 연동 (ngrok 사용)

1. ngrok 설치

   # Linux/Mac
   wget https://bin.equinox.io/c/bNyj1mQVY4c/ngrok-v3-stable-linux-amd64.tgz
   tar xzf ngrok-v3-stable-linux-amd64.tgz
   
   # ngrok 계정 생성: https://dashboard.ngrok.com/signup
   # authtoken 설정
   ./ngrok config add-authtoken YOUR_AUTHTOKEN
   

2. Event Subscriptions 설정

   • Slack 앱 → "Event Subscriptions" → "Enable Events" ON
   • Request URL: https://your-ngrok-url.ngrok.io/api/slack/events
   • Subscribe to bot events:
     • app_mention
     • message.channels
     • message.groups
     • message.im
     • message.mpim

방법 B: Socket Mode 연동

1. Socket Mode 활성화

   • Slack 앱 → "Socket Mode" → "Enable Socket Mode" ON

2. App-Level Token 생성

   • Token Name: "Roving Socket Token"
   • Scopes: connections:write
   • App Token 복사 (xapp-로 시작)

🤖 OpenAI API 설정

1. API 키 발급

1. https://platform.openai.com/api-keys 접속
2. "Create new secret key" 클릭
3. API 키 복사하여 .env의 OPENAI_API_KEY에 설정

2. 사용량 모니터링

• https://platform.openai.com/usage 에서 사용량 확인
• 필요시 사용량 제한 설정

🗄️ 데이터베이스 설정

1. PostgreSQL 설치 및 설정

# Ubuntu/Debian
sudo apt update
sudo apt install postgresql postgresql-contrib

# macOS (Homebrew)
brew install postgresql
brew services start postgresql

# 데이터베이스 생성
sudo -u postgres createdb ivada_db
sudo -u postgres createdb ivada_test_db

2. 데이터베이스 사용자 생성

-- PostgreSQL 콘솔에서 실행
sudo -u postgres psql

CREATE USER ivada_user WITH ENCRYPTED PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE ivada_db TO ivada_user;
GRANT ALL PRIVILEGES ON DATABASE ivada_test_db TO ivada_user;

3. 환경변수 업데이트

DATABASE_URL=postgresql://ivada_user:your_password@localhost/ivada_db
TEST_DATABASE_URL=postgresql://ivada_user:your_password@localhost/ivada_test_db

🚀 서버 실행

1. HTTP 서버 실행 (ngrok 사용)

# 터미널 1: FastAPI 서버
source venv/bin/activate
python run.py

# 터미널 2: ngrok 터널
./ngrok http 8000

2. Socket Mode 실행

source venv/bin/activate
python socket_run.py

3. 실행 확인

• HTTP: http://localhost:8000
• API 문서: http://localhost:8000/docs
• ngrok 모니터링: http://localhost:4040

🧪 테스트

1. API 테스트

# 서버 상태 확인
curl http://localhost:8000/health

# 메시지 처리 테스트
curl -X POST "http://localhost:8000/api/test/message" \
     -H "Content-Type: application/json" \
     -d '{"text": "안녕하세요", "user_id": "test_user"}'

2. Slack 테스트

1. 봇 초대: /invite @Roving
2. 직접 메시지: 안녕하세요 로빙!
3. 멘션 테스트: @Roving 오늘 할 일을 정리해주세요

3. 예상 응답

안녕하세요! 테스트 모드에서 실행 중입니다. 메시지를 받았습니다: '[메시지]'

🐛 문제 해결

Slack 연동 문제

• 봇이 응답하지 않음: Event Subscriptions 설정 확인
• 권한 오류: Bot Token Scopes 재확인
• URL 검증 실패: ngrok URL 및 서버 실행 상태 확인

서버 실행 문제

• 포트 충돌: lsof -i :8000으로 포트 사용 확인
• 의존성 오류: pip install -r requirements.txt 재실행
• 환경변수 오류: .env 파일 경로 및 내용 확인

데이터베이스 연결 문제

• 연결 실패: PostgreSQL 서비스 실행 상태 확인
• 권한 오류: 사용자 권한 재설정
• 인코딩 문제: UTF-8 인코딩 설정 확인

📞 지원

추가 도움이 필요하시면:

• GitHub Issues
• 개발 일지 참조
• Slack API 문서 참조