<div id="readability-page-1" class="page"><div itemprop="articleBody"> <p>FastAPI 관련 라이브러리나 예제 코드들을 살펴보다보면 실행 Dockerfile 파일이 아래와 같이 시작하는 파일들을 많이 만나볼 수 있다.</p> <p>FastAPI를 사용한다면 tiangolo 이름부터 아주 익숙할 것이다. 맞다. 바로 FastAPI를 만든 <a href="https://github.com/tiangolo" target="_blank" rel="noopener noreferrer">Sebastián Ramírez<span> <span>(opens new window)</span></span></a>가 FastAPI용 base docker image다. Python 3.6 이상의 버전들을 모두 제공하고 있으며 <code>-slim</code> (ex. <code>python3.8-slim</code>) 과 같이 Alpine Linux 버전 역시 제공하고 있으니 뭘 좋아하든 골라 사용하기 좋다.</p> <ul><li><strong>GitHub repo</strong>:&nbsp;<a href="https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker" target="_blank" rel="noopener noreferrer">https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker<span> <span>(opens new window)</span></span></a></li> <li><strong>Docker Hub image</strong>:&nbsp;<a href="https://hub.docker.com/r/tiangolo/uvicorn-gunicorn-fastapi/" target="_blank" rel="noopener noreferrer">https://hub.docker.com/r/tiangolo/uvicorn-gunicorn-fastapi/<span> <span>(opens new window)</span></span></a></li></ul> <p>아마 FastAPI를 한번이라도 사용해 본 사람이라면 이미 <code>uvicorn main:app --reload</code> 시작이 아마 익숙할 것이다. 이 베이스 이미지에서는 여기서 하나 더 추가 되었다.</p> <ul><li><a href="https://www.uvicorn.org/" target="_blank" rel="noopener noreferrer">Uvicorn<span> <span>(opens new window)</span></span></a> : lightning-fast "ASGI" server. 비동기 파이썬 웹 서버. 단일 process.</li> <li><a href="https://gunicorn.org/" target="_blank" rel="noopener noreferrer">Gunicorn<span> <span>(opens new window)</span></span></a> : WSGI(Web Server Gateway Interface). 여기서는 여러 Uvicorn 워커 프로세스를 매니지하는 용도로 사용된다.</li></ul> <p>Uvicorn + Gunicorn 로 서버 리소스(CPU 코어 갯수)에 적합한 워커 구성을 해주며 FastAPI가 바로 사용할 수 있는 Base Image가 바로 "uvicorn-gunicorn-fastapi-docker" 이다.</p> <h2 id="쓰면-좋은-경우"><a href="#쓰면-좋은-경우">#</a> 쓰면 좋은 경우</h2> <ul><li>프로세스 수 조정을 크게 신경 쓰지 않아도 되는 간단한 앱.</li> <li>클러스터가 아닌 단일 서버에서 실행하는 경우.</li> <li>단일 서버에 Docker Compose로 배포하여 컨테이너 내에서 Gunicorn + Uvicorn 조합으로 사용하는 경우.</li> <li>프로메테우스와 같은 모니터링 메트릭을 가져오는 경우, 하나의 컨테이너 + 여러 프로세스 조합으로 한번에 사용하는게 간단할 수 있음.</li></ul> <h2 id="안-써도-되는-경우-prod-배포의-경우"><a href="#안-써도-되는-경우-prod-배포의-경우">#</a> 안 써도 되는 경우 (Prod 배포의 경우)</h2> <p>위에서 언급한 바와 같이 편하게 사용하라고 만든 것임으로 꼭 써야하는 것은 아니다. 오히려, 해당 Repo REAME에서부터 <strong>WARNING</strong> 까지 붙혀가며, 꼭 써야하는 것은 아니니 유의 당부를 하고 있다. "그냥 직접 만들어 쓰는게 오히려 나을 수도 있다." 라고 말하고 있는데, 그 큰 이유중의 하나는 worker의 수 때문이다.</p> <p><code>uvicorn-gunicorn-fastapi-docker</code> 는 <a href="https://github.com/tiangolo/uvicorn-gunicorn-docker/blob/master/docker-images/gunicorn_conf.py#L21-L30" target="_blank" rel="noopener noreferrer">내부적으로 자동으로 process와 worker 수를 자동으로 조절해주고 있다.<span> <span>(opens new window)</span></span></a>  CPU 자원 상태를 체크하고 이에 알맞는 값을 계산해준다. 위에서 말한 "쓰면 좋은 경우"에서 반복되는 단일 서버나 단일 컨테이너로 띄울 때 좋은 이유가 여기에 있다. 떠 있는 환경에서 가장 적합한 갯수를 알아서 계산해 줄 테니 우리는 비지니스 로직에만 신경쓰면 된다.</p> <p>하지만 리얼 월드에서는 이 자동 튜닝 부분이 적합하지 않을 수도 있다. Docker를 사용하게 되면 단일로 띄우기 보다는 Kubernetes와 같은 컨테이너 오케스트레이션을 이용하여 클러스터에 여러개의 Pod으로 띄우는 경우가 대다수다. 즉, 클러스터 레벨에서 몇 개의 앱을 띄울 것인가가 관리된다. 이 때 각각의 컨테이너 내에서 Gunicorn + Uvicorn 으로 여러 워커 + 프로세스 매니저를 사용할 경우, 이 리소스 관리가 아주 복잡해 질 수 있다.</p> <p>따라서, 클러스터를 이용한 배포 및 운영을 하고 있다면 단일 Uvicorn process를 사용하는 것을 권장하고 있다. <a href="https://fastapi.tiangolo.com/deployment/docker/#replication-number-of-processes" target="_blank" rel="noopener noreferrer">더 자세한 내용은 공식 문서<span> <span>(opens new window)</span></span></a>에서도 찾아 볼 수 있다.</p> <h2 id="사용-방법"><a href="#사용-방법">#</a> 사용 방법</h2> <p>위 경우 <code>/app/app/main.py</code> 혹은 <code>/app/main.py</code> 에 있는 <code>app</code>을 실행하게 되니 파일 위치를 유의하자.
그 다음 docker build 그리고 run 해준다.</p> <p>제대로 잘 떳다면 <a href="http://localhost:8080/" target="_blank" rel="noopener noreferrer">http://localhost:8080<span> <span>(opens new window)</span></span></a> 에 접속될 것이다.</p> <p>만약 패키지 관리툴 Poetry를 사용한다면 아래와 같이 Poetry 설치 및 패키지 설치를 해주면 된다.</p> <h3 id="다른-dependency들과-함께-docker-compose로-실행하기"><a href="#다른-dependency들과-함께-docker-compose로-실행하기">#</a> 다른 dependency들과 함께 Docker Compose로 실행하기</h3> <p>Default는 <a href="https://github.com/tiangolo/uvicorn-gunicorn-docker/blob/master/docker-images/start.sh" target="_blank" rel="noopener noreferrer">start.sh<span> <span>(opens new window)</span></span></a>로 바로 run 되는 것으로 되어있으나, 개발 할때는  <a href="https://github.com/tiangolo/uvicorn-gunicorn-docker/blob/master/docker-images/start-reload.sh" target="_blank" rel="noopener noreferrer"><code>start-reload.sh</code><span> <span>(opens new window)</span></span></a>을 사용하여 코드 변경이 있을 때 마다 자동으로 리로드 될 수 있도록 하는 것이 편하다. 만약 위처럼 docker-compose가 아닌 그냥 <code>docker run</code> 사용시에는 아래와 같이 사용하면 된다.</p> <ul><li>(주의) reload에서는 Gunicorn으로 뜨지않기 때문에 만일 custom gunicorn 설정 파일을 사용한다면, reload에서는 반영되지 않는다.</li></ul> <h2 id="환경변수"><a href="#환경변수">#</a> 환경변수</h2> <p>기본적인 것들을 많이 제공하면서도 커스텀하게 필요한 부분들도 환경변수로 적절히 넣어줄 수 있다. 코드 폴더 구성이 다르거나, 워커의 수만 변경하고 싶을때, 최대 워커 수를 고정 시키고 싶은 경우 등.</p> <ul><li><code>APP_MODULE</code></li> <li><code>VARIABLE_NAME</code></li> <li><code>APP_MODULE</code></li> <li><code>GUNICORN_CONF</code></li> <li><code>WORKERS_PER_CORE</code></li> <li><code>MAX_WORKERS</code></li> <li><code>WEB_CONCURRENCY</code></li> <li><code>HOST</code></li> <li><code>PORT</code></li> <li><code>BIND</code></li> <li><code>LOG_LEVEL</code></li> <li><code>WORKER_CLASS</code></li> <li><code>TIMEOUT</code></li> <li><code>KEEP_ALIVE</code></li> <li><code>GRACEFUL_TIMEOUT</code></li> <li><code>ACCESS_LOG</code></li> <li><code>ERROR_LOG</code></li> <li><code>GUNICORN_CMD_ARGS</code></li> <li><code>PRE_START_PATH</code></li></ul> <p>자세한 사용 방법은 <a href="https://github.com/tiangolo/uvicorn-gunicorn-docker#environment-variables" target="_blank" rel="noopener noreferrer">여기<span> <span>(opens new window)</span></span></a>서 확인해 볼 수 있다.</p> <h2 id="custom-gunicorn-설정-파일"><a href="#custom-gunicorn-설정-파일">#</a> Custom Gunicorn 설정 파일</h2> <p><a href="https://github.com/tiangolo/uvicorn-gunicorn-docker/blob/master/docker-images/gunicorn_conf.py" target="_blank" rel="noopener noreferrer">기본으로 설정된 Gunicorn 파일이 있다.<span> <span>(opens new window)</span></span></a> 다음과 같은 path에 추가하면 override 되니 필요한 부분이 있으면 커스터마이즈도 가능하다.</p> <ul><li><code>/app/gunicorn_conf.py</code></li> <li><code>/app/app/gunicorn_conf.py</code></li> <li><code>/gunicorn_conf.py</code></li></ul> <h2 id="custom-app-prestart-sh"><a href="#custom-app-prestart-sh">#</a> Custom  <code>/app/prestart.sh</code></h2> <p>app 시작 전, 필요한 작업을 스크립트 처리할 수도 있다. 많이 사용 예로는 Alembic을 이용한 SQL migration 역시도 가능하다.</p> <p>예를 들어, 아래와 같은 스크립트를 <code>./app/prestart.sh</code> 에 만든다. (혹은 <code>PRE_START_PATH</code>로 위치를 변수로 넘겨 줄 수도 있다.)</p> <p>(대략 DB 뜨는 시간)10초를 기다린 후, alembic 커맨드를 실행한다. 그 후 앱이 구동 된다.</p> <h2 id="references"><a href="#references">#</a> References</h2> <ul><li><a href="https://github.com/tiangolo/uvicorn-gunicorn-docker" target="_blank" rel="noopener noreferrer">https://github.com/tiangolo/uvicorn-gunicorn-docker<span> <span>(opens new window)</span></span></a></li></ul></div></div>

Daily Log

FastAPI 관련 라이브러리나 예제 코드들을 살펴보다보면 실행 Dockerfile 파일이 아래와 같이 시작하는 파일들을 많이 만나볼 수 있다.
FROM tiangolo/uvicorn-gunicorn-fastapi
FastAPI를 사용한다면 tiangolo 이름부터 아주 익숙할 것이다. 맞다. 바로 FastAPI를 ...

가장 빠르게 FastAPI를 돌려보자 - uvicorn-gunicorn-fastapi-docker

댓글