FastAPI apps
What Kubana detects in a FastAPI repository, what happens when it finds several apps, workers for task queues, and migrations.
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/) whosepyproject.toml,requirements.txtorPipfilelistsfastapi. - Package manager: from the lock file. Supported:
uv.lock,poetry.lock,pdm.lock,Pipfile.lock,requirements.txt, or a plainpyproject.toml. uv workspaces work too. - The app: the
[tool.fastapi] entrypointsetting inpyproject.toml, the same filesfastapi runchecks (main.py,app/main.py, …), any module-levelapp = FastAPI(), or acreate_app()factory. - Python version: from
.python-version, thenrequires-python. Kubana supports Python 3.11 to 3.14. - Health check: a
/health,/healthz,/health-check,/upor/pingroute 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-magicgetslibmagic,pdf2imagegets Poppler,pydubandmoviepyget FFmpeg,pytesseractgets Tesseract, andweasyprintgets 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:
[tool.fastapi]
entrypoint = "app.main:app"The default start command is:
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:
alembic upgrade headCommands 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 instead.
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.
Last updated 19 October 2026 · Something missing or wrong? Tell us
