[Azure] VS Code + GitHub Actions로 Flask 웹앱 배포하기 (feat. 트러블슈팅)
로컬에서 개발한 Flask 애플리케이션을 마이크로소프트 애저(Azure) Web App에 배포하는 전체 과정을 정리함. VS Code 확장 프로그램과 GitHub Actions를 활용하여 CI/CD 파이프라인까지 구축하는 것이 목표임.
01. 로컬 개발 환경 및 Git 설정
배포 전, 로컬 환경에서 Git 설정과 가상환경 구동이 선행되어야 함.
1) Git 초기 설정 (VS Code)
VS Code 터미널에서 사용자 정보를 설정함. 이 정보는 커밋 내역에 남게 됨.
# 닉네임 설정
git config --global user.name "본인이름"
# 이메일 설정
git config --global user.email "본인이메일@example.com"
# 설정값 확인
git config --global user.name
2) 커밋 및 푸시 (Sync)
VS Code의 소스 제어 탭에서 진행함.
- 변경 사항 Commit (메시지 입력 필수).
- Sync Changes 버튼을 눌러 원격 저장소(GitHub)에 반영.
Tip:
.env파일이나 가상환경 폴더(venvs/) 등은 보안 및 용량 관리를 위해 반드시.gitignore파일에 등록하여 업로드에서 제외해야 함.
3) 로컬 서버 테스트
배포 전 로컬에서 정상 작동하는지 확인.
# 가상환경 진입
./venvs/dataproject/Scripts/activate
# 앱 실행 (app.py가 있는 폴더로 이동 후)
flask run
02. 배포 준비 (Requirements.txt)
Azure 서버가 어떤 라이브러리를 설치해야 하는지 알 수 있도록 명세서를 작성해야 함.
1) 패키지 목록 생성
가상환경이 켜진 상태에서 아래 명령어를 실행함.
# 현재 설치된 라이브러리 목록을 파일로 저장
pip freeze > requirements.txt
2) 필수 패키지 확인
특히 gunicorn은 배포 환경(Linux)에서 Flask를 구동하기 위해 반드시 필요함.
requirements.txt 예시
Flask==3.1.2
gunicorn # << 필수!
psycopg2-binary==2.9.11
python-dotenv==1.2.1
pandas==3.0.0
# ... (기타 의존성)
03. Azure Web App 생성 (VS Code)
Azure 포털에 접속하지 않고 VS Code 확장 프로그램으로 리소스를 생성할 수 있음.
- Azure Tools 설치: VS Code 마켓플레이스에서 'Azure Tools' 검색 및 설치.
- 로그인:
Azure: Sign In을 클릭하여 계정 연동. - Web App 생성:
- App Services 우클릭 > Create New Web App (Advanced) 선택.
- 이름: 유니크한 앱 이름 입력 (예:
3dt026-webapp). - Runtime:
Python 3.13(본인 프로젝트 버전에 맞춤). - OS:
Linux권장. - Resource Group: 기존 그룹 선택하거나 새로 생성.
- Location:
Korea Central(한국 중부). - Pricing Tier: 초기엔
F1(Free) 선택 (추후 트러블슈팅에서B1으로 업그레이드 예정).
04. 환경 변수 및 설정 (중요)
로컬의 .env 파일은 업로드되지 않으므로, Azure 포털에서 직접 환경 변수를 설정해야 함.
1) Application Settings (환경 변수)
- 경로: Azure Portal > 해당 Web App > 설정(Settings) > 환경 변수(Environment variables).
- 추가할 변수:
DB_HOST,DB_PASSWORD,DB_USER등 로컬.env에 있던 내용.SCM_DO_BUILD_DURING_DEPLOYMENT=true(배포 시 빌드 수행, 패키지 설치를 위해 필수).- [트러블슈팅]
SCM_COMMAND_IDLE_TIMEOUT=3600(배포 중 타임아웃 방지). - [트러블슈팅]
WEBSITES_PORT=8000(필요시 포트 명시).
2) 시작 명령 (Startup Command)
Flask의 개발용 서버(flask run)는 배포 환경에 적합하지 않음. gunicorn을 사용해야 함.
- 경로: 구성(Configuration) > 일반 설정(General settings) > 시작 명령(Startup Command).
- 명령어:
gunicorn --bind=0.0.0.0 --timeout 600 app:app
app:app:파일명:Flask객체명형식임.
05. 배포하기 (CI/CD 구축)
방법 A: VS Code에서 직접 배포 (수동)
- VS Code Azure 탭 > Web App 우클릭 > Deploy to Web App.
- 배포 후 Start Streaming Logs를 클릭하여 진행 상황과 에러 로그를 실시간으로 확인 가능.
방법 B: GitHub Actions 연동 (자동화)
코드를 GitHub에 푸시하면 자동으로 배포되도록 설정함.
- Azure Portal > 배포 센터(Deployment Center) 이동.
- 원본(Source):
GitHub선택. - 권한 부여: GitHub 계정 로그인 및 권한 승인.
- 설정: 조직(Organization), 리포지토리(Repository), 브랜치(main) 선택.
- 워크플로우 옵션:
기본 인증(Basic Auth)등 선택 후 저장. - 이후 GitHub의 Actions 탭에서 워크플로우가 생성되고 빌드/배포가 진행되는 것을 볼 수 있음.
06. 💣 트러블슈팅 (Troubleshooting) 모음
배포 과정에서 겪은 오류와 해결 방법 정리.
1. 배포 타임아웃 및 빌드 오류
- 증상: 배포 중 로그가 멈추거나 타임아웃 오류 발생.
- 해결: 환경 변수에
SCM_COMMAND_IDLE_TIMEOUT값을3600(초)으로 설정하여 대기 시간을 늘림.
2. 포트 바인딩 문제 (Application Error)
- 증상: 배포 성공 후 접속 시 "Application Error" 발생. 로그에 "Container didn't respond to HTTP pings on port" 등의 메시지.
- 해결:
- 환경 변수에
PORT또는WEBSITES_PORT를8000으로 지정. - 시작 명령(Startup Command)을 명시적으로 지정:
gunicorn --bind=0.0.0.0 --timeout 600 app:app
3. 할당량 초과 (Quota Exceeded)
- 증상: 배포 혹은 실행 중 CPU/메모리 사용량 초과로 서버 중지.
- 원인: 무료 티어(
F1)는 하루 사용량 제한이 있음. - 해결: Scale Up (App Service Plan) 메뉴에서 요금제를
B1(Basic)으로 업그레이드하여 해결함.
4. 파일명 충돌 (abc.py)
- 증상: 특정 라이브러리 임포트 에러 (
ImportError). - 원인: 프로젝트 내에
abc.py라는 파일이 있었음. 이는 파이썬 표준 라이브러리의abc모듈과 이름이 겹쳐서 충돌을 일으킴. - 해결: 파일 이름을 다른 이름(예:
my_utils.py)으로 변경 (Rename).
제 별명이 감자입니다