full-stack-fastapi-mongodb: a cookiecutter generator that wires auth and Docker for you

A generator that hands you an auth-ready application skeleton

The problem this project addresses is not FastAPI or MongoDB, both of which are well documented elsewhere. The problem is the boring middle layer between them: session handling, password hashing, token refresh, CORS, a background worker, a reverse proxy that terminates TLS, and a frontend that knows how to log in. Teams write that middle layer on every new project and get it slightly wrong in slightly different ways.

full-stack-fastapi-mongodb is a cookiecutter template. Running it produces a directory containing a complete working application rather than a starting stub. The project describes itself as a base project generator for developers who want to build and maintain full-feature progressive web applications, with Python on the backend and TypeScript on the frontend, and who would rather not hand-roll authentication and deployment configuration.

The scope is clear from the repository layout. The top-level entries include cookiecutter.json, a hooks directory, a docs directory with separate guides for building a generated app, development and installation, deployment for production, authentication and magic tokens, and websockets, plus the template directory itself named after the cookiecutter project_slug placeholder. The rendered project ships its own README.md template with development and deployment instructions, so the documentation arrives with the code rather than in a separate wiki.

What you get on generation is a stack with several moving parts already connected: a FastAPI backend with PyMongo and ODMantic on top of MongoDB, generic CRUD support through inheritance, a Next.js and React frontend with React useForm, Redux and TailwindCSS, a Celery worker, Flower for task monitoring, and Traefik in front of both frontend and backend so they share a domain and split by path.

Why a MongoDB fork of the PostgreSQL generators exists

This repository is explicitly an experimental fork of Sebastián Ramírez's Full Stack FastAPI and PostgreSQL Base Project Generator and Whythawk's version of the same project. That lineage explains most of its structure and most of its sharp edges.

The stated version pins are specific: FastAPI 0.103.2, MongoDB Motor 3.4, ODMantic ODM 1.0.0, and the frontend moved to React. The current release line is described as targeting FastAPI 0.103 and introducing support for Pydantic 2, which matters because Pydantic 2 changed validation and serialization behavior in ways that break code written against the older API.

The lineage is also why the project is described as experimental rather than as a supported product. A fork inherits the upstream design decisions, including a decision to make the backend talk to MongoDB instead of PostgreSQL. ODMantic gives you Python models mapped onto MongoDB documents, and the template leans on common CRUD support via generic inheritance, so you write one base model and derive per-entity operations from it.

Because the fork is described as experimental, treat the version pins as part of the contract rather than as a starting point you can freely upgrade. The repository listing includes a THIRD-PARTY-NOTICES.txt alongside the MIT LICENSE file, which is consistent with a codebase derived from other people's projects and carrying attribution for them.

Generating the example application with cookiecutter and Compose

The README asks for Docker Desktop, Python 3.11 or newer, Cookiecutter, Hatch, Node.js and MongoDB Compass before you start. Compass is listed as a requirement because the point of the setup is to inspect the documents the app creates, not just the API responses.

The quick start is one generation command followed by a Compose build. The generator writes into the example directory, and the project name argument also determines the admin email domain, since a project named fullstackexample produces [email protected].

// Make sure cookiecutter and python are installed on the device
// This will generate a full-stack app in the directory ./example
cookiecutter https://github.com/mongodb-labs/full-stack-fastapi-mongodb --no-input project_name="example"

// Move into that directory.
cd example

// Make sure that you've opened the Docker Desktop app before this step.
// build
docker compose build --no-cache

// start the container in the background
docker compose up -d 

Docker Desktop has to be running before the build step because the Compose file builds images locally rather than pulling prebuilt ones, and the no-cache flag forces a full rebuild of the frontend and backend images. Once the containers are up, the frontend is served on port 3000 and container logs are visible in the Docker Desktop app.

The README warns plainly that the result is a local application that is not yet production ready, and it points readers to the getting-started guide before they try to deploy anything.

The six local endpoints a generated project exposes

Traefik sits in front of the frontend and the backend so both answer on the same domain separated by path, and it handles route forwarding and automatic Let's Encrypt certificate generation for production use. In local development that same proxy is what produces the fixed set of URLs the README lists.

The frontend runs at http://localhost:3000 and the backend at http://localhost/api/v1/. Two documentation surfaces come from FastAPI itself: Swagger UI at http://localhost/docs and ReDoc at http://localhost/redoc. The second is worth knowing about because ReDoc is the better fit when you want to hand a schema reference to a frontend team rather than an interactive console.

Two more URLs belong to the supporting infrastructure. Flower, the admin tool for Celery tasks, listens on http://localhost:5555, and the Traefik UI shows how routes are being handled by the proxy at http://localhost:8090. That last one is the debugging entry point when a request lands on the wrong container, which happens often enough when both services share one host.

The API is described as standards-based, built on and compatible with the OpenAPI and JSON Schema specifications. Practically, that means the Swagger UI is generated from the same schemas the frontend consumes, and validation and serialization are automatic rather than hand-written.

