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

Method 1: Docker Compose (Recommended)

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

Prerequisites

Install these tools on your system:

• Docker (version 20.10+)
• Docker Compose (version 1.29+)

Installation Steps

1. Get the template:

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

2. Set up environment:

   cp src/.env.example src/.env
   # Edit src/.env with your configuration

3. Start services:

   docker compose up -d

4. 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

2. Install uv (Python package manager):

   pip install uv

3. Install PostgreSQL:

   # On Ubuntu/Debian
   sudo apt install postgresql postgresql-contrib
   
   # On macOS
   brew install postgresql
   
   # On Windows
   # Download from postgresql.org

4. 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

2. Install Python dependencies:

   uv sync

3. Set up environment variables:

   cp src/.env.example src/.env
   # Edit src/.env with your local database/Redis settings

4. 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

5. Run database migrations:

   cd src
   uv run alembic upgrade head

6. Create admin user:

   uv run python -m src.scripts.create_first_superuser

7. Start the application:

   uv run uvicorn src.app.main:app --reload --host 0.0.0.0 --port 8000

8. 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
• Pre-commit for code quality

Installation Steps

1. Fork and clone:

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

2. Install development dependencies:

   uv sync --group dev

3. Set up pre-commit hooks:

   uv run pre-commit install

4. Set up development environment:

   cp src/.env.example src/.env
   # Configure for development

5. 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/services/v1/health
3. Database Connection: Check logs for successful connection
4. Redis Connection: Test caching functionality
5. 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:

• Check the GitHub Issues for common problems
• Search existing issues
• Create a new issue with details