FastAPIBlueprint

FastAPI Blueprint 02: Project Setup & Environment

Set up a clean, scalable FastAPI project structure that’s ready to handle anything from authentication to analytics.

Kevin Edraki

Kevin Edraki

— 3 min read
FastAPI Blueprint 02: Project Setup & Environment

What You’ll Learn in This Chapter

In the first chapter, we mapped out the architecture for our FastAPI microservice template.
Now it’s time to lay the foundation — the project’s environment and folder structure — so everything is clean, consistent, and easy to extend.

By the end of this chapter, you’ll have:

  • A consistent folder structure for your service
  • Poetry or pip configured with dependencies
  • Environment variable management with .env and Pydantic Settings
  • A running FastAPI app with a /health endpoint from Step 1
  • Ready-to-use Docker setup for containerized development

Why Environment Setup Matters

A microservice template isn’t just about code — it’s about maintainability.
A good setup should let you:

  • Onboard a new developer in minutes
  • Swap databases or message brokers without changing core logic
  • Keep configs out of your codebase and in .env files or secret managers
  • Run locally with minimal fuss, whether via uvicorn or Docker

Skipping this step means your “template” quickly turns into spaghetti that’s hard to reuse.

Folder Structure We’ll Use

We’ll extend the structure from Step 1:

fastapi-blueprint/
├─ pyproject.toml / requirements.txt
├─ .env.example
├─ Dockerfile
├─ docker-compose.yml   <-- added here for local DB/message broker runs
├─ app/
│  ├─ core/             <-- config, logging, constants
│  ├─ api/              <-- versioned routes
│  ├─ domain/           <-- business logic
│  ├─ ports/            <-- interfaces
│  ├─ adapters/         <-- implementations
│  └─ main.py
└─ tests/

Step-by-Step Setup

1. Choose Dependency Manager

We’ll use Poetry in this series, but I’ll include pip equivalents.
Poetry gives you lock files and a cleaner dependency setup.

Poetry:

pip install poetry
poetry init
poetry add fastapi uvicorn[standard] pydantic-settings
poetry add --group dev pytest httpx pytest-asyncio

Pip:

python -m venv .venv
source .venv/bin/activate
pip install fastapi uvicorn[standard] pydantic-settings pytest httpx pytest-asyncio
pip freeze > requirements.txt

2. Create .env and .env.example

We’ll define default configs here:

.env.example

APP_NAME=fastapi-blueprint
APP_ENV=local
API_V1_STR=/api/v1
LOG_LEVEL=INFO

Copy it to .env for local runs:

cp .env.example .env

3. Configure Pydantic Settings

app/core/config.py

from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    app_name: str
    app_env: str
    api_v1_str: str
    log_level: str = "INFO"

    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")

settings = Settings()

4. Update Main App Factory

We’ll extend Step 1’s create_app() to load settings automatically:

app/main.py

from fastapi import FastAPI
from app.core.config import settings
from app.core.logging import setup_logging
from app.api.v1.routes_health import router as health_router

def create_app() -> FastAPI:
    setup_logging(settings.log_level)

    app = FastAPI(
        title=settings.app_name,
        version="0.1.0",
        docs_url="/docs",
        redoc_url="/redoc",
    )

    app.include_router(health_router, prefix=settings.api_v1_str)

    return app

app = create_app()

5. Add Docker Support

Dockerfile (from Step 1) stays mostly the same, but now we add Compose.

docker-compose.yml

version: '3.9'

services:
  app:
    build: .
    container_name: fastapi_blueprint
    ports:
      - "8000:8000"
    env_file: .env
    volumes:
      - .:/app
    command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

6. Test the Setup

Run locally:

poetry run uvicorn app.main:app --reload

or via Docker:

docker compose up --build

Check:

curl http://127.0.0.1:8000/api/v1/health

What’s Next (Step 3 Preview)

In FastAPI Blueprint 03: Core FastAPI Structure, we’ll:

  • Break routes into modules
  • Introduce dependency injection for shared logic
  • Set up API versioning conventions for long-term growth

✅ Checklist for Chapter 2 Completion

  • Poetry or pip installed and configured
  • .env and .env.example created
  • Settings class reads environment variables
  • App loads configs and logging from .env
  • Dockerfile + docker-compose.yml tested locally
  • /health endpoint reachable at http://localhost:8000/api/v1/health

If you want, I can now generate the matching “Step 2” feature image with the same blueprint background as Step 1, but updated to say:
FastAPI Blueprint 02: Project Setup & Environment
That way your series stays visually consistent.

Do you want me to make it?

Read more