How to Deploy a FastAPI App on Kubana App Platform

Kubana Cloud · November 20, 2026 · Updated November 16, 2026 · 17 min read

Tutorials
How to Deploy a FastAPI App on Kubana App Platform
On this page

Introduction

You wrote a FastAPI app and it runs on your laptop. Now you want it on the internet, with HTTPS, without renting a server, writing a Dockerfile or learning Kubernetes.

Kubana App Platform does that. You point it at a GitHub repository, and Kubana reads your code to work out how to run it: where the app is, which package manager you use, your Python version, your health check route, even the system libraries your dependencies need. There is nothing to fill in. You review what Kubana found, press Deploy, and get a public HTTPS address.

At a glance

  • Time: about 15 minutes for the first deploy.
  • You need: a Kubana account with App Platform access, a GitHub repository, and a few dollars of credit.
  • You get: your API at https://<your-app>.platform.kubana.app, rebuilt on every push if you want, with build logs, live logs and one-click rollbacks.
  • You don't need: a Dockerfile, a Procfile, a server, or any settings file.

The guide has two parts. Part 1 takes you to a live URL in seven steps. Part 2 covers the extras most real apps need: a database with Alembic migrations, a Celery worker, cron jobs, deploy on push, and your own domain. Do as much of Part 2 as your app needs. Part 3 shows how to do all of it by asking your AI assistant (Claude, ChatGPT, Cursor and others), through Kubana's MCP server.

Note: App Platform is in early access. If you don't see it in the dashboard, open App Platform and choose Request early access.

Before you start

You need:

  • A Kubana Cloud account with App Platform access.
  • A project in the dashboard to hold the app (Projects → New project if you have none).
  • Enough credit for the size you pick. Before the first deploy, your balance must cover 72 hours of that size. The dashboard shows the exact amount when you pick a size (for the Small size it is well under a dollar).
  • A FastAPI app in a GitHub repository, public or private.

Don't have an app yet? Two files are enough

Create a new GitHub repository with these two files:

requirements.txt
app/main.py

requirements.txt:

fastapi[standard]

app/main.py:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def home():
    return {"message": "Hello from Kubana App Platform!"}

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

Push them to GitHub and follow the steps below. The screenshots show a slightly bigger app called notes-api, with a database and a Celery worker, so that Part 2 has something to show. Your two-file app goes through Part 1 exactly the same way.

Check these four things

Kubana handles most FastAPI projects as they are. Check that:

  1. fastapi is listed as a dependency in requirements.txt, pyproject.toml or Pipfile, either at the root of the repository or in a first-level folder such as backend/.
  2. Kubana can find your app. It looks for an app = FastAPI() in the usual places (main.py, app/main.py, …), the [tool.fastapi] entrypoint setting in pyproject.toml, or a create_app() factory.
  3. If you pin a Python version, it is 3.11 to 3.14. Kubana reads .python-version first, then requires-python in pyproject.toml. If you pin nothing, Kubana uses the newest supported version.
  4. Your app has a health route (recommended). If you declare /health, /healthz, /health-check, /up or /ping, Kubana calls it before sending traffic to a new version, so a broken release never replaces a working one.

You can use pip, uv, Poetry, PDM or Pipenv. Kubana picks the right one from your lock file.

Part 1: From GitHub to a live URL

Step 1: Create the app

In the dashboard, open App Platform and choose New app.

App Platform page with the New app button highlighted

Fill in the form (the numbers match the screenshot):

  1. Project: the project the app belongs to.
  2. App name: a short name such as notes-api. It becomes part of your address: notes-api.platform.kubana.app.
  3. Framework: choose Backends, then FastAPI.
  4. GitHub repository: paste owner/repo, the HTTPS URL or the SSH URL. All three work.
  5. App size: CPU, memory and disk. Small is plenty to start, and you can pick a bigger size later.

New app form with project, name, Backends, FastAPI, repository and size filled in, numbered 1 to 5

Choose Review app, check the summary, then Create app and Confirm & create. Nothing is billed yet: billing starts at the first deploy.

Create app confirmation showing the app, framework, repository, size, price and the credit required

Step 2: Let Kubana read your repository

Kubana opens your new app on the Deploy key panel. A deploy key is a key that gives Kubana read-only access to this one repository: Kubana can clone your code but can never push to it.

Deploy key panel with Copy key, Open deploy keys and the verify button highlighted

  1. Choose Copy key (1).

  2. Choose Open deploy keys (2). It opens your repository's Settings → Deploy keys page on GitHub. Choose Add deploy key.

  3. Paste the key, give it a title such as Kubana, and leave Allow write access unchecked. Save.

    GitHub Add deploy key form with the Kubana key pasted and Allow write access unchecked

  4. Back in Kubana, choose I've added the key, verify access (3).

After a few seconds the status changes to Ready and the next item to do shows up in the menu as Set branch · Required.

App page after verification: status Ready and the Set branch item marked Required

If verification fails: check that you added the key to the same repository you entered in Step 1 and that you saved it on GitHub. Read-only access is enough.

Step 3: Pick the branch to deploy

Open Set branch. Choose Load branches, select the branch Kubana should deploy (1, usually main, marked Default) and choose Save branch (2).

Git branch list loaded from GitHub with main selected and Save branch highlighted

Kubana only deploys this branch. Pushes to other branches are ignored.

Step 4: Check how Kubana will run your app

When you save the branch, Kubana reads it and shows what it found under Configuration → How Kubana runs your app. For the notes-api app in the screenshots it says:

How Kubana runs your app: runs app.main:app and checks /health, installs with pip on Python 3.13, and offers to add a Celery worker

Read it as plain English:

  • Runs app.main:app: the FastAPI object Kubana found in app/main.py.
  • Checks /health before switching traffic: a new version only goes live once that route answers.
  • Installs with pip · Python 3.13: from requirements.txt and .python-version.
  • Your app uses Celery: Kubana noticed app/worker.py. You'll use this in Part 2.

If this looks right, there is nothing to configure. Kubana detects again on every deploy, so if you move files around later, the next deploy picks it up. Choose Detect again to check before deploying.

If Kubana can't find your app, this panel says so and tells you why. The simplest fix is to tell FastAPI where your app is, in pyproject.toml:

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

As a last resort, open Custom start command and type the command yourself. Your app must listen on port 8080.

Step 5: Add your environment variables

Your app's settings and secrets (database URL, API keys…) belong in Environment, not in your repository.

Open Environment → Add variables → Paste .env, paste your variables (1), check the preview, then choose Create 2 variables (2):

Environment tab with a .env block pasted: DATABASE_URL and SECRET_KEY, and the add button highlighted

New variables show as pending until the next deploy. Kubana stores them right away, but your app only sees them once it is deployed.

Environment list with DATABASE_URL and SECRET_KEY marked as pending changes

If your app doesn't need any variable yet (the two-file app above doesn't), skip this step and come back to it in Part 2.

Keys named GIT_SSH_KEY_B64 or starting with KUBANA_ are reserved and can't be used.

Step 6: Deploy

Choose Deploy at the top right of the app page and confirm.

Deploy confirmation dialog

The status changes to Deploying. Under Deployments you can see the commit being built. A first deploy usually takes two to three minutes, and the page refreshes by itself.

Deployments tab with one deployment In Progress for commit 4f9c2a1

Behind the scenes Kubana clones your branch, builds an image with your dependencies, starts it, waits for /health to answer, then sends traffic to it.

Step 7: Open your app

When the status is Active, your public address appears next to the repository name. Choose Open app, or copy the address.

App overview: status Active, public address notes-api.platform.kubana.app highlighted, live commit 4f9c2a1, billing active

Add /docs to the address to get FastAPI's interactive documentation, live on the internet:

The app's /docs page served at https://notes-api.platform.kubana.app/docs

Your app is live. The overview also shows the live commit, which is the exact version that is running.

Note: On a brand new app, the HTTPS certificate can take a few minutes to be issued. If your browser warns about the certificate, wait a moment and reload.

Where to look when something is off

  • Deployments → Logs shows the build log of a deployment: what Kubana detected, the packages it installed, the start command and the health check.

    Build log of a successful deployment: detection, pip install, image build, start command and health check

  • Logs shows what your running app prints: requests, errors, your own print() and logging output.

    Runtime logs with uvicorn startup lines and incoming requests

Part 2: Make it a real app

Each section below is optional and stands on its own.

Connect a database and run migrations

