#Deploy and Host Full Stack FastAPI with MongoDB

Full Stack FastAPI + MongoDB

A production-ready full stack application template: the official Full Stack FastAPI Template with MongoDB as the database instead of PostgreSQL.

What's inside

⚡ FastAPI backend (Python 3.14) with automatic interactive API docs at /docs
🍃 PyMongo talking to MongoDB: documents in users and items collections, a unique index on user email, and idempotent seeding of the first superuser at boot
🔑 JWT (OAuth2 password flow) authentication, argon2 password hashing with transparent bcrypt upgrade on login
🚀 React + TypeScript frontend (Vite, Tailwind CSS, shadcn/ui), built into the backend image and served by FastAPI on the same domain — no separate web host, no CORS setup
✉️ React Email templates for account and password-reset emails
✅ Full backend test suite (Pytest, 58 tests) run in CI
🐋 One multi-stage Dockerfile: Bun builds the frontend, uv manages the Python runtime

The backend exposes the same OpenAPI schema as the original template, so the generated type-safe frontend client works unchanged.

After deploying

Open your generated Railway domain — the login page is served by FastAPI.
Sign in with the FIRST_SUPERUSER email and FIRST_SUPERUSER_PASSWORD you configured.
Explore the API at /docs.

Deploy and Host

Deploy this template and you get two services on Railway:

Backend — a Dockerized FastAPI application that serves both the REST API (under /api/v1) and the built React frontend from a single port. On every deploy it runs backend/scripts/prestart.sh, which creates the email unique index and seeds the first superuser if it does not exist yet, then serves with fastapi run on the port Railway provides. Railway health-checks the redirect-free GET /health endpoint, so the deployment only goes live once the app is actually serving.
MongoDB — a Railway MongoDB database. The backend connects to it through the MONGODB_URI variable, which references the database's own connection string (${{Mongo.MONGO_URL}}), so credentials stay in sync automatically.

Set these variables on the backend service when deploying: PROJECT_NAME, SECRET_KEY, FIRST_SUPERUSER, FIRST_SUPERUSER_PASSWORD (generate SECRET_KEY and the password — the app refuses to boot with the default changethis values outside development), and FRONTEND_HOST set to https://${{RAILWAY_PUBLIC_DOMAIN}} so CORS allows the generated domain automatically.

About Hosting

Hosting this stack on Railway means one web service plus one managed database. The frontend is built into the backend image, so there is nothing else to host: API and UI share one domain and one deployment. Deploys are atomic from Railway's point of view — the healthcheck on /health gates the switch to the new deployment, and database seeding is idempotent, so redeploys are safe against existing data. MongoDB runs as a Railway database service with automated backups available on Pro; the backend stores users (with hashed passwords) and items as documents and never needs schema migrations, which removes the Alembic migration step the original template requires on every deploy.

Why Deploy

Zero-migration database workflow: MongoDB is schemaless — the template creates indexes and seeds data at boot, so you never run migration commands when you change your models.
One service, one domain: the React frontend is compiled into the FastAPI app, so you deploy a single container; no CDN, reverse proxy, or CORS configuration needed.
Everything included out of the box: JWT auth with secure password hashing, user and item CRUD with role-based permissions, password recovery emails, and a type-safe frontend client generated from the OpenAPI schema.
CI-tested: the same code you deploy is validated by the backend test suite on every push.

Common Use Cases

SaaS products and internal admin tools that need accounts, roles (superuser vs normal user), and CRUD dashboards out of the box.
Rapid prototyping of API + SPA products when you want to iterate on data models without managing SQL migrations.
Teams standardizing on MongoDB who still want the FastAPI development experience: typed Pydantic models, OpenAPI docs, and generated frontend clients.
A starting point for FastAPI + MongoDB projects that keeps parity with the official full-stack-fastapi-template structure, so upstream improvements are easy to port.

Dependencies for template

Railway MongoDB plugin (Mongo service): provides the MONGO_URL variable referenced as MONGODB_URI by the backend. Provisioned automatically with the template.
Backend service variables: PROJECT_NAME, SECRET_KEY, FIRST_SUPERUSER, FIRST_SUPERUSER_PASSWORD, FRONTEND_HOST (your generated Railway domain).
Docker: the backend builds from the repo-root Dockerfile (frontend build stage + Python runtime stage). No other runtime dependencies are required.