FastAPI 프로젝트 환경 설정 및 서버 공유

1. 프로젝트 배경 및 기술 스택 선정

 

2. 서버 환경 구축: Dockerfile 및 Docker Compose 설정

 

 2.1 Dockerfile을 통한 이미지 생성

 

2.2. Docker Compose를 통한 서비스 정의 (docker-compose.yml)

docker-compose.yml은 다중 컨테이너 애플리케이션을 정의하고 실행하는 데 사용됩니다.

여기서 4700번 포트 매핑이 이루어졌습니다.
| 서비스 | 설정 항목 | 설정 값 | 역할 및 진행 내용 | | :--- | :--- | :--- | | web | build: . | Dockerfile을 사용하여 web 서비스 이미지를 빌드합니다. | | web | ports | 4700:8000 | [핵심] 포트 포워딩 설정. 호스트 OS의 4700번으로 들어오는 요청을 web 컨테이너 내부의 8000번 포트로 연결합니다. | | web | command | ... --port 8000 --reload | Uvicorn을 실행하여 컨테이너 내부의 8000번 포트에 바인딩합니다. (외부 포트 4700과는 분리됨). | | db | image | postgres:latest | PostgreSQL 데이터베이스 이미지를 사용합니다. | | db | healthcheck | pg_isready -U user | DB 연결 상태를 주기적으로 확인하여, DB가 완전히 준비될 때까지 web 컨테이너의 시작을 지연시킵니다. | | web | depends_on | condition: service_healthy | db 서비스의 Health Check가 성공했을 때만 web 컨테이너가 시작되도록 보장하여 DB 연결 실패를 방지합니다. |

 

3. 서버 실행 및 포트 포워딩 설정 (UFW 방화벽)

 

3.1. 컨테이너 실행 및 재시작
기존 컨테이너 정리: docker compose down 명령으로 기존의 컨테이너를 중지하고 제거합니다.
새 컨테이너 실행: docker compose up -d --build 명령으로 수정된 설정(4700:8000 포트 매핑)을 적용하여 백그라운드(-d)에서 컨테이너를 빌드 및 실행했습니다.

 

3.2. UFW (Uncomplicated Firewall) 방화벽 설정
로컬 네트워크 팀원들이 4700번 포트로 접속할 수 있도록 방화벽 규칙을 설정했습니다.
4700번 포트 허용: sudo ufw allow 4700/tcp 명령을 통해 호스트 OS의 4700번 TCP 포트에 대한 외부 접근을 허용했습니다.
규칙 적용: sudo ufw reload 명령으로 변경된 방화벽 규칙을 즉시 활성화했습니다.
상태 확인: sudo ufw status 결과 4700/tcp가 ALLOW 상태임을 확인했습니다.

 

4.1 초기 실행 실패 문제 해결 (치명적 오류)

 

초기에는 command 설정에 uvicorn ... --port 4700:8000와 같이 포트 매핑 문법을 사용한 오류가 있었습니다.
오류 원인: Uvicorn은 내부 포트(정수)만 받는데, 4700:8000 문자열이 전달되어 컨테이너가 시작하지 못하고 반복 재시작 (Restarting)되었습니다.

해결: docker compose logs web로 오류를 확인한 후, command를 uvicorn ... --port 8000으로 수정하여 컨테이너 내부 포트만 바인딩하도록 조정했습니다.

 

4.2. 최종 접속 검증
컨테이너 재실행 후, 두 가지 방법을 통해 4700번 포트로의 접속을 검증했습니다.
Docker 로그 확인: docker compose logs web를 통해 Uvicorn이 http://0.0.0.0:8000에서 정상적으로 서버 프로세스를 시작했음을 확인했습니다.
curl 테스트 성공: curl http://192.168.0.180:4700/docs 명령 실행 시 FastAPI Swagger UI의 HTML 코드가 정상적으로 반환되었음을 확인했습니다.