Apps on App Platform run in containers that are replaced on every deploy, so anything written to the app's own disk is lost. Don't use a SQLite file: keep your data in a database that runs outside the app: a managed MySQL or PostgreSQL service, or a database on your own Kubana server.

  1. Add DATABASE_URL in Environment (see Step 5). For MySQL with SQLAlchemy it looks like:

    DATABASE_URL=mysql+pymysql://user:password@your-db-host:3306/notes
  2. Tell Kubana to run your migrations. Kubana never runs migrations on its own. In Configuration → Post-deployment commands, Kubana suggests alembic upgrade head when it sees Alembic: click the suggestion so it fills the first row (1), then Save commands (2).

    Post-deployment commands with alembic upgrade head added and Save commands highlighted

  3. Redeploy. Post-deployment commands run from your app's folder after each successful deploy, in order. If one fails, the ones after it don't run.

Alembic tip: your alembic.ini must contain prepend_sys_path = . (the default from alembic init). Without it, alembic upgrade head can't import your app package and the command fails.

Add a background worker (Celery)

FastAPI's built-in BackgroundTasks run inside the web app and work as they are. A task queue such as Celery needs its own process, which runs as a second app called a worker.

Kubana spots the task library for you. Under How Kubana runs your app, choose Add a worker:

How Kubana runs your app with the Add a worker button highlighted

In one click, Kubana creates the worker app from the same repository and branch, with the same size and a copy of your environment variables. You don't add another deploy key. The worker detects its own command:

The new worker app, which runs celery -A app.worker:celery_app worker

Then:

  1. Make sure both apps have your broker's address, for example REDIS_URL=redis://…. Environment variables are copied once when the worker is created, so later changes must be made on both apps.
  2. Deploy the worker. It is billed from its first deploy, like any app.

A worker has no public address. Celery, RQ, Huey, ARQ, Dramatiq, Taskiq and SAQ are all detected, as are their schedulers (Celery beat, for example) when your code defines one.

Run a script on a schedule (cron jobs)

For a script that runs every night or every hour, you don't need a worker. Open Configuration → Cron jobs → Add cron job:

Add cron job form: name, command, schedule in plain words and time limit

  • Command: for example python -m app.jobs.cleanup. It runs from your app's folder, with your environment variables.
  • When should it run? Pick it in plain words (every day at 02:00, every 15 minutes…) or type a cron expression. Times are in UTC, and the form shows your local time next to them.
  • Time limit: a run that takes longer is stopped (5 minutes by default).

On a running app, a new cron job starts right away. You don't need to redeploy.

Deploy automatically on every push

So far you deployed by hand. To deploy every time you push to your branch:

  1. On Configuration → Auto-deploy, turn the switch on and confirm.

  2. Choose Show GitHub webhook details, and copy the Payload URL and the Secret.

    Auto-deploy turned on with the webhook payload URL and secret

  3. In GitHub, open your repository → Settings → Webhooks → Add webhook. Paste the payload URL, set Content type to application/json, paste the secret, and choose Just the push event. Save.

    GitHub Add webhook form with the payload URL, application/json and the push event

From now on, git push to your branch starts a deployment, labelled Auto deploy in Deployments.

Use your own domain

Every app gets a *.platform.kubana.app address. You can also attach up to five of your own domains, and HTTPS is set up for you.

  1. First, at your DNS provider (or in Kubana DNS Management), point the domain at Kubana with the records shown in the Domains tab:

    Type Host Value Required
    A @ or your subdomain, e.g. api 62.238.7.246 Yes
    AAAA @ or your subdomain 2a01:4f9:c015:ef6::1 Optional (IPv6)
  2. Then, in Domains, choose Add domain, enter the hostname (for example api.mynotes.rw) and attach it. Kubana checks the DNS records, then issues the certificate within a few minutes.

  3. Optionally make it the primary domain, so it becomes the app's main address.

Domains tab with notes-api.platform.kubana.app and the custom domain api.mynotes.rw attached

Extra A or AAAA records that point somewhere else make verification fail. Remove them first.

Part 3: Do it all by asking your AI assistant

Everything in this guide can also be done by asking an AI assistant. Kubana runs an App Platform MCP server: connect it once to Claude, ChatGPT, Claude Code, Codex, Cursor or VS Code, and your assistant can create, configure, deploy and debug your apps for you, with your account's permissions. If you already write code with an assistant, you don't have to leave your editor to ship it.

Connect it (about one minute)

  1. In your assistant, add a custom connector (or MCP server) with this URL:

    https://api.kubana.cloud/mcp/app-platform

    Claude users can also install it from the Claude directory. Setup steps for each assistant are on the MCP page.

  2. Your browser opens Kubana. Sign in, then choose Authorize. You don't need an API key.