The admin account and the credential you must change first

A generated application contains exactly one user, [email protected], with a default password of changethis. The email domain follows the project name, so a project generated as fullstackexample yields [email protected]. This is a deliberate convenience for local exploration and a real liability the moment the app is reachable by anyone else.

The authentication stack behind that account is the most substantial part of the template. Schemas, models, crud helpers and APIs for user management are already built, with OAuth2 JWT token support and default hashing. On top of that sit magic link authentication with password fallback, cookie management, and separate access and refresh tokens.

The magic link path matters for deployment decisions, because email delivery is an operational dependency that no local setup can exercise for you. The authentication guide is a separate document, which tells you the team behind the project treats the login flow as the part most likely to need adjustment. The frontend side is symmetric: authorization is route based, and it can detect both whether a user is logged in and whether that user is a superuser.

Token refresh is handled for you too, but the mechanism is standard JWT issuance rather than a session store, so revocation semantics depend on token expiry and any secret rotation you add yourself.

Celery, Flower and ODMantic behind the API

The background worker is a Celery process that can import and use models and code from the rest of the backend selectively. That selectivity is the design point. In a monorepo-style template, a worker that eagerly imports the whole application package pulls web-only dependencies and settings into the worker process, which makes startup failures harder to read. A selective import mechanism lets you name the modules a given worker needs.

Flower is the operator-facing half of that pair, exposed on port 5555, giving a web view of queued, running and failed tasks. It is included rather than left to the developer, which saves the step of wiring a monitoring tool into a Compose file before you know what your task names will be.

On the persistence side the stack uses PyMongo as the driver and ODMantic as the object document mapper. The key features list names PyMongo for direct driver access, common CRUD support via generic inheritance, and FastAPI's automatic validation, serialization and interactive documentation. The combination means the same schema objects drive request validation, the OpenAPI description and the MongoDB document shape, so a field added to a model appears in the Swagger UI without a separate declaration.

One constraint worth naming comes from the MongoDB choice itself. A document store gives you flexible schemas and horizontal write scaling, but it does not give you multi-document transactions or a relational schema language, so requirements that depend on those need another answer.

Where the template stops short of a production answer

The README states the position plainly: the quick start generates a local application that is not yet production-ready, and it asks you to read the linked documentation before creating a version to deploy to a production host. The deployment guide exists, but the wording places the responsibility for reading it on you rather than promising a turnkey rollout.

Maintenance facts are worth stating without extrapolation. The repository is not archived. The last push was on 2026-06-04. The two releases listed are dated 2024-01-10 and 2023-11-10, so the newest tagged release predates the most recent push by a wide margin and the release trail has not been kept in step with commits to main. The current release line is described as targeting FastAPI 0.103 with Pydantic 2 support, which places the framework baseline where the upstream project was at that point.

Two smaller gaps show up in what is visible. The repository has no homepage, so there is no site of record beyond the README and the docs directory. And the README text itself ends mid-sentence in the release notes area, so the release notes for the current version are not fully readable from the top-level README and live in the release entries or the docs.

The operational gap is the one to weigh. GitHub CI with frontend and backend testing is included, but the continuous integration set up covers the generated project's test commands rather than the template's future upgrades.

What the MIT licence covers and what it does not settle

The project is released under the MIT licence, and the repository carries a LICENSE file together with a THIRD-PARTY-NOTICES.txt. That combination is what you would expect from a fork of two other people's generators: your own generated project can be used, modified and distributed under MIT terms, while the notices file records obligations attached to the code inherited from upstream authors.

This is not legal advice, and the practical point is narrower. The MIT grant from the MongoDB Labs project does not by itself tell you which terms apply to the parts of the template that came from the PostgreSQL generators. Before shipping a product built on the rendered output, read the THIRD-PARTY-NOTICES.txt file that lands in your generated project and confirm the notice obligations are satisfied, and check the licence file of each upstream generator it credits.

The same caution applies to the dependency surface. FastAPI, Motor, ODMantic, Next.js, React, Redux, Celery, Flower and Traefik each carry their own licences, and the pinned versions in the template decide which of those you inherit. The generated README.md is where those instructions are supposed to be gathered, so treat that file as a checklist to work through rather than background reading.

Editorial conclusion

Adopt this generator if your next service is a Python API with a React frontend, MongoDB storage and an OIDC-free email login, and if you are comfortable owning a template fork. Do not adopt it if you need relational transactions, a maintained upstream line of releases, or a documented production rollout path, since the fork labels itself experimental and the newest listed release is 2024-01-10. Before generating anything, read cookiecutter.json and the generated README.md in your target directory to confirm the pinned FastAPI, Motor and ODMantic versions still match the code you plan to write, and replace the default changethis password before exposing the app on any host.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mongodb-labs/full-stack-fastapi-mongodb on GitHub
4. README
5. Releases