QUICKSTART.md

🚀 빠른 시작 가이드

FastAPI + Streamlit 프로젝트를 5분 안에 실행하는 방법입니다. 해당 가이드에서는 Docker를 사용하는 방법과 Local로 실행하는 2가지 방법을 설명합니다.

• 방법 1: Docker 사용 (추천) 🐳
• 방법 2: 로컬 실행 💻

---

방법 1: Docker 사용 (추천) 🐳

1단계: Docker 설치 확인

docker --version
docker-compose --version

설치가 안 되어 있다면: https://www.docker.com/get-started 을 참고해주세요

2단계: 환경 테스트 (선택사항)

환경이 제대로 설정되어 있는지, 다음 script를 실행해서 확인합니다.

./test_docker.sh

3단계: 프로젝트 실행

옵션 A - Docker Compose 직접 사용:

docker-compose up --build

옵션 B- Docker 이미지별로 실행(비권장):

4단계: 접속

• 🎨 Streamlit: http://localhost:8501
• 🚀 FastAPI: http://localhost:8000
• 📚 API 문서: http://localhost:8000/docs

5단계: 종료

# Ctrl+C 또는
docker-compose down

---

방법 2: 로컬 실행 💻

1단계: 가상환경 생성

python -m venv venv

# Mac/Linux
source venv/bin/activate

# Windows
venv\Scripts\activate

2단계: 의존성 설치

pip install -r backend/requirements.txt
pip install -r frontend/requirements.txt

3단계: 프로젝트 실행

Mac/Linux:

chmod +x run_all.sh
./run_all.sh

Windows:

run_all.bat

또는 개별 실행:

터미널 1 (백엔드):

python run_backend.py

터미널 2 (프론트엔드):

python run_frontend.py

4단계: 접속

• 🎨 Streamlit: http://localhost:8501
• 🚀 FastAPI: http://localhost:8000
• 📚 API 문서: http://localhost:8000/docs

---

📊 사용 예시

1. Streamlit 대시보드에서 사용자 생성

1. http://localhost:8501 접속
2. 사이드바에서 "사용자 관리" 선택
3. "사용자 생성" 탭 클릭
4. 정보 입력:
   • 사용자명: testuser
   • 이메일: test@example.com
   • 비밀번호: password123
5. "생성" 버튼 클릭

2. API로 직접 호출

# 사용자 생성
curl -X POST "http://localhost:8000/api/v1/users/" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "email": "test@example.com",
    "password": "password123"
  }'

# 모든 사용자 조회
curl http://localhost:8000/api/v1/users/

# 아이템 생성
curl -X POST "http://localhost:8000/api/v1/items/?owner_id=1" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "노트북",
    "description": "맥북 프로",
    "price": 2500000
  }'

# 모든 아이템 조회
curl http://localhost:8000/api/v1/items/

3. Swagger UI에서 테스트

1. http://localhost:8000/docs 접속
2. API 엔드포인트 선택
3. "Try it out" 클릭
4. 파라미터 입력
5. "Execute" 실행

---

🆘 문제 해결

만약, 아래 문제가 발생할 경우, 다음을 확인해주세요!!

1. "포트가 이미 사용 중입니다" 오류

# Mac/Linux
lsof -ti:8000 | xargs kill -9
lsof -ti:8501 | xargs kill -9

# 또는 Docker 컨테이너 정리
docker-compose down

2. "API 서버에 연결할 수 없습니다" 오류

1. 백엔드가 실행 중인지 확인
2. http://localhost:8000/health 접속 테스트
3. Docker 사용 시 컨테이너 로그 확인:

   docker-compose logs backend

캐시 문제로 인한 업데이트 오류

코드를 수정해도 내용이 반영되지 않는 문제가 발생할 경우, image build cache를 지우고 실행해보세요.

# Docker 이미지 재빌드
docker-compose build --no-cache
docker-compose up

---

📚 더 알아보기

• 전체 README - 상세한 프로젝트 문서
• Docker 가이드 - Docker 사용법 상세 가이드
• FastAPI 문서
• Streamlit 문서

---

🎉 완료!

이제 FastAPI + Streamlit 프로젝트가 실행되었습니다! 궁금한 점이 있으면 이슈를 등록해주세요. 😊