Containerise a Python API with Docker

mkdir my-api && cd my-api

# Imports: load FastAPI, HTTP error handling and Pydantic models
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List
import datetime

# Create the FastAPI instance with metadata for Swagger documentation
app = FastAPI(
    title="My API",
    description="Example API containerised with Docker",
    version="1.0.0"
)

# Define the Item data model with Pydantic validation
class Item(BaseModel):
    name: str
    price: float
    in_stock: bool = True

# Simulate an in-memory database for this tutorial
items_db: List[Item] = [
    Item(name="Laptop", price=999.99),
    Item(name="Mouse", price=29.99),
]

# Root GET route: respond with a message and timestamp
@app.get("/")
def root():
    return {
        "message": "API operational 🚀",
        "timestamp": datetime.datetime.now().isoformat()
    }

# GET /items route: return the complete list of items
@app.get("/items", response_model=List[Item])
def get_items():
    """Returns all available items."""
    return items_db

# GET /items/{item_id} route: retrieve a specific item by ID
@app.get("/items/{item_id}", response_model=Item)
def get_item(item_id: int):
    if item_id < 0 or item_id >= len(items_db):
        raise HTTPException(status_code=404, detail="Item not found")
    return items_db[item_id]

# POST /items route: add a new item to the database
@app.post("/items", response_model=Item, status_code=201)
def create_item(item: Item):
    items_db.append(item)
    return item

# GET /health route: verify that the API is operational
@app.get("/health")
def health_check():
    return {"status": "healthy"}

# Modern web framework for building REST APIs
fastapi==0.111.0
# ASGI server for running FastAPI (asynchronous, performant)
uvicorn[standard]==0.29.0
# Data validation and JSON serialisation
pydantic==2.7.0

# Create an isolated virtual environment for this project
python -m venv venv
# Activate the environment (Windows: venv\Scripts\activate)
source venv/bin/activate

# Install dependencies listed in requirements.txt
pip install -r requirements.txt

# Start the API with auto-reload on file changes
uvicorn main:app --reload --port 8000

# ── Official base Python image ──
# python:3.11-slim: lightweight variant (~150MB vs ~1GB for full image)
FROM python:3.11-slim

# ── Environment variables for Python ──
# PYTHONDONTWRITEBYTECODE=1: don't generate unnecessary .pyc files
# PYTHONUNBUFFERED=1: send logs directly to stdout (real-time)
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1

# ── Set the working directory in the container ──
WORKDIR /app

# ── Copy dependencies FIRST ──
# Docker uses cache: if requirements.txt doesn't change, this layer is reused
# Changes to source code won't force a dependency reinstall
COPY requirements.txt .
# --no-cache-dir: don't store pip cache (saves space)
RUN pip install --no-cache-dir --upgrade pip && \
    pip install --no-cache-dir -r requirements.txt

# ── Copy the application source code ──
COPY . .

# ── Port exposed by the application (documentation) ──
# Note: EXPOSE doesn't publish the port, you must use -p in docker run
EXPOSE 8000

# ── Startup command ──
# 0.0.0.0 makes the API accessible from outside the container
# By default, 127.0.0.1 would only be accessible from inside the container
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

# Temporary folders and local environments
venv/
__pycache__/
*.pyc
*.pyo

# Secrets and local configuration (never include in image)
.env
.env.local

# Version control and documentation
.git
.gitignore
*.md

# Cache and test files
.pytest_cache/
.coverage

# Build the Docker image
# -t my-api:v1: give the image a name and tag
# . : use the Dockerfile from the current directory
docker build -t my-api:v1 .

# Verify the image is created and see its size
docker images | grep my-api

# Run a container based on the my-api:v1 image
# -d: detached (background mode, frees the terminal)
# -p 8000:8000: publish port 8000 from container to 8000 on host
#        (without this, the API would only be accessible from inside the container)
# --name api-container: give the container a name (more readable than random ID)
docker run -d -p 8000:8000 --name api-container my-api:v1

# List running containers
docker ps

# Display container logs in real time (-f = follow)
docker logs -f api-container

# Test 1: root route
curl http://localhost:8000/
# Response: {"message":"API operational 🚀","timestamp":"2025-01-15T10:30:00"}

# Test 2: get all items (GET /items)
curl http://localhost:8000/items
# Response: [{"name":"Laptop","price":999.99,"in_stock":true},...]

# Test 3: create a new item (POST /items)
curl -X POST http://localhost:8000/items \
  -H "Content-Type: application/json" \
  -d '{"name":"Keyboard","price":79.99,"in_stock":true}'
