FastAPI + Streamlit 프로젝트

FastAPI 백엔드와 Streamlit 프론트엔드를 결합한 풀스택 웹 애플리케이션 템플릿입니다.
Docker Compose를 사용하여 간편하게 배포할 수 있도록 만들었습니다.

📁 프로젝트 구조

fastaapi_w_streamlit/
├── backend/                 # FastAPI 백엔드
│   ├── __init__.py
│   ├── main.py             # FastAPI 메인 애플리케이션
│   ├── config.py           # 설정 관리
│   ├── models.py           # Pydantic 데이터 모델
│   ├── routers/            # API 라우터
│   │   ├── __init__.py
│   │   ├── users.py        # 사용자 관련 API
│   │   └── items.py        # 아이템 관련 API
│   ├── Dockerfile          # 백엔드 Docker 이미지
│   └── requirements.txt    # 백엔드 의존성
├── frontend/               # Streamlit 프론트엔드
│   ├── __init__.py
│   ├── app.py             # Streamlit 메인 애플리케이션
│   ├── Dockerfile         # 프론트엔드 Docker 이미지
│   └── requirements.txt   # 프론트엔드 의존성
├── docker-compose.yml     # Docker Compose 설정
├── .dockerignore          # Docker 제외 파일
├── run_backend.py         # 백엔드 실행 스크립트 (로컬)
├── run_frontend.py        # 프론트엔드 실행 스크립트 (로컬)
├── run_all.sh             # 통합 실행 스크립트 (Mac/Linux)
├── run_all.bat            # 통합 실행 스크립트 (Windows)
├── .env.example           # 환경 변수 예시
├── .gitignore             # Git 제외 파일 목록
└── README.md              # 프로젝트 문서

🚀 주요 기능

Backend (FastAPI)

✅ RESTful API 설계
✅ 모듈화된 라우터 구조
✅ Pydantic을 통한 데이터 검증
✅ CORS 미들웨어 설정
✅ 자동 API 문서 생성 (Swagger UI, ReDoc)
✅ 환경 변수 기반 설정
✅ 헬스 체크 엔드포인트
✅ Docker 컨테이너화

Frontend (Streamlit)

✅ 직관적인 웹 인터페이스
✅ 사용자 관리 (CRUD)
✅ 아이템 관리 (CRUD)
✅ 실시간 데이터 조회
✅ API 테스트 도구
✅ 반응형 대시보드
✅ Docker 컨테이너화

🐳 Docker로 실행 (추천)

Docker가 설치되어 있다면 가장 간단하게 실행할 수 있습니다.

사전 요구사항

