[python] Fastapi 애플리케이션 exe 파일로 배포하기

개요

웹 서비스를 코드 공개 없이 외부에서 실행할 수 있도록 exe 파일로 변환하려 함

확인

Fastapi 서버는 python으로 작성되어 있으므로 pyinstaller 를 사용하여 실행 파일을 패키징하려 함

진행

1. main.py 에서 if __name__ == "__main__": 블록으로 실행되는 uvicorn 분리하기

• 이유
  • pyinstaller는 application을 패키징할 때 model import 순서와 참조 방식에 영향을 받을 수 있다.
  • if __name__ == "__main__": 블록을 정상적으로 인식하지 못해서 ASGI 서버(즉, uvicorn)를 실행하지 못한다.
• 진행
  • main.py 에서는 단순히 Fastapi 애플리케이션을 정의하는 역할만 하고, run_server.py에서 main.py를 module로 import하여 app을 실행한다.

변경 전

main.py

import uvicorn
from fastapi import FastAPI, Request
from fastapi.staticfiles import StaticFiles
from fastapi.templating import Jinja2Templates
from fastapi.responses import HTMLResponse, JSONResponse
from fastapi.middleware.cors import CORSMiddleware
from api.api import api_router

app = FastAPI(title="fastapi_app", openapi_url="/api/v1/openapi.json")
app.include_router(api_router)
app.mount("/static", StaticFiles(directory="static"), name="static")

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

templates = Jinja2Templates(directory="templates")

@app.get("/", tags=["root"], response_class=HTMLResponse)
async def read_root(request: Request):
    return templates.TemplateResponse("index.html", {"request": request})

if __name__ == "__main__":
    uvicorn.run("main:app", host='0.0.0.0', port=8000)

 

변경 후

main.py

from fastapi import FastAPI, Request
from fastapi.staticfiles import StaticFiles
from fastapi.templating import Jinja2Templates
from fastapi.responses import HTMLResponse, JSONResponse
from fastapi.middleware.cors import CORSMiddleware
from api.api import api_router

app = FastAPI(title="fastapi_app", openapi_url="/api/v1/openapi.json")
app.include_router(api_router)
app.mount("/static", StaticFiles(directory="static"), name="static")

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

templates = Jinja2Templates(directory="templates")

@app.get("/", tags=["root"], response_class=HTMLResponse)
async def read_root(request: Request):
    return templates.TemplateResponse("index.html", {"request": request})

 

run_server.py

from main import app

if __name__ == "__main__":
    import asyncio
    from hypercorn.config import Config
    from hypercorn.asyncio import serve

    config = Config()
    config.bind = ["0.0.0.0:8000"]

    asyncio.run(serve(app, config))

 

✅ uvicorn.run()을 사용하지 않고 asyncio.run() 으로 실행 시켰다.

 

→ uvicorn.run() 는 자체적으로 이벤트 루프를 생성하고 관리한다. 그러나 이와는 별개로 pyinstaller 로 패키징할 때 asyncio 의 이벤트 루프가 중복되어 발생하는 문제가 발생한다. (특히, windows에서는 이러한 충돌이 발생할 가능성이 높다.)

 

→ uvicorn.run()는 비동기 환경에서 동기적으로 호출되므로, 내부적으로 이벤트 루프를 시작하고 이를 동기 방식으로 실행시키려고 한다. 하지만 asyncio.run()은 이벤트 루프를 직접 제어하기 때문에 기본적으로 이벤트 루프가 없는 환경에서 사용하도록 설계되어 있다. asyncio.run을 통해 명시적으로 이벤트 루프를 생성하여 비동기 서버를 실행하면, 충돌 없이 더 안정적으로 작동할 있다!

 

2. 실행 파일에서 static , templates 폴더 경로 설정

HTML 템플릿, CSS, JavaScript와 같은 정적 리소스를 포함하는 static과 templates 폴더 FastAPI가 이 폴더들을 특정 경로에서 찾는다. PyInstaller로 패키징할 때는 실행 파일이 임시 디렉토리에서 실행되므로, static 및 templates 폴더의 위치를 동적으로 설정해 줘야 한다.

 

변경 전

# static
app.mount("/static", StaticFiles(directory="static"), name="static")

# templates
templates = Jinja2Templates(directory="templates")

 

변경 후

# PyInstaller 환경에서 실행 중인 경우의 경로 설정
if getattr(sys, 'frozen', False):
    base_dir = sys._MEIPASS  # PyInstaller가 설정하는 임시 폴더 경로
else:
    base_dir = os.path.dirname(os.path.abspath(__file__))

# static
app.mount("/static", StaticFiles(directory=os.path.join(base_dir, "static")), name="static")

# templates
templates = Jinja2Templates(directory=os.path.join(base_dir, "templates"))

 

✅ 추가로 참조하는 파일이 있으면 동일하게 경로를 추가해준다.

→ json 파일을 참조하는 부분이 있어서 동일하게 경로를 추가해주었다

if getattr(sys, 'frozen', False):
    base_dir = sys._MEIPASS
else:
    base_dir = os.path.dirname(os.path.abspath(__file__))

json_file_path = os.path.join(base_dir, "projects.json")

 

3. pyinstaller 실행

1. pyinstaller 설치해준다.

pip3 install pyinstaller

 

2. app을 실행시키는 run_server.py 와 동일한 위치에서 아래의 명령어를 실행한다.

- MacOS : --add-data 부분에 ":" 사용

pyinstaller --onefile --name fastapi_app --add-data "static:static" --add-data "templates:templates" --add-data "projects.json:." run_server.py

 

- Windows  : --add-data 부분에 ";" 사용

pyinstaller --onefile --name fastapi_app --add-data "static;static" --add-data "templates;templates" --add-data "projects.json;." run_server.py

 

성공적으로 실행이 완료되면 2개의 폴더(build, dist), 1개의 spec 파일(fastapi_app.spec)이 생성된다.

1. build
   1. build 폴더는 패키징 과정에서 발생하는 임시 파일을 저장한다.
   2. 패키징이 끝난 후에는 build 폴더가 필요 없으므로 삭제해도 무방하다.
2. dist
   1. dist 폴더는 최종 패키징된 실행 파일을 저장하는 위치
   2. --onefile 옵션을 사용하지 않은 경우: dist 폴더에 메인 실행 파일과 함께 모든 의존성이 포함된 하위 폴더가 생성된다.
   3. --onefile 옵션을 사용한 경우: dist 폴더에 단일 .exe 파일이 생성된다.
   4. 이 폴더는 최종 결과물이므로, exe 파일을 다른 위치에 복사하여 사용하면 된다.
3. .spec 파일
   1. .spec 파일은 PyInstaller의 설정 파일로, 패키징 과정에서 PyInstaller가 사용할 설정을 포함한다.
   2. --add-data 옵션으로 추가했던 파일들, --hidden-import으로 숨겨진 임포트를 추가했던 정보 등이 이 파일에 저장된다.
   3. .spec 파일을 수정하여 패키징 세부 설정을 변경하고, 이 파일을 사용해 다시 빌드할 수 있다.

pyinstaller fastapi_app.spec

 

4. 생성된 exe 파일 실행

1. 생성된 파일을 더블 클릭하여 실행한다.

 

2. http://0.0.0.0:8000 으로 서비스가 올라감을 확인할 수 있다.

 

3. 서비스가 잘 운영됨을 확인할 수 있다.

 

 

 

📌 MacOS에서 생성한 exe 파일은 windows에서 실행이 되지 않는다. windows에서 실행할 exe 파일은 windows에서 생성해야한다.

 

📌 windows 에서 pyinstaller 실행 시 유의할 점 2가지

1. pyinstaller는 Python의 Scripts 디렉토리에 설치된다. 이 경로가 Windows 환경 변수 PATH에 추가되지 않은 경우, pyinstaller 명령어를 인식하지 못할 수 있다.
   1. Python Scripts 경로 확인하고 Windows 환경 변수에 추가한다.
   2. 제어판 > 시스템 > 고급 시스템 설정 > 환경 변수로 이동 → PATH 변수를 찾아 편집한 후, C:\Users\YourUsername\AppData\Local\Programs\Python\Python39\Scripts 경로를 새 줄로 추가하고 저장
2. cmd 또는 PowerShell 을 관리자 권한으로 실행시켜서 pyinstaller를 실행한다.
   1. Windows에서 관리자 권한이 필요할 수 있다.