Deploy FastAPI to Your Own VPS with One Config File

To deploy a FastAPI app to your own VPS, you need a server, a start command for uvicorn, and a way to get HTTPS, a database and migrations in place. With ox, all of that lives in one small file called ox.toml. You run ox check, then ox deploy, and your API is live on your own Ubuntu server. This post walks through it step by step.

What you need

• A FastAPI app that runs with uvicorn, in a GitHub repo.

• A fresh Ubuntu LTS server with at least 1 GB of memory, 10 GB of free disk, and ports 80 and 443 free.

• An ox account. You sign in with GitHub.

In the ox dashboard, press Add a server. It shows one command with a fresh token in it. Run it on the server as root:

curl -fsSL https://deploywithox.com/install/<token> | sudo bash

This installs the ox agent and Caddy. Then press New project and pick your repo.

What ox finds by itself

ox reads the Python files at the root of your repo. Often you need no config at all. It looks for:

• The install step, from your lockfile. For uv.lock that is uv sync --frozen --no-dev. It also knows poetry.lock, requirements.txt and a plain pyproject.toml.

• The Python version, from .python-version, .tool-versions or mise.toml.

• A start command. This works when uvicorn or fastapi[standard] is a dependency, and one of main.py, app.py, app/main.py or src/main.py makes the app with FastAPI(.

• Migrations. When alembic.ini is in the repo and alembic is a dependency, it runs uv run alembic upgrade head.

• Services. When the repo has no ox.toml, it adds PostgreSQL if psycopg, psycopg2 or asyncpg is a dependency, and Redis if redis is.

If ox is not sure, it does not guess a start command. ox check prints a hint that says why. Then you set it yourself.

The one config file

When you want your own domain, a health check and full control, add this ox.toml to the root of your repo:

domains = ["api.example.com"]

[app]
start  = "uv run uvicorn app.main:app --host 127.0.0.1 --port $PORT --workers 2"
health = "/health"

[build]
install = "uv sync --frozen --no-dev"
migrate = "uv run alembic upgrade head"

[services]
postgres = {}

Here is what each line does:

• domains: the names your API answers on. ox gets the HTTPS certificate for each.

• start: runs uvicorn on the port ox picks, with two worker processes.

• health: a path that must answer with a 2xx or 3xx status before a new release gets traffic.

• install: installs your packages from uv.lock.

• migrate: runs your Alembic migrations on every deploy, after ox takes a snapshot of the database.

• postgres: a database for this app.

Add a health route

The health route should answer without touching the database, so it stays fast:

from fastapi import FastAPI

app = FastAPI()


@app.get("/health")
def health():
    return {"ok": True}

This route matters. On each deploy, the new release starts next to the old one. Traffic moves only after /health answers. So a broken release never takes your API down.

Connect to Postgres

With postgres = {}, ox makes a database and gives your app DATABASE_URL. Add redis = {} and you also get REDIS_URL.

There is one small catch. DATABASE_URL starts with postgres://. SQLAlchemy wants the driver in the name, so change the start of it when you read it:

import os
from sqlalchemy import create_engine

url = os.environ["DATABASE_URL"].replace("postgres://", "postgresql+psycopg://", 1)
engine = create_engine(url)

Point Alembic's env.py at the same url. That way your migrations and your app use one database.

Set your secrets

ox also gives you PORT, HOST, PUBLIC_URL and PUBLIC_HOST. Set your own keys, like SECRET_KEY, on the dashboard. Or use ox vars set <project> SECRET_KEY, which asks for the value.

Every key named in .env.example must be set before a deploy can start. ox never reads your .env file.

Check, then ship it

Run these from your repo:

ox check                      # in the repo: prints the plan and "Ready to deploy."
ox deploy <project> --wait    # stream the deploy, exit with its result
ox logs <project> --follow    # the app's own logs

For the ox.toml above, ox check ends like this:

  Provided by ox: PORT, HOST, OX_ENV, OX_PROJECT, OX_RELEASE, OX_DATA_DIR, PUBLIC_URL, PUBLIC_HOST, DATABASE_URL
  Set on the dashboard before the first deploy: SECRET_KEY
  hint: SQLAlchemy (from uv.lock) rejects DATABASE_URL's postgres:// scheme; in your code, use os.environ["DATABASE_URL"].replace("postgres://", "postgresql+psycopg://", 1)

Ready to deploy.

The check runs before anything on the server changes. If a key is missing, you find out now, not after a broken deploy.

If it fails

• "nothing to run": ox found no start command. The hint above it says why, such as uvicorn not being a dependency. Add uvicorn, or set [app] start.

• The app exited while starting, or /health did not answer within 120s: read the app's log above it. A wrong module path like main:app instead of app.main:app is a common cause. So is a KeyError for a missing variable.

• The migrate step failed: Alembic's own output is above it. Run the migration against a local database, fix it, and push.

If an older release is live, it keeps serving while you fix any of these.

Try it

ox is free while it is in beta. Sign up with GitHub at deploywithox.com. The full FastAPI guide has every detail from this post. The config reference lists every key you can put in ox.toml.

---

Tired of doing all this by hand? ox deploys your repo to your own server for you. No Docker, no config maze. Try deploywithox.com