Docker 설치 (https://www.docker.com/get-started)
Docker Compose 설치 (Docker Desktop에 포함)

실행 방법

1. 컨테이너 빌드 및 실행:

docker-compose up --build

2. 백그라운드 실행:

docker-compose up -d

3. 로그 확인:

docker-compose logs -f

4. 컨테이너 중지:

docker-compose down

5. 컨테이너 중지 및 볼륨 삭제:

docker-compose down -v

‼ Docker Compose 특징

자동 네트워크 구성: fastapi_streamlit_network 브리지 네트워크로 백엔드와 프론트엔드 연결
헬스체크: 프론트엔드는 백엔드 서비스의 상태를 모니터링하고 백엔드가 준비된 후 시작
환경 변수: Docker Compose에서 환경 변수를 통해 설정 관리
자동 재시작: 컨테이너 장애 시 자동으로 재시작 (restart: unless-stopped)

서비스 개별 제어 (참고)

# 백엔드만 재시작
docker-compose restart backend

# 프론트엔드만 재시작
docker-compose restart frontend

# 특정 서비스의 로그 확인
docker-compose logs -f backend
docker-compose logs -f frontend

# 컨테이너 상태 확인
docker-compose ps

💻 로컬 개발 환경 실행

Docker 없이 로컬에서 직접 실행할 수도 있습니다.

1. 가상환경 생성 및 활성화

python -m venv venv

# Mac/Linux
source venv/bin/activate

# Windows
venv\Scripts\activate

2. 의존성 설치

백엔드:

cd backend
pip install -r requirements.txt
cd ..

프론트엔드:

cd frontend
pip install -r requirements.txt
cd ..

3. 실행

방법 1: 통합 실행 (추천)

Mac/Linux:

chmod +x run_all.sh
./run_all.sh

Windows:

run_all.bat

방법 2: 개별 실행

터미널 1 - 백엔드:

python run_backend.py

터미널 2 - 프론트엔드:

python run_frontend.py

방법 3: 직접 실행

백엔드:

cd backend
python main.py
# 또는
uvicorn main:app --reload --host 0.0.0.0 --port 8000

프론트엔드:

streamlit run frontend/app.py

🌐 접속 URL

서버 실행 후 다음 URL에서 접속할 수 있습니다:

Docker 환경

Streamlit 대시보드: http://localhost:8501
FastAPI 서버: http://localhost:8000
Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc
헬스 체크: http://localhost:8000/health

로컬 환경

Streamlit 대시보드: http://localhost:8501
FastAPI 서버: http://localhost:8000
Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc
헬스 체크: http://localhost:8000/health

📚 API 엔드포인트

기본 엔드포인트

GET / - 루트 엔드포인트
GET /health - 헬스 체크

사용자 API (`/api/v1/users`)

Method	Endpoint	Description
POST	`/api/v1/users/`	사용자 생성
GET	`/api/v1/users/`	모든 사용자 조회
GET	`/api/v1/users/{user_id}`	특정 사용자 조회
DELETE	`/api/v1/users/{user_id}`	사용자 삭제

아이템 API (`/api/v1/items`)

Method	Endpoint	Description
POST	`/api/v1/items/`	아이템 생성
GET	`/api/v1/items/`	모든 아이템 조회
GET	`/api/v1/items/{item_id}`	특정 아이템 조회
PUT	`/api/v1/items/{item_id}`	아이템 수정
DELETE	`/api/v1/items/{item_id}`	아이템 삭제

🎨 Streamlit 기능

1. 홈 대시보드

API 서버 상태 확인
주요 기능 소개
유용한 링크 모음

2. 사용자 관리

조회: 전체 사용자 목록 확인
생성: 새로운 사용자 등록
삭제: 사용자 삭제

3. 아이템 관리

조회: 전체 아이템 목록 확인 (페이지네이션 지원)
생성: 새로운 아이템 등록
수정: 아이템 정보 수정
삭제: 아이템 삭제

4. API 테스트

직접 API 엔드포인트 테스트
HTTP 메서드 선택 (GET, POST, PUT, DELETE)
요청 본문 편집
응답 결과 확인

💡 사용 예시

1. 사용자 생성

# API 요청
POST http://localhost:8000/api/v1/users/
{
  "username": "johndoe",
  "email": "john@example.com",
  "password": "password123"
}

2. 아이템 생성

# API 요청
POST http://localhost:8000/api/v1/items/?owner_id=1
{
  "title": "노트북",
  "description": "맥북 프로 16인치",
  "price": 2500000
}

3. Streamlit에서 사용

브라우저에서 http://localhost:8501 접속
사이드바에서 "사용자 관리" 선택
"사용자 생성" 탭에서 정보 입력
"생성" 버튼 클릭

🔧 Docker 네트워크 구성

프로젝트는 fastapi_streamlit_network라는 커스텀 브리지 네트워크를 사용합니다:

Backend 서비스: 컨테이너명 fastapi_backend, 포트 8000
Frontend 서비스: 컨테이너명 streamlit_frontend, 포트 8501
내부 통신: 프론트엔드는 http://backend:8000으로 백엔드 API 호출
외부 접근: 호스트에서는 http://localhost:8000, http://localhost:8501로 접근

환경 변수

Docker Compose에서 설정되는 환경 변수:

Backend:

PROJECT_NAME=FastAPI Template
VERSION=1.0.0
DEBUG=True
HOST=0.0.0.0
PORT=8000

Frontend:

API_BASE_URL=http://backend:8000/api/v1
API_HOST=http://backend:8000

🛠️ 기술 스택

Backend

FastAPI: 고성능 웹 프레임워크
Uvicorn: ASGI 서버
Pydantic: 데이터 검증

Frontend

Streamlit: 데이터 앱 프레임워크
Requests: HTTP 클라이언트
Pandas: 데이터 처리

DevOps

Docker: 컨테이너화
Docker Compose: 멀티 컨테이너 오케스트레이션

🐛 트러블슈팅

Docker 관련 트러블슈팅은 Docker_Guide.md 문서를 참고하세요.

🔧 개발 시 유의사항

현재는 메모리 기반의 임시 데이터베이스를 사용합니다
서버 재시작 시 데이터가 초기화됩니다
실제 운영 환경에서는 PostgreSQL, MySQL 등의 데이터베이스 연결이 필요합니다
비밀번호는 반드시 해싱하여 저장해야 합니다
인증/인가 시스템 구현이 필요합니다

📈 다음 단계

프로젝트를 확장하려면 다음을 고려하세요:

데이터베이스 연결
- PostgreSQL, MySQL, MongoDB 등
- SQLAlchemy ORM 적용
- Docker Compose에 데이터베이스 서비스 추가
인증/인가
- JWT 토큰 기반 인증
- OAuth2 소셜 로그인
- 세션 관리
고급 기능
- 파일 업로드/다운로드
- 실시간 알림 (WebSocket)
- 데이터 시각화 (차트, 그래프)
- Redis 캐싱
배포
- Docker Hub에 이미지 푸시
- Kubernetes 오케스트레이션
- CI/CD 파이프라인 (GitHub Actions)
- 클라우드 배포 (AWS ECS, GCP Cloud Run, Azure Container Instances)
테스트
- 단위 테스트 (pytest)
- 통합 테스트
- E2E 테스트
- Docker 환경에서 테스트 실행
모니터링
- 로깅 시스템 (ELK Stack)
- 에러 추적 (Sentry)
- 성능 모니터링 (Prometheus + Grafana)
- 컨테이너 모니터링
보안
- HTTPS/SSL 인증서
- 환경 변수 암호화
- Docker 시크릿 관리
- 보안 취약점 스캔

🤝 기여

이슈나 풀 리퀘스트는 언제든 환영합니다!

📄 라이선스

MIT License

📞 문의

질문이나 제안사항이 있으시면 이슈를 등록해주세요.

Happy Coding! 🚀🐳

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
backend		backend
frontend		frontend
.dockerignore		.dockerignore
.gitignore		.gitignore
DOCKER_GUIDE.md		DOCKER_GUIDE.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
docker-compose.yml		docker-compose.yml
run_all.sh		run_all.sh
run_backend.py		run_backend.py
run_frontend.py		run_frontend.py
test_docker.sh		test_docker.sh

nonegom/fastapi-streamlit-boilerplate

Folders and files

Latest commit

History

Repository files navigation