# FastAPI apps

> What Kubana detects in a FastAPI repository, what happens when it finds several apps, workers for task queues, and migrations.

- Product: Kubana Cloud, App Platform
- Web page: https://kubana.cloud/docs/app-platform/fastapi-apps
- Last updated: 2026-10-19

FastAPI apps are backends on App Platform. Kubana reads your repository to find how to install and start the app, then builds it for you, so you don’t need a Dockerfile.

## What Kubana detects

There is nothing to configure. When you select a branch, Kubana reads it and shows how it will run your app in **Configuration > How Kubana runs your app**:

- **App directory**: the repository root, or a first-level folder (like `backend/`) whose `pyproject.toml`, `requirements.txt` or `Pipfile` lists `fastapi`.
- **Package manager**: from the lock file. Supported: `uv.lock`, `poetry.lock`, `pdm.lock`, `Pipfile.lock`, `requirements.txt`, or a plain `pyproject.toml`. uv workspaces work too.
- **The app**: the `[tool.fastapi] entrypoint` setting in `pyproject.toml`, the same files `fastapi run` checks (`main.py`, `app/main.py`, …), any module-level `app = FastAPI()`, or a `create_app()` factory.
- **Python version**: from `.python-version`, then `requires-python`. Kubana supports Python 3.11 to 3.14.
- **Health check**: a `/health`, `/healthz`, `/health-check`, `/up` or `/ping` route declared on the app. Without one, Kubana checks that the app is running.
- **System packages**: Debian packages your dependencies need, installed automatically. For example `python-magic` gets `libmagic`, `pdf2image` gets Poppler, `pydub` and `moviepy` get FFmpeg, `pytesseract` gets Tesseract, and `weasyprint` gets Pango.

Kubana detects again on every deploy, so a push that moves your app is picked up. Use **Detect again** to check before deploying.

## When Kubana finds several apps

If your repository holds several FastAPI projects, or several apps, Kubana lists what it found and asks which one this app runs. Pick one; you can change it later with **Choose another folder**.

To deploy the other one too, create a second app from the same repository and pick it there.

## Custom start command

For what detection can't handle, open **Custom start command** and enter the command that starts your app. Your app must listen on port **8080**. Leave it empty to go back to what Kubana detects.

When Kubana can't find your app, the simplest fix is usually to tell FastAPI where it is, in `pyproject.toml`:

```toml
[tool.fastapi]
entrypoint = "app.main:app"
```

The default start command is:

```bash
uvicorn app.main:app --host 0.0.0.0 --port 8080 --proxy-headers --forwarded-allow-ips '*'
```

To run more web workers, set the `WEB_CONCURRENCY` environment variable.

## Migrations

Kubana **never runs migrations on its own**. To run Alembic on every deploy, add a post-deployment command in **Configuration**:

```bash
alembic upgrade head
```

Commands run from your app directory after each successful deploy.

## Frontends served by FastAPI

Kubana installs and runs your Python app; it doesn't build JavaScript. If your app serves a built frontend (for example with `app.frontend()` or `StaticFiles`) from a folder that isn't in the repository, the deploy stops with a message. Deploy the frontend as a separate **Vue** or **React** app, or commit its build output.

## Background tasks and schedulers

FastAPI's `BackgroundTasks` run inside the web app, so they work as they are.

Task queues run in a separate worker app. When your app uses one, **How Kubana runs your app** offers **Add a worker**: one click creates it from the same repository and branch, with the same size and a copy of your environment variables, and with no deploy key to add. Deploy it to start it; it is billed once deployed. Environment variables are copied once, so later changes need to be made on both apps.

Kubana detects the library and runs its worker, plus its scheduler when there is one:

| Library | Worker | Scheduler |
| --- | --- | --- |
| Celery | `celery -A app.worker:celery_app worker` | `celery … beat`, when you define a beat schedule |
| RQ | `rq worker --with-scheduler` | `rqscheduler` with rq-scheduler, or `rq cron` |
| Huey | `huey_consumer app.queue.huey` | built into the consumer |
| ARQ | `arq app.worker.WorkerSettings` | built in (`cron_jobs`) |
| Dramatiq | `dramatiq app.broker app.tasks` | `periodiq`, when installed |
| Taskiq | `taskiq worker app.broker:broker --fs-discover` | `taskiq scheduler`, when you define one |
| SAQ | `saq app.jobs.settings` | built in (`cron_jobs`) |
| APScheduler | none | a script that runs a `BlockingScheduler` |

A worker app has no public URL. Set your broker's URL (for example `REDIS_URL`) on **both** apps; RQ reads `RQ_REDIS_URL`. If Kubana finds several libraries, it asks which one this app runs. If it finds none, set the worker and scheduler commands under **Custom commands**.

Kubana stops workers gracefully on redeploy. ARQ and SAQ cancel running jobs unless your settings give them a grace period.

For plain scripts on a schedule, use [cron jobs](https://kubana.cloud/docs/app-platform/cron-jobs) instead.

**Warning: APScheduler**
If your app starts APScheduler inside the web process, every web worker runs its own scheduler. Keep `WEB_CONCURRENCY` at 1.


## Step-by-step tutorial

For a full walkthrough with screenshots, read [How to deploy a FastAPI app on Kubana App Platform](https://kubana.cloud/blog/app-platform/how-to-deploy-a-fast-api-app-on-kubana-app-platform).
