Reference

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/) 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:

[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 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 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