The short answer

To deploy FastAPI, stop using fastapi dev and uvicorn --reload. Those are development servers. A FastAPI production deployment runs Uvicorn in a container, on 0.0.0.0 and the port in the start command, with dependencies locked in the image, settings in environment variables, and one server process in that container. A FastAPI Uvicorn production process is that server: no reload, every interface, and the port from the command.

FastAPI hosting on Unbroker is a Dockerfile service, and that path requires Pro. Dockerfile builds are not available on Free. The product page is Deploy FastAPI. The steps are Deploy a FastAPI application.

Dev server and production server

fastapi dev starts development mode. Auto-reload is on, and the server listens on 127.0.0.1, the address the machine uses to talk to itself. The FastAPI CLI says to use fastapi run for production. fastapi run turns reload off and listens on 0.0.0.0, so the process is reachable from outside the machine. In a container, that is the address you want.

Uvicorn’s deployment page says to run uvicorn --reload for local development. The settings page says --host defaults to 127.0.0.1, and --host 0.0.0.0 is how you make the application available on the network. --reload and --workers cannot be used together.

Development (fastapi dev, uvicorn --reload)Production server
ProcessDevelopment mode. Reloads when the code changes. Not the release command.Uvicorn without reload, in a container. fastapi run is the CLI’s production command and also disables reload.
Address127.0.0.1. Other machines cannot reach that address. fastapi dev uses port 8000.0.0.0.0 and the port in the command. The Unbroker sample is ${PORT:-8000}.
DependenciesWhatever the local environment has installed.A committed requirements.txt of resolved versions, installed in the image.
SettingsOften a local .env file.Runtime environment variables. Not in the repo, and not copied into the image.
Long workEasy to leave in the request process.A worker with a durable queue, when the job has to survive a restart.

A production Dockerfile

The Unbroker guide’s Dockerfile is the file to ship. FastAPI’s container page uses its own Python base image and fastapi run on a fixed port. The guide uses python:3.12-slim, installs the committed requirements, drops to a non-root user, and starts Uvicorn so the shell can expand PORT.

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt
COPY main.py ./
RUN useradd --uid 10001 --create-home appuser
USER appuser
ENV PORT=8000
CMD ["sh", "-c", "exec uvicorn main:app --host 0.0.0.0 --port ${PORT:-8000}"]

Record the resolved dependencies in requirements.txt and commit that file, so the image installs a known set of versions. The guide says to keep the base image and those locked dependencies updated through your normal review. Copy the requirements file before the application file. FastAPI’s container page puts the dependency file first for the same reason: the install layer can be reused when only the application code changes.

The CMD line is Docker’s exec form, the JSON array. FastAPI’s container page says to use that form so the process can shut down gracefully and lifespan events run. The shell form, a bare CMD uvicorn ..., does not. This command still starts a shell, because the shell is what expands PORT. exec replaces that shell with Uvicorn. The guide states both parts: the shell expands PORT, and exec lets the application receive shutdown signals. Without exec, the signal stops at sh and the server is not the process that receives it.

${PORT:-8000} listens on PORT when it is set, and on 8000 only when PORT is empty. ENV PORT=8000 is the default inside the image. Bind 0.0.0.0, not 127.0.0.1. The process runs as appuser, not as root.

A FastAPI Docker deploy starts from this file at the repository root. The guide’s local check builds the image and requests /health before you connect the repository. The same shape is Deploy a Docker container. A compose file that starts the API, a database, and a worker as one stack is a different layout: Docker Compose in production.

FastAPI’s container page also says the old tiangolo/uvicorn-gunicorn-fastapi image is deprecated. Build from a Python base image instead of that image.

Workers, processes, and replicas

The guide’s example has one server process per container. That matches the case FastAPI documents when replication lives outside the container.

FastAPI’s container page says that if a cluster or a platform replicates containers, you want a single Uvicorn process in each container, not --workers. --workers starts several worker processes inside one container, with a process manager in front of them. FastAPI says that extra manager is complexity you already covered if the platform is creating the copies. Uvicorn documents --workers on its deployment page. The default count is 1, or $WEB_CONCURRENCY if that variable is set. Do not set WEB_CONCURRENCY unless you intend the default to follow it. The guide’s command does not pass --workers.

There is a separate case. FastAPI says --workers can make sense for a simple app on a single server, or for Docker Compose on one machine, where you do not have another way to run several containers and balance requests across them. That is not the Unbroker example. Running Uvicorn workers in production is that choice: several processes in one container, or one process and more containers. This post does not pick a worker count.

On Unbroker, Free runs one replica. Pro can configure replicas, up to the shared-cell limit in the plans table. Replica autoscaling is not available on Free. How copies are added and removed is Replica autoscaling. A worker service is different: the worker guide says worker services run one replica.

Settings and secrets

FastAPI’s settings page says secret keys, database credentials, and other settings usually come from environment variables, because they change and because many of them are sensitive. An environment variable is a string outside the Python code. Anything that is not a string, including a number, has to be parsed in the application.

