Full Stack FastAPI Template

1. What is Full Stack FastAPI Template?

Full Stack FastAPI Template is a ready-made skeleton for a complete web application, maintained by the team behind FastAPI. Instead of wiring every part together yourself, you start with a site that already has sign-in, a user admin screen, a database, password-recovery emails and automatically generated API documentation. Your job is to turn it into your own product.

To be direct: this is a tool for developers, not an app you use as it is. When you run it you only see a sample admin dashboard with an "Items" section for adding, editing and deleting test data. The value is in the source code underneath.

The template is MIT licensed: free, modifiable, and fine for commercial projects. Running it on your own computer costs nothing. You only pay once you put it online, for whatever server or hosting service you choose.

A good fit if:

• You are learning Python or React and want to see how a real project is organised.
• You need a fast start for a web product with accounts and a database.
• You are willing to type a few commands and read error messages.

Not a good fit if:

• You want a website without writing code. Look for a drag-and-drop builder instead.
• You have no programming background and expect something that works right after installing.
• Your computer is low on memory or disk space: Docker has to download and run several services at once.

2. What do you need first?

Computer: Windows, macOS or Linux. It does not run on a phone. The project does not publish minimum hardware requirements.

Accounts: a free GitHub account if you want your own copy through the "Use this template" button. No API key is needed to run it locally.

Software to install beforehand:

Software	What it is	Needed for	Where to get it
Git	Downloads and tracks source code	Both routes	https://git-scm.com/downloads
Docker Desktop	Runs services in isolated "containers" so you do not install each one on your machine	Both routes	https://www.docker.com/
uv	Installs Python and Python packages	Route B only	https://docs.astral.sh/uv/
Bun	Runs the frontend and installs its packages	Route B only	https://bun.sh/

Beginners should take Route A: only Git and Docker. Route B is for when you start changing code and want to see each change immediately.

3. Step-by-step installation

Step 1: Create your own copy

Open https://github.com/fastapi/full-stack-fastapi-template, click Use this template near the top, choose Create a new repository, name it and create it. This is the method the project itself recommends.

What success looks like: GitHub takes you to a new repository under your account containing the backend and frontend folders and a compose.yml file.

Step 2: Download your copy

Replace <your-account> and <your-repo> with your GitHub account name and the repository name you just chose:

git clone https://github.com/<your-account>/<your-repo>.git
cd <your-repo>

What success looks like: git clone finishes without an error and you are now inside the project folder.

Step 3: Start Docker Desktop

Open the Docker Desktop app and wait until it reports that it is running. Check with:

docker compose version

What success looks like: one line showing a Docker Compose version number. If you get an error, see section 5.

Step 4 (Route A): Run everything with Docker Compose

From the project's root folder, run these in order:

docker compose run --rm backend bash scripts/prestart.sh

This prepares the database and creates the first admin account. The first run is slow because Docker has to download and build the pieces.

docker compose watch

This starts every service and keeps the terminal window busy. Leave that window open.

What success looks like: http://localhost:8000 shows a sign-in page in your browser. The documentation says the first start may take about a minute before all services are ready.

Step 4 (Route B): Development mode with uv and Bun

Here only the database and the test mailbox run in Docker; everything else runs directly on your machine.

From the root folder:

docker compose up -d db mailpit

Move into backend, install the packages, prepare the database and start the API server:

cd backend
uv sync
uv run bash scripts/prestart.sh
uv run fastapi dev

Open a second terminal window in the project's root folder (not backend):

bun install
bun run dev

What success looks like: http://localhost:5173 shows the sign-in page and http://localhost:8000/docs shows the API documentation.

Note: On Windows, commands containing bash scripts/prestart.sh need a bash environment. Git for Windows includes Git Bash; alternatively use Route A, where bash runs inside the container.

4. First use

