Skip to content

Installation Guide

This guide covers different ways to install the FastAPI Boilerplate depending on your needs.

System Requirements

  • Python: 3.11 or higher
  • Operating System: Linux, macOS, or Windows (WSL2 recommended)
  • Memory: 4GB RAM minimum (8GB recommended)
  • Disk Space: ~2GB free

Docker Compose handles every service for you (Postgres + Redis + the app).

Prerequisites

Steps

  1. Clone the repository:

    git clone https://github.com/benavlabs/fastapi-boilerplate
cd fastapi-boilerplate

  2. Install the workspace:

    uv sync --all-packages --all-extras

  3. Generate the compose file:

    uv run --no-sync bp deploy generate local

    docker-compose.yml is written at the repo root and is not committed, because the stack you want depends on how you deploy. local is the hot-reload stack: API, Taskiq worker, scheduler, Postgres and Redis. The other modes are prod and nginx, covered in CLI → Commands.

  4. Set up the environment file:

    cp backend/.env.example backend/.env
# Edit backend/.env: set SECRET_KEY (`uv run --no-sync bp env gen-secret` prints one),
# change ADMIN_PASSWORD and the default DB password.

  5. Bring up the stack, from the repo root:

    docker compose up

  6. Verify it's running:

    curl http://localhost:8000/health

What Gets Installed

  • App (FastAPI + Uvicorn) on port 8000
  • PostgreSQL on port 5432
  • Redis on port 6379

Method 2: Manual Installation (Local with uv)

For development on your host machine. You provide PostgreSQL and Redis yourself.

Prerequisites

  1. Python 3.11+:

    # Ubuntu/Debian
sudo apt update && sudo apt install python3.11

# macOS
brew install python@3.11

# Windows: download from python.org

  2. uv (fast Python package manager):

    # macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# or via pip
pip install uv

  3. PostgreSQL:

    # Ubuntu/Debian
sudo apt install postgresql postgresql-contrib

# macOS
brew install postgresql

  4. Redis:

    # Ubuntu/Debian
sudo apt install redis-server

# macOS
brew install redis

Steps

  1. Clone the repository:

    git clone https://github.com/benavlabs/fastapi-boilerplate
cd fastapi-boilerplate

    The repo is a uv workspace — the deployable application lives in backend/ and the developer CLI (bp) lives in cli/. Both share a single virtual environment at the repo root.

  2. Install Python dependencies:

    uv sync --all-packages --all-extras

    This syncs the whole workspace — backend, CLI, and dev tools — into one .venv/ at the repo root. From here on, uv run --no-sync <cmd> works from any subdirectory; the flag skips uv's implicit sync, so a command starts immediately and leaves the environment and the lockfile alone. Re-running a plain uv sync without --all-extras is what removes ruff, mypy and pytest again.

  3. Set up environment variables:

    cp backend/.env.example backend/.env
# Edit backend/.env: point POSTGRES_SERVER and CACHE_REDIS_HOST at localhost,
# set a strong SECRET_KEY (or run `uv run --no-sync bp env gen-secret`), etc.

    The CLI ships a few helpers for this step — see CLI → Commands:

    uv run --no-sync bp env gen-secret      # print a fresh SECRET_KEY
uv run --no-sync bp env validate        # audit the .env against the production validator

  4. Set up PostgreSQL (if not already configured):

    sudo -u postgres psql
CREATE DATABASE myapp;
CREATE USER myuser WITH PASSWORD 'mypassword';
GRANT ALL PRIVILEGES ON DATABASE myapp TO myuser;
\q

  5. Run database migrations (from backend/ — alembic looks for alembic.ini in cwd):

    cd backend
uv run --no-sync alembic upgrade head

  6. Create the initial admin user and tier:

    uv run --no-sync python -m scripts.setup_initial_data

  7. Start the app:

    uv run --no-sync fastapi dev src/interfaces/main.py

  8. (Optional) Start a Taskiq worker (in a second terminal):

    uv run --no-sync taskiq worker src.infrastructure.taskiq.worker:default_broker

Method 3: Development Setup

For contributors and anyone modifying the boilerplate itself.

Steps

  1. Fork and clone:

    # Fork on GitHub first
git clone https://github.com/yourusername/fastapi-boilerplate
cd fastapi-boilerplate

  2. Install dev dependencies:

    uv sync --all-packages --all-extras

  3. Set up pre-commit hooks (from the repo root):

    uv run --no-sync pre-commit install

  4. Set up the environment:

    cp backend/.env.example backend/.env

  5. Run the test suite to verify your setup:

    cd backend && uv run --no-sync pytest

Configuration

Environment Variables

The app reads its configuration from backend/.env (see backend/.env.example for the full reference). Common variables:

# Environment
ENVIRONMENT=development

# Database
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=postgres
POSTGRES_SERVER=postgres  # use "localhost" without Docker
POSTGRES_PORT=5432

# Cache (Redis)
CACHE_BACKEND=redis
CACHE_REDIS_HOST=redis    # use "localhost" without Docker
CACHE_REDIS_PORT=6379

# Security
SECRET_KEY=insecure-change-this-in-production

# Initial admin
ADMIN_NAME=Admin User
ADMIN_EMAIL=admin@example.com
ADMIN_USERNAME=admin
ADMIN_PASSWORD=Change-Me-Now-1!

See Environment Variables for the complete reference.

Using a hosted database instead

You don't have to run Postgres yourself. Set DATABASE_URL and it overrides every POSTGRES_* variable above — the local container (or local install) becomes unnecessary:

DATABASE_URL=postgresql+asyncpg://user:password@host.example.com/dbname?ssl=require

Neon — serverless Postgres, and a sponsor of this project — is free to start (a permanent free plan, no credit card) and has a step-by-step guide here, including the connection-string conversion asyncpg needs. Any managed Postgres works the same way.

Verification

After installing, verify everything works:

  1. API Docs: http://localhost:8000/docs
  2. Health Check: curl http://localhost:8000/health
  3. Admin Panel: http://localhost:8000/admin
  4. Database: check the app log for "Database connected" / no errors at startup

Troubleshooting

Port Already in Use

# Find what's on port 8000
lsof -i :8000
kill -9 <PID>

Database Connection Error

# Linux
sudo systemctl status postgresql
sudo systemctl restart postgresql

# macOS (Homebrew)
brew services restart postgresql

Redis Connection Error

redis-cli ping  # should print PONG
# If not, start it:
redis-server

Docker — Clean Reset

From the repository root, where docker-compose.yml is:

docker compose down       # stop containers
docker compose down -v    # also delete volumes (⚠️ wipes data)
docker compose build --no-cache
docker compose up

Next Steps

  1. Configuration Guide - Set up your environment
  2. First Run - Test your installation
  3. Project Structure - Understand the codebase

Need Help?