Python 배포

Python 프로젝트는 시작 명령을 못 찾아 실패하는 경우가 가장 많습니다. 빌드 시스템이 Django 말고는 프레임워크를 자동으로 알아보지 못하기 때문입니다.

가장 흔한 실패

requirements.txt 만 넣고 올리면 빌드는 되는데 서버가 안 뜹니다. 빌드 시스템이 기본값으로 python main.py 를 실행하는데, FastAPI·Flask 프로젝트에는 그걸 받아 줄 코드가 없기 때문입니다.

해결: Procfile 한 줄

zip 루트에 Procfile 이라는 확장자 없는 파일을 만들고 시작 명령을 적으면 됩니다.

• Procfile
• requirements.txt
• main.py

FastAPI

Procfile

web: uvicorn main:app --host 0.0.0.0 --port ${PORT:-3000}

requirements.txt

fastapi
uvicorn[standard]

main.py 안의 FastAPI 인스턴스 이름이 app 이 아니면 main:앱이름 으로 바꾸세요. 파일이 server.py 라면 server:app 입니다.

Flask

Procfile

web: gunicorn app:app --bind 0.0.0.0:${PORT:-3000}

requirements.txt

flask
gunicorn

app.py 안의 Flask 인스턴스가 app 인 경우입니다. 개발용 flask run 은 쓰지 마세요.

Django

Procfile

web: python manage.py migrate && gunicorn 프로젝트이름.wsgi --bind 0.0.0.0:${PORT:-3000}

requirements.txt

django
gunicorn

settings.py 에서 ALLOWED_HOSTS 를 반드시 열어야 합니다.

settings.py

ALLOWED_HOSTS = ["*"]      # 해커톤 기간 한정

Streamlit

Procfile

web: streamlit run app.py --server.address 0.0.0.0 --server.port ${PORT:-3000} --server.headless true

requirements.txt

streamlit

--server.headless true 를 빼면 브라우저를 띄우려다 멈춥니다.

Procfile 없이 하려면

main.py 를 직접 실행되게 만들어도 됩니다. 기본 시작 명령이 python main.py 이므로 이 방법도 동작합니다.

main.py

import os
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def root():
    return {"hello": "world"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))

팁

둘 중 하나만 하면 됩니다. Procfile 쪽을 권합니다 — 파일명이나 프레임워크가 바뀌어도 한 줄만 고치면 되고, 개발할 때 쓰는 실행 방식과 배포를 분리할 수 있습니다.

체크리스트

1. requirements.txt 가 zip 루트에 있는가
2. Procfile 에 시작 명령이 있는가 (또는 main.py 에 실행 블록)
3. 호스트가 0.0.0.0 인가 — 127.0.0.1 이면 접속이 안 됩니다
4. 포트가 PORT 환경변수 또는 3000 인가
5. .venv 를 zip 에 넣지 않았는가 (넣어도 서버가 지웁니다)

의존성 적는 법

설치한 패키지가 빠지면 빌드가 실패합니다. 가상환경에서 이렇게 뽑으세요.

pip freeze > requirements.txt

poetry 를 쓴다면 pyproject.toml 과 poetry.lock 을 그대로 올리면 됩니다.

데이터베이스 연결

포털에서 만든 DB 의 주소는 환경변수로 들어옵니다.

import os
DATABASE_URL = os.environ["DATABASE_URL"]      # postgresql://...

SQLAlchemy

from sqlalchemy import create_engine
engine = create_engine(os.environ["DATABASE_URL"])

Django settings.py

import dj_database_url, os
DATABASES = {"default": dj_database_url.parse(os.environ["DATABASE_URL"])}

자세한 내용은 데이터베이스 를 보세요.

Python 버전 지정

기본값이 아닌 버전이 필요하면 zip 루트에 .python-version 을 넣으세요.

.python-version

3.12