# Response: {"name":"Keyboard","price":79.99,"in_stock":true}

# Test 4: health check to verify the API responds
curl http://localhost:8000/health
# Response: {"status":"healthy"}

# Import os to read environment variables
import os
from fastapi import FastAPI

# Read environment variables with defaults
# In production, these values will be overridden by deployment
APP_ENV = os.getenv("APP_ENV", "development")
SECRET_KEY = os.getenv("SECRET_KEY", "change-me-in-production")
DATABASE_URL = os.getenv("DATABASE_URL", "sqlite:///./test.db")

app = FastAPI()

# Endpoint that exposes the current environment (useful for debugging)
@app.get("/")
def root():
    return {"env": APP_ENV, "message": "API operational"}

# Method 1: Pass variables directly with -e
docker run -d -p 8000:8000 \
  -e APP_ENV=production \
  -e SECRET_KEY=my-super-secret \
  -e DATABASE_URL=postgresql://user:pass@db:5432/mydb \
  --name api-prod \
  my-api:v1

# Method 2: Load all variables from a .env file
# (more practical in production, less verbosity)
docker run -d -p 8000:8000 \
  --env-file .env \
  --name api-prod \
  my-api:v1

# Docker Compose syntax version
version: '3.9'

services:
  # ── FastAPI service ──
  api:
    # build: . builds the image from the Dockerfile
    build: .
    ports:
      # Map port 8000 on host to port 8000 in container
      - "8000:8000"
    environment:
      # Environment variables for this container
      - APP_ENV=development
      # @db: the db container is accessible by this hostname (Docker internal network)
      - DATABASE_URL=postgresql://user:password@db:5432/mydb
    depends_on:
      # Wait for db service to be "healthy" before starting API
      db:
        condition: service_healthy
    volumes:
      # Mount the local /app directory in container
      # Enables hot reload: code changes = automatic restart
      - .:/app
    # Command override: run uvicorn with --reload (watch mode)
    command: uvicorn main:app --host 0.0.0.0 --port 8000 --reload

  # ── PostgreSQL service ──
  db:
    # Use PostgreSQL 16 image on Alpine base (ultra-lightweight)
    image: postgres:16-alpine
    environment:
      # Database credentials
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
      POSTGRES_DB: mydb
    volumes:
      # Mount a volume to persist data between restarts
      - postgres_data:/var/lib/postgresql/data
    # Health check: Docker Compose tests if PostgreSQL is ready
    healthcheck:
      # Command to check service health
      test: ["CMD-SHELL", "pg_isready -U user"]
      # Test every 5 seconds
      interval: 5s
      # Command timeout: 5 seconds
      timeout: 5s
      # Retry count before marking service unhealthy
      retries: 5

  # ── Adminer service: web interface for PostgreSQL ──
  adminer:
    # Official image for managing databases graphically
    image: adminer
    ports:
      - "8080:8080"
    # Wait for PostgreSQL to be ready
    depends_on:
      - db

# ── Named volumes ──
# postgres_data: creates a Docker volume to persist PostgreSQL data
# Survives even if container is deleted
volumes:
  postgres_data:

# Start all services defined in docker-compose.yml
# -d: detached mode (background)
docker compose up -d

# View logs from all services in real time
# -f: follow (keep watching for new logs)
docker compose logs -f

# Stop and remove all containers (volume data persists)
docker compose down

# Stop AND remove volumes (completely reset the DB)
# ⚠️ Use with caution: deletes data!
docker compose down -v

# ── Manage containers ──
# List running containers
docker ps

# List all containers (active and stopped)
docker ps -a

# Gracefully stop a container (SIGTERM)
docker stop my-container

# Remove a stopped container
docker rm my-container

# Force immediate container removal (even if running)
docker rm -f my-container

# ── Enter a container (debug interactively) ──
# Open a Bash shell inside the container
docker exec -it my-container bash

# Run a command without interaction
docker exec my-container ls /app

# ── Manage images ──
# List all downloaded/built images
docker images

# Remove a specific image
docker rmi my-api:v1

# Remove images not used by any container
docker image prune

# ── Complete cleanup ──
# Remove unused containers, images, networks and caches
# ⚠️ Drastic: use with caution!
docker system prune -a

my-api/
├── main.py              # FastAPI application code
├── requirements.txt     # Python dependencies
├── Dockerfile           # Docker image recipe
├── docker-compose.yml   # Multi-service orchestration
├── .dockerignore        # Files excluded from image
└── .env                 # Environment variables (don't commit!)