Deploy a FastAPI app
Uvicorn on $PORT, Python versions, secrets, PostgreSQL and migrations as a release command.
Gregale deploys a FastAPI app from its source: it finds fastapi in your
dependencies, installs them, and starts the app with Uvicorn. What every
framework shares is on Deploy a web framework.
To check an existing repository and verify its exact release through MCP, follow the FastAPI agent quickstart.
Prepare the app
# main.py
from fastapi import FastAPI
app = FastAPI()
@app.get("/healthz")
def healthz():
return {"ok": True}
@app.get("/")
def root():
return {"message": "hello"}
List the server with the app's dependencies, since Gregale starts it with
uvicorn:
# requirements.txt
fastapi
uvicorn
pyproject.toml, Pipfile and setup.py work too; the lockfile picks the
package manager (uv.lock, poetry.lock, Pipfile.lock, else pip).
Gregale looks for the module that creates FastAPI() and infers:
uvicorn main:app --host 0.0.0.0 --port $PORT
If it cannot find one it falls back to app:app and warns. To skip
inference, set the command:
# gregale.yaml
hosting:
start: uvicorn main:app --host 0.0.0.0 --port $PORT
health: /healthz
Keep --host 0.0.0.0 and --port $PORT: Uvicorn's defaults
(127.0.0.1:8000) are unreachable. Start the server directly rather than
through uv run or poetry run; the package manager is not part of the
running app.
For more than one worker process, use Gunicorn with Uvicorn workers and add
gunicorn to the dependencies:
web: gunicorn main:app -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:$PORT --workers 2
Choose the Python version
With no declaration the app builds on Python 3.13. 3.12 in
.python-version or runtime.txt selects Python 3.12. See
Runtime versions for other versions.
Deploy
gregale deploy --dry-run
gregale deploy --name my-api
If the deployment fails:
gregale app health my-api --errors
gregale logs my-api
Configuration and secrets
gregale env set --app my-api API_KEY="$API_KEY"
Values arrive as environment variables (os.environ["API_KEY"]). See
Delivered secrets.
Add PostgreSQL
gregale add postgres --app my-api --region <region>
The connection URL arrives as DATABASE_URL. It goes through a connection
pooler in transaction mode: keep the app's pool small and do not rely on
session state between transactions. With psycopg 3:
import os
from psycopg_pool import ConnectionPool
pool = ConnectionPool(os.environ["DATABASE_URL"], max_size=5)
Run migrations (for example Alembic) as a release command with their own credential, which only the release command receives:
gregale postgres attach my-api-postgres my-api --access migration --env MIGRATION_DATABASE_URL
# Procfile
web: uvicorn main:app --host 0.0.0.0 --port $PORT
release: alembic upgrade head
Point the migration tool at MIGRATION_DATABASE_URL. A failed release
command leaves the previous version serving. See
Managed PostgreSQL.
Spotted a problem on this page? Tell us