Then just ask

The whole of Part 1 becomes a short conversation:

Create a FastAPI app called notes-api from github.com/me/notes-api, Small size, in my Notes project.

The assistant creates the app and gives you the deploy key. Add it on GitHub as in Step 2, then:

I've added the key. Use the main branch, show me how Kubana will run the app, add the variables from this .env, run alembic upgrade head after each deploy, then deploy it.

The assistant confirms the key, saves the branch, reads back what Kubana detected, sets your variables and migrations, and deploys. Part 2 works the same way:

  • "Add a worker for my Celery tasks and deploy it."
  • "Run python -m app.jobs.cleanup every night at 2 am my time."
  • "Turn on auto-deploy." The assistant gives you the webhook URL and secret to paste in GitHub.
  • "Attach api.mynotes.rw and make it the primary domain."

It also makes problems easier to solve:

  • "My last deploy failed. Read the build log and tell me why."
  • "Show me the errors in notes-api's logs from the last few minutes."
  • "Roll back notes-api to the previous deployment."

You stay in control

  • Risky actions ask you first. Anything that costs money, takes an app offline or touches secrets (creating an app, the first deploy, changing variables…) needs a 6-digit code that Kubana emails you. The assistant asks you for it. Choose which actions need a code under MCP Servers → Approval policy in the dashboard. See approval codes.
  • GitHub stays yours. The assistant can't touch your GitHub account, so you add the deploy key and the webhook yourself, as in the steps above.
  • Same prices, same limits. Connecting is free. A deploy started by your assistant costs exactly what it costs from the dashboard.
  • Revoke at any time under MCP Servers → Connections.

More ideas are in What you can do with Kubana's MCP servers.

Updating and rolling back

  • New code: push to your branch (with auto-deploy) or choose Redeploy.
  • New environment variables, branch or post-deployment commands: save them, then Redeploy. Saving alone doesn't change the running app.
  • Something broke? In Deployments, open an earlier deployment and choose Redeploy this version. Kubana rebuilds that exact commit. Your Git history is untouched, so fix the code, then push again.

Troubleshooting

What you see Why it happens What to do
Verification of the deploy key fails The key is on another repository, or wasn't saved Add it to the repository you entered at creation. Read-only is fine.
This app can't deploy yet under How Kubana runs your app Kubana didn't find a FastAPI app, or found a problem Read the message. Usually fastapi is missing from your dependencies, or the app is in an unusual place: set [tool.fastapi] entrypoint in pyproject.toml.
Kubana asks which app this is Your repository holds several FastAPI projects Pick the one this app runs. To deploy another, create a second app from the same repository.
The deploy is refused for insufficient credit Your balance doesn't cover 72 hours of the size Top up your credits, then deploy again.
The deploy fails at the health check Your app crashes at startup or /health doesn't answer Open Logs: a missing environment variable or a database that can't be reached are the usual causes.
alembic upgrade head fails with No module named 'app' alembic.ini lacks prepend_sys_path = . Add that line and redeploy.
Data disappears after a deploy It was written to the container's disk (SQLite file, uploads) Use an external database, and object storage for files.
Your app serves a frontend from a folder that isn't in Git Kubana runs Python and doesn't build JavaScript Deploy the frontend as its own React or Vue app, or commit its build output.
Celery tasks never run No worker, or the worker has a different REDIS_URL Add a worker and set the same broker URL on both apps.

Costs at a glance

  • Billing is hourly from your credit and starts at the first deploy. The price is locked at that moment.
  • A stopped app is still billed. A terminated app is not.
  • A worker is a separate app and is billed separately.
  • The dashboard always shows the live price before you create an app.

When you no longer need an app, go to Sensitive → Terminate, then Delete if you want to remove it completely.

Conclusion

You took a FastAPI app from GitHub to a live HTTPS address without a Dockerfile or a single settings file: Kubana read your repository, found your app, its Python version and its health check, and ran it. From here you can connect a database, run Alembic on every deploy, start a Celery worker in one click, schedule cron jobs, deploy on every push and serve it on your own domain.

Next steps:

If a deploy fails and the logs don't explain why, contact support from the dashboard. We read every message.

Attachments

Back to all articles
Newsletter

Stay in the loop

Product updates, infrastructure insights, and platform news delivered to your inbox.