1. Open the .env file in the root folder with a text editor. Find FIRST_SUPERUSER (the email, admin@example.com by default) and FIRST_SUPERUSER_PASSWORD (the password).
2. Open the sign-in page (http://localhost:8000 on Route A, http://localhost:5173 on Route B) and log in with those two values.
3. Go to Items and add a new entry. It appears in the list. That data travelled through the API and was stored in the PostgreSQL database.
4. Open http://localhost:8000/docs. This is the interactive API documentation: every server endpoint can be tried right on the page.
5. Open http://localhost:8025. This is Mailpit, a fake inbox for development. Try the forgotten-password flow and the email lands here instead of being sent for real.

Addresses you get:

Address	What it is	Route A	Route B
http://localhost:8000	The application (frontend and API)	Yes	API only
http://localhost:5173	Frontend development server	No	Yes
http://localhost:8000/docs	Interactive API docs	Yes	Yes
http://localhost:8025	Mailpit test inbox	Yes	Yes
http://localhost:8080	Adminer, a database admin page	Yes	No
http://localhost:8090	Traefik dashboard (the router)	Yes	No

When you are ready to change things: data models live in backend/app/models.py, API endpoints in backend/app/api/, and the user interface in the frontend folder.

5. Common problems and fixes

Port 8000 is already taken

• Symptom: docker compose watch fails to bind port 8000 (usually with "port is already allocated" or "address already in use").
• Cause: uv run fastapi dev is still running, or another program is using port 8000. The project docs point out that the manually started server and the Compose backend share this port.
• Fix: stop the manual server (Ctrl+C in its window) and run the command again. The same can happen with ports 80, 5432, 8025, 8080 and 8090, which the template also uses.

Docker cannot be reached

• Symptom: docker commands answer "Cannot connect to the Docker daemon" or "docker: command not found".
• Cause: Docker Desktop is not running, or is not installed.
• Fix: open Docker Desktop, wait until it is up and try again. If you have just installed it, close and reopen the terminal.

The page does not load after starting

• Symptom: http://localhost:8000 refuses to connect even though the command showed no error.
• Cause: the services are still starting.
• Fix: wait a little longer, and read the logs with the command below to see which service is stuck.

docker compose logs backend

Changes to .env have no effect

• Symptom: you changed a password or the project name in .env, but the app behaves as before.
• Cause: containers read environment variables when they start.
• Fix: stop (Ctrl+C) and run docker compose watch again.

Frontend edits do not show on port 8000

• Symptom: on Route B the page on port 5173 has changed, but port 8000 still shows the old one.
• Cause: port 8000 serves a pre-built copy of the frontend.
• Fix: go into the frontend folder and rebuild it.

bun run build

uv or Bun is missing

• Symptom: "uv: command not found" or "bun: command not found".
• Cause: not installed, or the terminal was opened before installing.
• Fix: install from the links in section 2 and reopen the terminal. Or use Route A, which needs neither tool.

6. Uninstalling and updating

Stopping: press Ctrl+C in the window running docker compose watch, then run:

docker compose down

Removing everything: the following is a standard Docker Compose command. It stops all services and also deletes the data stored in the test database:

docker compose down -v

Then delete the project folder. Docker Desktop, Git, uv and Bun can be removed like any other application if you no longer need them.

Updating: because you created your copy with "Use this template", your project is fully separate from the original and does not receive new versions automatically. The template's documentation does not describe a way to pull upstream changes. Follow release-notes.md and the Releases page of the original repository to see what is new, then apply what you need by hand. The latest release at the time of writing is 0.12.0 (12 August 2026).

7. Frequently asked questions

Does it cost anything? Not while it runs on your own machine. Once you put it online you pay whoever hosts it. The project ships two deployment guides: deployment.md (FastAPI Cloud) and deployment-docker-compose.md (your own server with Docker Compose). Check the official page of the service you choose for prices.

Do I need an internet connection? During installation, yes: Docker, uv and Bun download their components. After that the app runs entirely on your computer at localhost.

Is my data sent anywhere? When run locally, data stays in the PostgreSQL database that Docker runs on your machine. Emails are not delivered to the outside world; Mailpit captures them for you to read.

Are the passwords in the .env file safe? The included .env holds development defaults only and is public in the repository. The documentation says not to keep production secrets there; when you deploy, generate fresh keys and passwords as the two deployment guides explain.

What if I only want the API and no frontend? That works. frontend/README.md has a "Removing the Frontend" section listing each step.