Deploying FastOpp to Leapcell: A Step-by-Step Guide

FastOpp is a modern FastAPI starter package for AI web applications that ships with auth, admin, demo data, and a few practical examples for real projects. Leapcell is a low-friction platform that gives you hosted services like Postgres and S3-compatible object storage with a straightforward deploy flow. This tutorial walks you through deploying FastOpp to Leapcell from a clean fork to a fully working demo, including database, emergency superuser, and object storage.

A full video tutorial is here: FastOpp Deployment to Leapcell - Tutorial

SQLite remains ideal for local development, but production needs a managed PostgreSQL database and durable object storage. Deploying to Leapcell delivers the same core architecture you’d assemble on AWS, with far less friction and strong performance.

You can start to learn about serverless, scalable architectures with FastOpp. But FastOpp itself is a starter package. It should not be used in production environments.

Forking and running the FastOpp project is quite fast. To deploy to Leapcell and get a publicly available URL, the process took me 30–45 minutes on a first run. There are two components that take longer with Leapcell:

1. Database cannot be the SQLite library stored to a file and has to be PostgreSQL

2. Storage must be Object Storage and cannot be a file

---

Prerequisites

• GitHub account with permission to fork repos.

• Leapcell account with GitHub integration enabled.

• Basic familiarity with environment variables and FastAPI.

• Local Python only needed if you want to generate a secure key with uv (recommended).

---

1) Fork FastOpp

1. Open the FastOpp repository: https://github.com/Oppkey/fastopp.

2. Click Fork and create the fork in your GitHub account.

3. Optional: rename the fork to something like fastopp-leapcell-tutorial.

You can also download a ZIP and re-upload to a new repo, but for this tutorial use a fork to keep things simple.

---

2) Create a Leapcell Service from Your Fork

1. In Leapcell, click Create service.

2. Select your newly created fork as the source.

3. Set region near your users.

4. Set Framework to FastAPI. Entry point is main:app.

Build command
Use:

pip install -r requirements.txt

Do not prefix with RUN in Leapcell’s UI.

Start command
Use:

uvicorn main:app --host 0.0.0.0 --port 8080

So nor prefix with startup() in Leapcell’s UI.

Submit to deploy. Expect an initial failure in logs when the app tries to write to the root filesystem; fix this in the next step with an upload directory env var.

Default settings in Leapcell:

---

3) Set the Upload Directory - Required on Leapcell

Leapcell does not allow writing to the root filesystem. Add this environment variable in the service settings:

UPLOAD_DIR=/tmp/uploads

Save and redeploy. Health checks should pass and you’ll get a working domain under Domains. You can browse the homepage, but login and demo data won’t work until the database is configured.

---

4) Provision Postgres and Connect FastOpp

1. In Leapcell, create a PostgreSQL database with the free plan.
   Note: the free tier allows one free Postgres instance. If you already created one and get a “Failed to create database” error, delete the existing free DB from Settings and retry.

2. In the DB page, locate the SQLAlchemy connection string under Python and copy it. It will look like:

    postgresql+psycopg2://USER:PASSWORD@HOST:PORT/DBNAME?sslmode=require
   

3. Modify the driver to use psycopg (async-capable stack) instead of psycopg2:

    postgresql+psycopg://USER:PASSWORD@HOST:PORT/DBNAME?sslmode=require
   

4. In your service’s environment variables, set:

    DATABASE_URL=postgresql+psycopg://USER:PASSWORD@HOST:PORT/DBNAME?sslmode=require
   

Save and redeploy. The app can now initialize sessions and accept logins once a superuser exists.

---

5) Generate a SECRET_KEY

FastOpp needs SECRET_KEY. On your local machine with uv installed:

uv run python oppman.py secrets

Copy the output and set it as:

SECRET_KEY=your_generated_secret_key
ENVIRONMENT=production

You can technically use any string, but generating a proper 32-byte key is best practice. Save and redeploy.

---

6) Create a Superuser via Emergency Access

Serverless environments like Leapcell do not expose a shell, so you cannot run FastOpp’s init script directly. Use Emergency Access once from the running FastOpp UI to create your first superuser:

1. Add:

    EMERGENCY_ACCESS_ENABLED=true
   

2. Redeploy. Open your site’s Emergency Access page (linked from the homepage “First Time Setup” section).

1. Paste your SECRET_KEY to grant temporary access.

2. Create a superuser (email + strong password).

3. Log in with that superuser.

4. Disable emergency mode immediately:

    EMERGENCY_ACCESS_ENABLED=false
   

5. Redeploy.

You now have admin access without shell commands.

---

7) Enable Object Storage for Media

FastOpp’s demo imports sample photos. Ephemeral /tmp storage is not reliable for user files. Configure S3-compatible storage on Leapcell:

1. In Leapcell, create an Object Storage bucket.

2. In the service environment variables, set:

STORAGE_TYPE=s3
S3_ACCESS_KEY=your_leapcell_access_key
S3_SECRET_KEY=your_leapcell_secret_key
S3_BUCKET=your_bucket_name
S3_ENDPOINT_URL=https://objstorage.leapcell.io
S3_CDN_URL=https://your-account.leapcellobj.com/your-bucket

3. Save and redeploy.

Notes:

• Leapcell may assign an internal bucket name even if you provide a label. Use the actual bucket identifier from the UI.

• After this step, uploads and demo images persist and load consistently via the CDN URL.

---

8) Initialize the Demo and Verify

1. While logged in as superuser, open Oppdemo Dashboard.

2. Click Initialize Full Demo. Wait until the status shows success for each step. If images do not appear, you likely missed the object storage configuration or did not wait long enough for the job to complete.

3. Visit Webinar Demo on the homepage to confirm data and images are present.

4. Test the admin flow:

   • Open Management → Webinar Management.

   • Edit or replace a speaker/registrant photo to confirm S3 writes and CDN reads.

5. Optional: open SQL Admin and verify tables and rows. Use the same admin credentials.

If a step appears stuck, re-open the page and re-run Initialize Full Demo after confirming object storage env vars are correct and the service has redeployed.

---

9) Health Checks

Leapcell’s deploy panel will show periodic health checks against the app. FastOpp includes standard health endpoints you can hit manually during troubleshooting:

• /kaithhealthcheck is used by Leapcell

• /health

• /healthz

A 200 OK confirms the process is live and the ASGI app responded.

---

Troubleshooting

• “Failed to create database” on free tier: You likely already used your one free DB. Delete the existing free DB in Settings and recreate.

• Images don’t appear or disappear: You are writing to /tmp/uploads instead of S3. Configure the S3 variables and redeploy.

• Login blocked: You have no superuser yet. Enable emergency access, create a superuser, then disable emergency access.

• DB errors mentioning psycopg2: Update the SQLAlchemy URL to use psycopg.

• Build fails on RUN: Use pip install -r requirements.txt as the build command in Leapcell’s UI.

---

What You Now Have

• A working FastOpp instance on Leapcell.

• Postgres configured with SSL.

• Persistent S3-compatible object storage and a CDN URL.

• Admin access to seed demos and manage content.

From here you can remove demo modules, keep the base stack, and start building your features. The same deployment flow applies as you customize FastOpp for production use.

Try building your first project and let us know about it!