docker-origin

React + TypeScript + FastAPI + PostgreSQL + pgvector 기반 AI 활용 예제 프로젝트

개요

이 저장소는 다음 기술 스택을 사용하는 예제 애플리케이션입니다.

• 프론트엔드: React + TypeScript + Vite
• 백엔드: FastAPI + Uvicorn
• 데이터베이스: PostgreSQL
• 벡터 검색: pgvector
• 전체 환경: Docker 컨테이너

폴더 구조

• backend/
  • requirements.txt: Python 패키지 목록
  • app/main.py: FastAPI 서버 진입점 및 기본 API
• frontend/
  • package.json: 프론트엔드 의존성 및 실행 스크립트
  • src/: React 앱 소스 코드
• db/
  • init.sql: PostgreSQL 초기화 SQL (pgvector 확장 및 documents 테이블 생성)
• Dockerfile: Docker 컨테이너 환경 설정
• start.sh: PostgreSQL 시작, DB 초기화, 백엔드/프론트엔드 자동 실행

start.sh 역할

start.sh는 컨테이너 실행 시 자동으로 호출되며 다음 작업을 수행합니다.

1. PostgreSQL 클러스터가 실행 중인지 확인하고 없으면 시작합니다.
2. 데이터베이스 연결 준비가 될 때까지 대기합니다.
3. POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB 환경 변수를 기반으로 사용자와 데이터베이스를 생성합니다.
4. db/init.sql을 실행하여 vector 확장과 documents 테이블을 초기화합니다.
5. 기존 uvicorn 또는 vite 프로세스를 종료합니다.
6. FastAPI 백엔드 서버를 uvicorn으로 실행합니다.
7. React 프론트엔드 개발 서버를 npm run dev로 실행합니다.

주요 기능

현재 프로젝트는 다음 기본 기능을 갖습니다.

• FastAPI 서버 기본 라우트
  • /: FastAPI is running
  • /health: 상태 확인용 헬스체크
  • /api/ping: pong from FastAPI
• PostgreSQL 데이터베이스 초기화
  • vector 확장 설치
  • documents 테이블 생성
  • content, embedding, created_at 필드를 가진 구조
• React + Vite 기반 기본 UI
  • src/App.tsx에 HMR(Hot Module Replacement) 카운터 예제가 포함됨

기술 스택

• Docker 기반 Linux 컨테이너
• Ubuntu 24.04
• Python 3 + FastAPI + Uvicorn
• React 19 + TypeScript + Vite
• PostgreSQL 16
• pgvector
• SQLAlchemy, psycopg[binary], langchain 등

백엔드 의존성

backend/requirements.txt에 포함된 주요 라이브러리:

• fastapi
• uvicorn[standard]
• python-dotenv
• pydantic-settings
• psycopg[binary]
• sqlalchemy
• pgvector
• langchain
• langchain-openai
• langchain-community
• langgraph
• mcp
• httpx
• pytest
• ruff

실행 방법

1. 이미지 빌드

docker build -t docker-origin .

2. 컨테이너 실행

docker run --rm -p 5173:5173 -p 8000:8000 -p 5432:5432 docker-origin

3. 접속

• 프론트엔드: http://localhost:5173
• 백엔드: http://localhost:8000
• 백엔드 헬스 체크: http://localhost:8000/health

환경 변수

start.sh에서 기본값으로 다음 변수를 사용합니다.

• POSTGRES_USER: 기본값 app
• POSTGRES_PASSWORD: 기본값 1q2w3e4r!
• POSTGRES_DB: 기본값 ai_app
• BACKEND_PORT: 기본값 8000
• FRONTEND_PORT: 기본값 5173

Docker 실행 시 환경 변수를 덮어쓸 수 있습니다.

docker run --rm -p 5173:5173 -p 8000:8000 -p 5432:5432 \
  -e POSTGRES_USER=myuser \
  -e POSTGRES_PASSWORD=mypassword \
  -e POSTGRES_DB=mydb \
  docker-origin

로컬 개발

백엔드

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

프론트엔드

cd frontend
npm install
npm run dev -- --host 0.0.0.0 --port 5173

참고

• db/init.sql은 PostgreSQL vector 확장을 생성하고 documents 테이블을 구성합니다.
• 현재 프론트엔드 앱은 기본 Vite 템플릿 상태로, AI 기능 통합을 위한 확장이 필요합니다.
• 백엔드는 기본 API만 포함되어 있으며, 실제 AI 문서 임베딩/검색 기능은 추가 개발이 필요합니다.

start.sh 실행 및 종료 방법

1. 직접 실행

start.sh는 Docker 이미지 안에서 /app/start.sh로 실행되도록 복사됩니다. 컨테이너 내부에서 직접 실행하려면 다음 명령을 사용합니다.

bash /app/start.sh

실행 권한이 있는 상태라면 다음처럼 실행할 수도 있습니다.

/app/start.sh

현재 스크립트는 /app/backend, /app/frontend, /app/db/init.sql 경로를 사용하므로 일반 호스트 경로가 아니라 컨테이너 내부에서 실행하는 것을 기준으로 합니다.

2. 백그라운드 실행

터미널을 닫아도 계속 실행하려면 nohup과 &를 사용합니다.

nohup bash /app/start.sh > /app/app.log 2>&1 &

start.sh는 실행될 때 다음 PID 파일을 자동으로 기록합니다.

• /app/start.pid: start.sh PID
• /app/backend.pid: FastAPI 백엔드 PID
• /app/frontend.pid: React/Vite 프론트엔드 PID

실행 로그는 다음 명령으로 확인합니다.

tail -f /app/app.log

3. 백그라운드 실행 종료

start.sh가 기록한 PID를 사용해 종료합니다.

kill $(cat /app/start.pid)

start.sh는 종료 신호를 받으면 /app/backend.pid, /app/frontend.pid에 기록된 백엔드와 프론트엔드 프로세스도 함께 정리합니다.

정상 종료가 되지 않을 때는 다음처럼 강제 종료할 수 있습니다.

kill -9 $(cat /app/start.pid)
kill -9 $(cat /app/backend.pid)
kill -9 $(cat /app/frontend.pid)

PID 파일이 없거나 프로세스가 남아 있는지 확실하지 않다면 다음 명령으로 관련 프로세스를 강제 종료합니다.

pkill -9 -f "bash /app/start.sh"
pkill -9 -f "uvicorn app.main:app"
pkill -9 -f "vite"
pkill -9 -f "npm run dev"