Skip to content

Installation Guide

This guide covers different ways to install and set up the FastAPI Boilerplate depending on your needs and environment.

System Requirements

Before you begin, ensure your system meets these requirements:

  • Python: 3.11 or higher
  • Operating System: Linux, macOS, or Windows (with WSL2 recommended)
  • Memory: Minimum 4GB RAM (8GB recommended)
  • Disk Space: At least 2GB free space

Docker Compose is the easiest way to get started. It handles all dependencies and services automatically.

Prerequisites

Install these tools on your system:

Installation Steps

  1. Get the template:
git clone https://github.com/benavlabs/fastapi-boilerplate cd fastapi-boilerplate
  1. Quick setup (recommended):
# Interactive setup - choose your deployment type ./setup.py  # Or specify directly: ./setup.py local, ./setup.py staging, ./setup.py production

This automatically copies the correct Dockerfile, docker-compose.yml, and .env files for your chosen deployment scenario.

  1. Start services:
docker compose up -d

Manual Setup Alternative

If you prefer to set up manually:

# Copy configuration files for local development cp scripts/local_with_uvicorn/Dockerfile Dockerfile cp scripts/local_with_uvicorn/docker-compose.yml docker-compose.yml  cp scripts/local_with_uvicorn/.env.example src/.env # Edit src/.env with your configuration if needed
  1. Verify installation:
curl http://localhost:8000/docs

What Gets Installed

Docker Compose sets up these services:

  • Web server (FastAPI + Uvicorn) on port 8000
  • PostgreSQL database on port 5432 (internal)
  • Redis server on port 6379 (internal)
  • ARQ Worker for background tasks
  • NGINX (optional, for production)

Method 2: Manual Installation

For more control or development purposes, you can install everything manually.

Prerequisites

  1. Install Python 3.11+:
# On Ubuntu/Debian sudo apt update sudo apt install python3.11 python3.11-pip  # On macOS (with Homebrew) brew install python@3.11  # On Windows # Download from python.org
  1. Install uv (Python package manager):
pip install uv
  1. Install PostgreSQL:
# On Ubuntu/Debian sudo apt install postgresql postgresql-contrib  # On macOS brew install postgresql  # On Windows # Download from postgresql.org
  1. Install Redis:
# On Ubuntu/Debian sudo apt install redis-server  # On macOS brew install redis  # On Windows # Download from redis.io

Installation Steps

  1. Clone the repository:
git clone https://github.com/benavlabs/fastapi-boilerplate cd fastapi-boilerplate
  1. Install Python dependencies:
uv sync
  1. Set up environment variables:
cp src/.env.example src/.env # Edit src/.env with your local database/Redis settings
  1. Set up PostgreSQL:
# Create database and user sudo -u postgres psql CREATE DATABASE myapp; CREATE USER myuser WITH PASSWORD 'mypassword'; GRANT ALL PRIVILEGES ON DATABASE myapp TO myuser; \q
  1. Run database migrations:
cd src uv run alembic upgrade head
  1. Create admin user:
uv run python -m src.scripts.create_first_superuser
  1. Start the application:
uv run uvicorn src.app.main:app --reload --host 0.0.0.0 --port 8000
  1. Start the worker (in another terminal):
uv run arq src.app.core.worker.settings.WorkerSettings

Method 3: Development Setup

For contributors and advanced users who want to modify the boilerplate.

Additional Prerequisites

  • Git for version control

Installation Steps

  1. Fork and clone:
# Fork the repository on GitHub first git clone https://github.com/yourusername/fastapi-boilerplate cd fastapi-boilerplate
  1. Install development dependencies:
uv sync --group dev
  1. Set up pre-commit hooks:
uv run pre-commit install
  1. Set up development environment:
cp src/.env.example src/.env # Configure for development
  1. Run tests to verify setup:
uv run pytest

Docker Services Breakdown

Understanding what each Docker service does:

Web Service

web:  build: .  ports:  - "8000:8000"  depends_on:  - db  - redis
  • Runs the FastAPI application
  • Handles HTTP requests
  • Auto-reloads on code changes (development)

Database Service

db:  image: postgres:13  environment:  POSTGRES_DB: myapp  POSTGRES_USER: postgres  POSTGRES_PASSWORD: changethis
  • PostgreSQL database server
  • Persistent data storage
  • Automatic initialization

Redis Service

redis:  image: redis:alpine  command: redis-server --appendonly yes
  • In-memory data store
  • Used for caching and job queues
  • Persistent storage with AOF

Worker Service

worker:  build: .  command: arq src.app.core.worker.settings.WorkerSettings  depends_on:  - redis
  • Background task processor
  • Handles async jobs
  • Scales independently

Configuration

Environment Variables

The application uses environment variables for configuration. Key variables:

# Database POSTGRES_USER=postgres POSTGRES_PASSWORD=changethis POSTGRES_SERVER=localhost # or "db" for Docker POSTGRES_PORT=5432 POSTGRES_DB=myapp  # Redis REDIS_CACHE_HOST=localhost # or "redis" for Docker REDIS_CACHE_PORT=6379  # Security SECRET_KEY=your-secret-key-here ALGORITHM=HS256 ACCESS_TOKEN_EXPIRE_MINUTES=30

Database Connection

For manual installation, update your database settings:

# Local PostgreSQL POSTGRES_SERVER=localhost POSTGRES_PORT=5432  # Docker PostgreSQL POSTGRES_SERVER=db POSTGRES_PORT=5432

Verification

After installation, verify everything works:

  1. API Documentation: http://localhost:8000/docs
  2. Health Check: http://localhost:8000/api/v1/health
  3. Ready Check: http://localhost:8000/api/v1/ready
  4. Database Connection: Check logs for successful connection
  5. Redis Connection: Test caching functionality
  6. Background Tasks: Submit a test job

Troubleshooting

Common Issues

Port Already in Use:

# Check what's using port 8000 lsof -i :8000  # Kill the process kill -9 <PID>

Database Connection Error:

# Check PostgreSQL status sudo systemctl status postgresql  # Restart PostgreSQL sudo systemctl restart postgresql

Redis Connection Error:

# Check Redis status redis-cli ping  # Start Redis redis-server

Permission Errors:

# Fix Docker permissions sudo usermod -aG docker $USER # Log out and back in

Docker Issues

Clean Reset:

# Stop all containers docker compose down  # Remove volumes (⚠️ deletes data) docker compose down -v  # Rebuild images docker compose build --no-cache  # Start fresh docker compose up

Next Steps

After successful installation:

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

Need Help?

If you encounter issues: