GitHub Webhook을 활용한 나만의 자동 배포 시스템 ⑤ Nginx, HTTPS 설정 및 최종 연동

들어가며: 마지막 퍼즐 조각 맞추기

---

---

안녕하세요! 드디어 길었던 시리즈의 마지막 편입니다. 지난 4편까지 우리는 자동 배포 시스템의 이론부터 시작해, FastAPI 웹훅 서버의 핵심 로직을 구현하고 Systemd 서비스로 안정적인 운영 환경까지 구축했습니다.

이번 시리즈의 이전 포스트들은 아래의 링크로 확인할 수 있습니다.

① 왜 직접 구현하는가?

② 전체 아키텍처 및 프로세스 설계

③ 스테이징 서버 환경 설정 및 FastAPI 웹훅 서버 기초 구축

④ 배포 핸들러 상세 및 Systemd 서비스 등록

하지만 아직 한 단계가 남았습니다. 현재 우리의 FastAPI 웹훅 서버는 8000번 포트에서만 작동하고 있으며, HTTPS를 사용하지 않아 보안에 취약합니다. 또한, GitHub는 공개된 도메인과 HTTPS 연결을 강력히 권장합니다.

이번 5편에서는 마지막 퍼즐 조각들을 맞춰 시스템을 완성할 것입니다. Nginx를 리버스 프록시로 설정하여 FastAPI 서버를 외부에 안전하게 노출하고, Let's Encrypt를 통해 무료 HTTPS를 적용한 후, 최종적으로 GitHub 웹훅을 연동하여 자동 배포 시스템을 완성해봅시다.

잠깐, 왜 Apache2가 아닌 Nginx인가요? Apache2와 Nginx는 서버 프로그램 시장을 양분하는 훌륭한 웹 서버들입니다. 하지만 FastAPI와 같은 비동기 웹 프레임워크는 Nginx와 더 좋은 궁합을 보여줍니다. Nginx는 비동기 이벤트 기반으로 설계되어 있어, 높은 동시 접속 환경에서 FastAPI의 비동기적 성능을 최대로 끌어낼 수 있습니다. 이 때문에 FastAPI 커뮤니티에서는 Nginx를 프로덕션 환경의 웹 서버로 강력히 추천하며, 이 글도 Nginx를 중심으로 설명합니다

Nginx 설치 및 리버스 프록시 설정

왜 Nginx를 사용해야 할까?

1. 리버스 프록시: FastAPI와 같은 애플리케이션 서버는 외부 트래픽을 직접 받는 용도가 아닙니다. Nginx는 웹훅 요청을 받아 FastAPI 서버로 안전하게 전달하는 리버스 프록시 역할을 합니다.

2. 보안: Nginx는 다양한 보안 설정과 DDoS 공격 방어 기능을 제공합니다.

3. HTTPS 적용: HTTPS 인증서를 관리하고 적용하는 역할은 Nginx와 같은 웹 서버가 담당합니다.

Nginx 설치 및 설정

스테이징 서버에 SSH로 접속하여 Nginx를 설치합니다. 이 글을 읽으시는 독자분들은 이미 Nginx에 대한 어느정도의 경험과 지식이 있다는 것을 전제로 하여 Nginx의 설치방법, 파일구조나 작동원리에 대한 자세한 설명은 생략하도록 하겠습니다.

sudo apt update
sudo apt install -y nginx
sudo systemctl enable nginx # 재부팅시 자동 실행
sudo systemctl start nginx # nginx 시작
sudo systemctl status nginx # Active 상태 확인

이제 우리의 FastAPI 웹훅 서버로 들어오는 요청을 전달하기 위한 Nginx 설정 파일을 작성합니다. deployer.example.com이라는 도메인을 사용한다고 가정하겠습니다. 아래는 설정의 예시입니다.

#/etc/nginx/sites-available/deployer.example.com

# HTTP 요청을 HTTPS로 308 리디렉션
server {
    listen 80;
    server_name deployer.example.com;
    return 308 https://$host$request_uri;
}

# HTTPS 요청 처리
server {
    listen 443 ssl;
    server_name deployer.example.com;

    # SSL 인증서 경로 설정
    ssl_certificate /etc/letsencrypt/live/deployer.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/deployer.example.com/privkey.pem;
    ssl_session_cache shared:SSL:1m;
    ssl_session_timeout 5m;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_protocols TLSv1.2 TLSv1.3;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_redirect off;
    }
}

• HTTP 80번 포트 설정: server_name이 deployer.example.com인 listen 80 블록은 들어오는 모든 HTTP 요청을 return 308 https://$host$request_uri; 명령을 통해 영구적으로 HTTPS로 리다이렉션합니다.

• HTTPS 443번 포트 설정: listen 443 ssl; 블록은 HTTPS 요청을 처리합니다.

• ssl_certificate & ssl_certificate_key: 이미 Let's Encrypt를 통해 발급받았다고 가정하고 작성되었습니다. 이 블록에서는 발급받은 SSL 인증서와 키 파일의 경로를 지정합니다. 이 경로는 certbot이 인증서를 발급할 때 자동으로 생성해 주는 경로입니다.

• location / 블록: HTTPS로 변환된 요청을 우리의 FastAPI 서버(http://127.0.0.1:8000)로 전달하는 리버스 프록시 설정을 해줍니다.

이 설정 파일로 Nginx를 재시작하면, 이제 모든 웹훅 요청은 안전한 HTTPS로 처리될 것입니다.

# 설정 파일을 sites-enabled 디렉토리로 심볼릭 링크
sudo ln -s /etc/nginx/sites-available/deployer.example.com /etc/nginx/sites-enabled/

# Nginx 설정 파일의 문법 오류를 검사합니다.
sudo nginx -t

# Nginx를 재시작하여 변경 사항을 적용합니다.
sudo systemctl restart nginx

HTTPS 적용 (Let's Encrypt + Certbot)

---

---

GitHub 웹훅은 보안상의 이유로 HTTPS 통신을 강력히 권장합니다. Let's Encrypt는 누구나 무료로 SSL/TLS 인증서를 받을 수 있는 비영리 인증 기관이며, Certbot은 인증서 발급과 갱신을 자동화해주는 훌륭한 도구입니다. 여기서는 설치방법에 대해서는 생략합니다.

성공적으로 완료되면, 브라우저에서 https://deployer.example.com에 접속하여 FastAPI의 API 문서(.../docs)나 / 엔드포인트에 접근해 보세요. Webhook server is running! 메시지를 볼 수 있다면 Nginx와 HTTPS 설정이 성공적으로 완료된 것입니다.

GitHub 웹훅 최종 연동 및 테스트

이제 모든 준비가 끝났습니다. GitHub 저장소에 우리가 구축한 자동 배포 시스템을 연결해 봅시다.

1. GitHub 저장소 접속: 자동 배포를 적용할 프로젝트의 GitHub 저장소로 이동합니다.

2. Webhooks 설정: 상단 메뉴에서 Settings -> 좌측 메뉴에서 Webhooks 를 클릭합니다.

3. 웹훅 추가: Add webhook 버튼을 클릭하고 다음 정보를 입력합니다.

   • Payload URL: Nginx와 HTTPS를 적용한 웹훅 서버의 주소를 입력합니다. (예: https://deployer.example.com/webhook)

   • Content type: application/json을 선택합니다.

   • Secret: 3편에서 ~/projects/webhook_server/.env 파일에 설정했던 GITHUB_WEBHOOK_SECRET의 값을 정확하게 복사해서 붙여넣습니다.

   • Which events would you like to trigger this webhook?: Just the push event를 선택합니다.

   • Active: 체크박스가 활성화되어 있는지 확인합니다.

4. 저장: Add webhook 버튼을 클릭하여 웹훅을 저장합니다.

웹훅이 정상적으로 등록되면, Recent Deliveries 섹션에 초록색 체크 표시가 나타나면서 테스트 요청이 성공적으로 전송된 것을 확인할 수 있습니다.

이제 최종 테스트를 진행해 봅시다.

1. 로컬에서 코드 변경: 프로젝트의 코드를 조금 수정하고 Git에 커밋 하고 푸시를 해봅시다.

2. 상태 확인:

   • GitHub 웹훅 설정 페이지의 Recent Deliveries에서 방금 보낸 푸시에 대한 웹훅이 성공(초록색 체크)했는지 확인합니다.

   • 스테이징 서버에 SSH로 접속하여 sudo journalctl -u github-webhook-deployer.service -f 명령어로 실시간 로그를 확인합니다. Git pull successful, Deployment task finished 등의 메시지가 보인다면 성공입니다.

   • 배포된 Docker 컨테이너의 상태를 확인하여 최신 코드가 반영되었는지 검증합니다.

마무리하며: 자동 배포 시스템 완성!

축하합니다! 로컬 개발 환경에서부터 GitHub, 그리고 자체 구축한 스테이징 서버까지 이어지는 완전한 CI/CD 파이프라인을 성공적으로 구축하셨습니다.

이 시리즈를 통해 우리는 다음을 모두 해냈습니다.

• 왜 직접 웹훅 기반 자동 배포 시스템을 구축해야 하는지 이해했습니다.

• FastAPI를 이용한 웹훅 서버 아키텍처를 설계하고 구현했습니다.

• Systemd를 이용해 서비스를 안정적으로 운영하는 방법을 배웠습니다.

• Nginx와 HTTPS 설정을 통해 보안을 강화했습니다.

• 최종적으로 GitHub와 연동하여 모든 과정을 자동화했습니다.

이제 코드를 푸시하는 순간, 여러분의 손길이 닿지 않아도 서버가 알아서 최신 코드를 반영할 것입니다. 이 시스템을 기반으로 더 복잡한 배포 로직을 추가하거나, 알림 기능을 연동하는 등 자신만의 방식으로 발전시켜 보세요.

긴 여정 함께해 주셔서 감사합니다!