pydantic-settings is optional. BaseSettings reads those variables, case-insensitive, and validates them into the types you declare. A .env file is the local form of the same idea. In production, set the same names as runtime variables. Do not commit the file, and do not bake it into the image.

A secret copied into an image layer stays in the artifact even if a later layer deletes the file. The Docker guide says to add .env, local credentials, and other local files to .dockerignore when a COPY is broad, and to set application secrets through runtime variables. That guide is Deploy a Docker container.

On Unbroker, open the service’s variables and set the value for the environment that should receive it: Production, Preview, or All. A production database credential does not belong in All unless preview environments should receive it. Use a service variable for configuration that one application owns. Shared project variables are for a setting several services share, and they require Pro. A service variable overrides a shared variable with the same key. Redeploy so the running revision uses the new value. Do not print the whole environment while you debug. The scope is Environment variables and secrets, and the steps are Configure environment variables and secrets.

Database, pools, and migrations

The FastAPI guide’s example has no database. When you add one, it says to use a runtime connection variable, a connection pool, and a deliberate schema migration step. Do not run migrations during the image build.

On Unbroker there are two PostgreSQL paths. An Apps node is a private database service in the project. A managed cluster is a database host the provider operates. The connection guide starts from Unbroker Pro and an existing PostgreSQL resource. Managed databases are not available on Free. You still own the schema and the migrations. Store the credentials in the service’s runtime variables. A command that reveals a connection string can print a secret, so keep that output out of the repo, the chat, and the logs. Do not turn certificate verification off to get past a connection error, and do not expose the database publicly to diagnose a private one. The steps are Connect your application to PostgreSQL. Operating the database is Postgres in production.

Bound the pool, and set timeouts. The connection guide’s row for “too many connections” is the pool size multiplied by processes and replicas. One process per container does not keep the total small if every replica opens a large pool.

Run the migration once, with the runtime credentials, before the new version takes traffic. FastAPI’s deployment concepts say a previous step such as a database migration should run a single time. If every process runs it, those processes do the work in parallel, and a migration can conflict with itself. If the project already uses Alembic, that command is this step. This page does not add flags for it. On Unbroker, migration commands require Pro. What a code rollback leaves behind is Database migrations on deploy.

Background work

BackgroundTasks run after the response, in the same process. FastAPI’s background-task page uses them when the client does not need to wait, for example an email notification or a file the request has already accepted. The task function can be async def or a normal def.

The same page has a caveat. If the work is heavy and does not need the memory of that process, use a queue tool instead. The page names Celery as the example. Those tools need a message queue, and they can run on other processes and other machines. The Unbroker worker guide does not name a library. It says the worker and the durable queue are separate, and that a loop over an in-memory array is not durable delivery.

If the job has to survive a restart, BackgroundTasks are the wrong place. They live in the server process. When that process stops, the in-process task stops with it. Put the consumer in its own worker service. The start command should launch the consumer and stay up while it waits. A script that handles one item and exits is a scheduled job or a one-off command, not a worker. Worker services require Pro, and they run one replica. They have no public URL. The split is Background workers and cron jobs, and the steps are Deploy a background worker.

Health checks and startup failures

The guide’s FastAPI health check is GET /health. The sample returns {"ok": True}. After the deploy, open /health on the service URL. The sample also has /api/message.

Two failures show up before you need a bigger machine. An import error usually means the module path in main:app does not match the repository, or a dependency was omitted from the image. A container that answers locally and is unreachable after deploy usually needs the host or the port corrected: 0.0.0.0, and the port the command actually bound. Read the runtime logs before you increase resources. Where to start when a release fails is Debug a failed deployment. The guide links the same diagnosis in Diagnose a failed deployment.

How this works on Unbroker

In Cloud, add a repository service, select the Dockerfile build method, and use the root Dockerfile. Configure runtime variables before deploying. Open /health on the service URL.

An Express API on the managed Node.js preset is a different path. The public managed Node.js path can qualify for Free, and Dockerfile builds are not on Free. What changes after nodemon is Express in production.

The guide starts from a Python repository, a local Docker check, and Unbroker Pro. Dockerfile builds are a paid-plan capability. They are not available on Free. The plans table lists Dockerfile builds, worker services, migration commands, and managed databases as not available on Free and available on Pro. The pricing page lists Dockerfiles with Pro as well. This page does not describe a Free path for FastAPI. What the $0 plan can run, for managed Node.js and static sites, is free backend hosting without a Dockerfile.

Pro is $25 a month with $25 of usage credit. The credit resets each billing cycle and does not roll over. If eligible usage stays under the credit, the monthly charge is still the plan price. If eligible usage is above the credit, only the difference is added. Plan rows are on pricing and in Plans. Budget the running API, the build, and any database separately. The guide says the same thing.

How do I deploy a FastAPI app with Docker Compose?

A Docker Compose file is an inventory of processes, not something Unbroker runs as one Compose project. To deploy a FastAPI app that you today start with Compose, treat each service in the file as its own Unbroker service.

When you create a project you can paste a Compose file; Unbroker creates one service per entry. That path supports images, repository builds, environment, depends_on, ports, commands, and one persistent volume per service. It does not decide what is public, where the data lives, or whether a database should be a managed cluster. You can also add those services by hand.

The FastAPI service itself is still the Dockerfile in this post: Uvicorn, no reload, listening on 0.0.0.0 and PORT. Dockerfile builds require Pro. A Postgres or Redis service in the same Compose file becomes a separate Apps database node or a managed database, not a process packed into the API image. The field-by-field map is in Docker Compose in production. The container steps are in Deploy a FastAPI application.

Checklist

  1. Leave fastapi dev and uvicorn --reload out of the production command.
  2. Listen on 0.0.0.0. Use the guide’s ${PORT:-8000} form, and put exec in front of Uvicorn so shutdown signals reach the server.
  3. Install a committed requirements.txt of resolved versions. Run as the non-root user in the guide’s Dockerfile.
  4. Keep one server process in the container. Do not pass --workers when replicas live outside it, and do not set WEB_CONCURRENCY unless you mean to.
  5. Read settings from environment variables. Keep secrets out of the repo and out of the image.
  6. Point Postgres at a runtime variable. Bound the pool. Remember the pool size times processes times replicas.
  7. Run migrations once, as their own step, not during the image build and not in every process.
  8. Put work that must survive a restart on a worker with a durable queue. Leave BackgroundTasks for short work in the web process.
  9. Open /health after deploy. Read runtime logs before you raise resources.
  10. Deploy the Dockerfile service on Pro. Dockerfile builds are not on Free.

FAQ

Can I use uvicorn --reload or fastapi dev in production?

No. Uvicorn's deployment page says to run uvicorn --reload for local development. fastapi dev is development mode: auto-reload is on, and it listens on 127.0.0.1. The FastAPI CLI says to use fastapi run for production. Reload watches the working tree and is the wrong process for a release. The Unbroker guide starts Uvicorn without reload, on 0.0.0.0, and takes the port from PORT.

Should I run Uvicorn with --workers or one process per container?

One process per container when something outside the container creates the copies. FastAPI's container page says that, and it says not to pass --workers in that case. --workers starts several worker processes inside one container. It is mutually exclusive with --reload. Uvicorn's default is 1, or the value of WEB_CONCURRENCY when that variable is set. The Unbroker example does not pass --workers. It has one server process. How copies are added on Unbroker is Replica autoscaling.

Why is my FastAPI container healthy locally but unreachable after deploy?

Check the host and the port. The FastAPI guide says a healthy local container that is unreachable remotely often needs that configuration corrected. Uvicorn's default host is 127.0.0.1, which other machines cannot reach. Bind 0.0.0.0. The guide's command uses ${PORT:-8000}, so an empty PORT falls back to 8000, and the image sets ENV PORT=8000. Read the runtime logs before you raise CPU or memory. An import error usually means the main:app path does not match the module, or a dependency was left out of the image.

Where do FastAPI secrets and settings go in production?

In environment variables, outside the repository and outside the image. FastAPI's settings page says secret keys and database credentials are commonly read from the environment. pydantic-settings is optional: BaseSettings reads those variables and validates them. A .env file is a local convenience on that same page. Do not commit it, and do not copy it into an image layer. On Unbroker the values are runtime variables. How they are scoped is Environment variables and secrets.

When should Alembic migrations run?

Once, as their own step, with the runtime credentials, not while the image is built and not from every server process. The FastAPI guide says to use a deliberate schema migration step and not to run migrations during the image build. FastAPI's deployment concepts say a previous step such as a migration should run once: parallel runs can conflict. If the project already uses Alembic, that command is the step. On Unbroker, migration commands require Pro. What a code rollback does not undo is Database migrations on deploy.

Are FastAPI BackgroundTasks enough for long jobs?

For a small task that can run in the same process after the response, yes. FastAPI's background-task page uses them for work the client does not need to wait for, such as an email notification. The same page says heavy work that does not need that process belongs in a queue tool, which can run on other processes and other machines. BackgroundTasks do not outlive the process. If the job has to survive a restart, use a worker and a durable queue. The split is Background workers and cron jobs.

Can I deploy FastAPI on Unbroker's Free plan?

No. The documented path is a Dockerfile build, and Dockerfile builds are not available on Free. The plans table lists them as not available on Free and available on Pro. The pricing page lists Dockerfiles with Pro. This page does not describe another way to run FastAPI on Free. Pro is $25 a month with $25 of usage credit. The steps are Deploy FastAPI and the FastAPI guide.

How do I deploy a FastAPI app with Docker Compose?

Treat the Compose file as an inventory, not as a single unit Unbroker runs. When you create a project you can paste a Compose file, and Unbroker creates one service per entry. That path supports images, repository builds, environment, depends_on, ports, commands, and one persistent volume per service. It does not choose what is public, where the data lives, or whether a database should be a managed cluster. The FastAPI service is still a Dockerfile that starts Uvicorn on 0.0.0.0 and PORT, and Dockerfile builds require Pro.