Deploy FastAPI on a VPS: the complete production guide

FastAPI draws all its performance from the asynchronous ASGI model: persistent WebSocket connections, response streaming, and concurrent calls to other services. Serverless platforms often cut long-lived connections and bill every request, which penalizes a high-throughput or real-time API. On a VPS, you run Uvicorn driven by Gunicorn with as many workers as cores, you keep connections open as long as needed, and you place Nginx at the front for TLS and buffering. You also control the connection pool to PostgreSQL and the Redis cache, two essential levers as load grows — the throughput actually sustained is measured against your own traffic.

A FastAPI API is lightweight: 1 vCPU and 1 GB of RAM are enough to start, but aim for 2 vCPU and 2 GB as soon as you add a database and a cache on the same VPS. For sustained load (>100 req/s), plan for at least 4 vCPU and 4 GB.

Recommended versions in 2025: Python 3.11+ (3.12 for maximum performance), FastAPI 0.115+ (full Pydantic v2 support and Python 3.10+ annotations), Uvicorn 0.30+ (event loop stability fixes). Install via Docker with the python:3.12-slim image, or from the official repository with pip install fastapi[standard]>=0.115 uvicorn[standard]>=0.30 gunicorn>=22.0.

On the infrastructure side: Docker Engine 24+, Docker Compose v2 (integrated plugin, docker compose), Nginx 1.24+ as reverse proxy, and a domain pointed to the VPS for the TLS certificate. Ubuntu 22.04/24.04 LTS is the recommended base; Debian 12 also works.

For FastAPI applications in production, asyncpg combined with SQLAlchemy 2.x (async mode) offers an excellent balance of performance and maintainability. Configure the connection pool according to expected load:

from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from sqlalchemy.orm import sessionmaker

engine = create_async_engine(
    DATABASE_URL,
    pool_size=10,        # persistent connections
    max_overflow=20,     # additional connections under peak
    pool_timeout=30,     # seconds before error
    pool_recycle=1800,   # recycle after 30 min to avoid PostgreSQL timeouts
    echo=False,
)

AsyncSessionLocal = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)

Inject the session into your routes via a FastAPI dependency:

async def get_db():
    async with AsyncSessionLocal() as session:
        yield session

For schema migrations, Alembic is the standard tool. Initialize it in your project (alembic init migrations) then configure alembic.ini to point to your DATABASE_URL. Essential commands:

# Generate a migration from your SQLAlchemy models
alembic revision --autogenerate -m "add_users_table"

# Apply pending migrations
alembic upgrade head

# Check current state
alembic current

In production, run alembic upgrade head before starting the API — add it as an init command in your docker-compose.yml or in a separate startup script. Never run migrations from multiple instances simultaneously.

A simple GitHub Actions pipeline is sufficient for most FastAPI projects: build the image, push to a registry, and deploy to the VPS via SSH with zero-downtime.

# .github/workflows/deploy.yml
name: Deploy FastAPI
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build & push Docker image
        run: |
          docker build -t ghcr.io/${{ github.repository }}:${{ github.sha }} .
          echo ${{ secrets.GITHUB_TOKEN }} | docker login ghcr.io -u ${{ github.actor }} --password-stdin
          docker push ghcr.io/${{ github.repository }}:${{ github.sha }}

      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.VPS_HOST }}
          username: deploy
          key: ${{ secrets.VPS_SSH_KEY }}
          script: |
            cd /opt/myapp
            export IMAGE_TAG=${{ github.sha }}
            docker compose pull api
            docker compose up -d --no-deps api
            docker compose exec api alembic upgrade head

The --no-deps flag on docker compose up restarts only the api container without touching db or redis, ensuring zero-downtime for third-party services. For more robust deployments with instant rollback, tag your images with the commit SHA and keep the last 3 versions locally.

Access Uvicorn logs directly via Docker:

# Real-time logs
docker compose logs -f api

# Last 100 lines
docker compose logs --tail=100 api

For structured JSON logs (indexable by an aggregator like Loki or Elasticsearch), replace the standard Python logger with loguru or structlog:

from loguru import logger
import sys

logger.remove()
logger.add(sys.stdout, format="{time} {level} {message}", serialize=True)

@app.middleware("http")
async def log_requests(request, call_next):
    logger.info("request", method=request.method, url=str(request.url))
    response = await call_next(request)
    logger.info("response", status=response.status_code)
    return response

To expose Prometheus metrics, add a /metrics endpoint with prometheus-fastapi-instrumentator:

from prometheus_fastapi_instrumentator import Instrumentator

Instrumentator().instrument(app).expose(app, endpoint="/metrics")

Then restrict /metrics to your internal network from Nginx (allow 127.0.0.1; deny all;) to avoid publicly exposing metrics.

Worker timed out (pid XXXXX) — Gunicorn kills a worker that did not respond within the --timeout delay. Common causes: a synchronous route (def instead of async def) blocks the event loop, or a blocking operation (file read, network call) runs without asyncio.run_in_executor. Increasing --timeout masks the problem; the correct fix is to make the route async or offload blocking work.

Address already in use (port 8000) — A previous Gunicorn process is still active. In Docker: docker compose down then docker compose up -d forces container recreation and releases the port. Check with docker ps -a that no zombie container is running.

502 Bad Gateway after a deployment — Nginx forwarded the request to the API during its restart. Wait 10–15 seconds for the Docker healthcheck to confirm the new container is healthy before considering the deployment complete. Add proxy_read_timeout 60; in Nginx to absorb slow startups.

CORS in production: No 'Access-Control-Allow-Origin' header — FastAPI serves the origins declared in CORSMiddleware. Verify that CORS_ORIGINS in your .env contains exactly the frontend URL (protocol + domain + port if non-standard, no trailing slash). A value of ["*"] works in development but must never go to production.

DB connection refused at startup — The API starts before PostgreSQL is ready. depends_on with condition: service_healthy in Docker Compose solves this. In Kubernetes or deployments without Compose, implement a retry loop with exponential backoff in the application startup code.

The ServOrbit Marketplace offers a preconfigured FastAPI Stack template: Python 3.12, Uvicorn, Gunicorn, Nginx, and PostgreSQL 16 are installed automatically on your VPS from the order form. No SSH session for the base setup — you arrive directly at the repository clone step and start Uvicorn. The marketplace page contains the exact specifications, use cases, and a first-login guide.