Module 2: Local & Container Deployment

1. Introduction: Local & Container Deployment

Overview

This is the first capsule of Module 2. Here you'll understand why local deployment with Docker Compose multi-container is the base of everything that comes in this guide — and why "local" doesn't mean "toy." A well-configured local environment replicates production faithfully: same service structure, same networking configuration, same health checks. The difference from production is where it runs, not how it's configured.

Why it matters: You already made an informed decision in Module 1 with your decision matrix. Regardless of which strategy you chose, mastering local deployment with Docker Compose is fundamental. It's your development environment, your staging, and for many cases it's legitimate production. Modules 4 (LocalStack), 6 (migration), and 8 (capstone) build on the Compose you configure here.

Where Are We in the Guide?

Context

Phase 1: Deployment Strategies (Modules 1-3)
├── Module 1: Understanding Deployment Options    ✅ COMPLETED
├── Module 2: Local & Container Deployment        ← YOU ARE HERE
└── Module 3: Serverless & Lambda for AI

Phase 2: Cloud Infrastructure & Migration (Modules 4-6)
Phase 3: Alternatives & Production (Modules 7-8)

Transition from Module 1

In Module 1 you built a framework to decide. Here you start to implement. The first strategy you master is local deployment because:

It's the base of your daily development
Docker Compose is portable to any platform
Your local environment must replicate production
LocalStack (M4) integrates as a service in your Compose

What Docker Compose Multi-Container Is for AI

From one container to a system

The Docker guide (#15) taught you to containerize your app: one Dockerfile, one container, one service. But a production AI app isn't a single container:

Simple AI app (1 container):
└── FastAPI + OpenAI SDK

Production AI app (3-5 containers):
├── FastAPI (API gateway)
├── Redis (response cache)
├── ChromaDB/Qdrant (vector store)
├── Worker (async processing)
└── Nginx (reverse proxy + SSL)

Docker Compose orchestrates all these containers as a system: it brings them up in the right order, connects their networks, shares volumes, and verifies that each one is healthy before accepting traffic.

The restaurant analogy

A single container is like a chef who cooks, serves, and charges. It works if you have 5 customers. Docker Compose is like an organized restaurant: chef in the kitchen, waiters serving, cashier charging, each with their role and communicating with each other. If the chef isn't ready, the waiters wait. If the register fails, the restaurant keeps cooking but doesn't charge.

Each category in code

So you see the concrete difference, this is what each pattern looks like:

# A single container (Docker guide #15)
docker run -p 8000:8000 my-ai-app

# Docker Compose multi-container (this module)
# docker-compose.yml
services:
  api:
    build: ./api
    ports:
      - "8000:8000"
    depends_on:
      cache:
        condition: service_healthy
  cache:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]

# One command brings up the whole system
docker compose up -d

# One command shuts it down
docker compose down

The key difference: with docker run you manage each container manually. With Compose, you declare your whole system in one file and Compose orchestrates it for you.

This Module's Technologies

Tool	Version	What it does in this module
Docker Compose	v2.20+	Orchestrates multi-container
FastAPI	0.115+	API gateway of your AI app
Redis	7.x	LLM response cache
Python	3.10+	The app's language
OpenAI SDK	1.0+	LLM calls
Pydantic	2.0+	Config and request validation
curl	-	Health checks and testing

Reference architecture

                    ┌──────────────────────────────────────────┐
                    │         Docker Compose Network           │
                    │                                          │
  User Request ──→  │  ┌─────────┐      ┌─────────┐           │
                    │  │ FastAPI  │ ←──→ │  Redis   │           │
                    │  │ :8000   │      │  :6379  │           │
                    │  │         │      │ (cache) │           │
                    │  │ /health │      └─────────┘           │
                    │  │ /ask    │                             │
                    │  └─────────┘                             │
                    │       │                                  │
                    │       ↓                                  │
                    │  OpenAI API (external)                   │
                    └──────────────────────────────────────────┘

Each service runs in its own container, with its own filesystem, its own internal network, and its own health checks. Docker Compose makes sure the ordering, communication, and persistence work without manual intervention.

Module Objective

By the end of this module you'll be able to:

✅ Design a Docker Compose file for a multi-container AI app (FastAPI + Redis + AI service)
✅ Implement environment configuration per environment (dev, staging, prod)
✅ Configure volumes for persistent data and networking between services
✅ Implement health checks that verify each service's real readiness
✅ Define correct dependency ordering between services
✅ Debug local deployment with docker compose logs, exec, and troubleshooting
✅ Handle secrets and API keys safely without committing to Git

Professional objective

When you need to show your AI app to a colleague, a manager, or an investor, you'll run docker compose up and in 30 seconds you'll have a multi-service system running with health checks, cache, and production-like configuration. That's professional local deployment.

Module Roadmap

#	Capsule	What you'll learn	Type
01	Introduction (this one)	Context, objectives, setup	Intro
02	Docker Compose for AI Apps	Compose file, services, networks, volumes	Technical
03	Environment Configuration	Variables per environment, .env files, overrides	Technical
04	Health Checks and Dependencies	Readiness checks, dependency ordering, restart policies	Technical
05	Networking and Communication	Internal networks, ports, service discovery	Technical
06	Debugging Local Deployment	Logs, exec, troubleshooting AI apps	Technical
07	Secrets and Local Security	API keys, .env, Docker secrets, gitignore	Technical
08	Project: Local Multi-Container AI App	Complete Compose with FastAPI + Redis + AI	Project

Estimated duration: 1.25-1.5 hours.

Prerequisites

What you already know (from the Docker guide #15)

✅ What a Dockerfile, image, and container are
✅ How to build and run a container
✅ Basic commands: docker build, docker run, docker ps
✅ Dockerizing a FastAPI app

What you'll learn here (new)

Docker Compose multi-service (not just one container)
Orchestration: ordering, health checks, dependencies
Environment config per environment
Local deployment debugging
Local secrets management

Technical Setup

Verify tools

# Docker
docker --version
# Docker version 24.0+ expected

# Docker Compose (v2, integrated in Docker Desktop)
docker compose version
# Docker Compose version v2.20+ expected

# Python
python --version
# Python 3.10+ expected

Create the project structure

mkdir -p module-02/{api,worker}
cd module-02

# Initial structure
# module-02/
# ├── api/
# │   ├── main.py
# │   ├── requirements.txt
# │   └── Dockerfile
# ├── worker/
# │   ├── worker.py
# │   ├── requirements.txt
# │   └── Dockerfile
# ├── docker-compose.yml
# ├── docker-compose.override.yml
# ├── .env
# └── .env.example

OpenAI API key

You need an OpenAI API key for this module's examples. If you don't have one:

Go to platform.openai.com
Create an account (or use the existing one)
Go to API Keys → Create new secret key
Copy the key (starts with sk-proj-...)

# Create a .env file in your working directory
echo "OPENAI_API_KEY=sk-proj-your-key-here" > .env

# NEVER commit this file to Git
echo ".env" >> .gitignore

The examples use gpt-4o-mini, which is the cheapest model (~$0.15/1M input tokens). A full practice module shouldn't cost you more than $0.50.

Quick verification

# Verify that Docker works
docker run --rm hello-world

# Verify that Compose works
echo 'services:
  test:
    image: alpine
    command: echo "Compose works!"' > test-compose.yml

docker compose -f test-compose.yml up
# Expected output: "Compose works!"

rm test-compose.yml

Verify everything together

# Quick full verification script
echo "=== Docker ===" && docker --version \
  && echo "=== Compose ===" && docker compose version \
  && echo "=== Python ===" && python --version \
  && echo "=== OpenAI key ===" && ([ -f .env ] && echo ".env exists ✅" || echo ".env missing ❌") \
  && echo "=== All checks passed ==="

If everything shows correct versions and .env exists, you're ready for capsule 02.

Connection to the Project

This module's project: Local Multi-Container AI App

You'll build a complete Docker Compose with:

FastAPI as the API gateway (receives requests, processes them)
Redis as the response cache (avoids repeated LLM calls)
Worker (optional) for asynchronous processing

User Request
    ↓
┌─────────────────────┐
│ FastAPI (api)        │
│ Port 8000            │
│ ├── /health          │
│ ├── /ask             │──→ Check Redis cache
│ └── /ask (cache miss)│──→ Call OpenAI → Store in Redis
└─────────────────────┘
         ↕
┌─────────────────────┐
│ Redis (cache)        │
│ Port 6379 (internal) │
│ Response cache       │
└─────────────────────┘

This Compose extends in later modules:

M4: Add LocalStack as a service (local S3, Lambda)
M6: Use as a development environment for migration to AWS
M8: Base of the system deployed in production

Compose evolution throughout the guide:

M2: FastAPI + Redis (base)
 ↓
M4: FastAPI + Redis + LocalStack (local S3/Lambda)
 ↓
M6: Same Compose, code that works against LocalStack AND AWS
 ↓
M8: Local Compose → CI/CD → Production platform

The Compose you build in this module isn't a throwaway exercise. It's the guide's central artifact — the base on which you add layers of complexity module by module.

What is NOT a prerequisite (you learn it here)

Some concepts you might think you need to know but that this module teaches you:

Concept	Do you need it beforehand?	Where you learn it
Docker Compose syntax	No	Capsule 02
.env files and overrides	No	Capsule 03
Health checks	No	Capsule 04
Docker networking	No	Capsule 05
Docker debugging	No	Capsule 06
Secrets management	No	Capsule 07

Limits: What This Module Does NOT Cover

❌ Docker from scratch — Prerequisite: Docker Essentials Guide (#15)
❌ Kubernetes — Enterprise-scale orchestration, out of scope
❌ Cloud deployment — That comes in Modules 3-8
❌ Docker Swarm — Compose is enough for this guide's scope
❌ CI/CD setup — Prerequisite: CI/CD for AI Systems Guide (#16)

Signs of Success

By the end of this module:

✅ docker compose up brings up your multi-container AI app in <30 seconds
✅ The health checks verify that each service is operational
✅ Redis caches responses and reduces LLM calls
✅ You can switch between dev and staging configuration with a flag
✅ You know how to diagnose when a service doesn't start (logs, exec, networking)
✅ The API keys aren't in your code or in Git

Quick self-assessment

If you can answer these questions at the end of the module, you've mastered it:

Why does an AI app need more than one container?
What problem does depends_on with condition: service_healthy solve?
What's the difference between ports and expose in Compose?
How do you switch between dev and staging configuration without modifying the Compose file?
What's the first thing you do when a service doesn't start?

If any seems hard now, don't worry — the answers become clear across the 8 capsules.

Summary

Docker Compose multi-container is the base of professional deployment for AI apps.
A well-configured local environment replicates production — it's not a toy.
A typical AI app has 3-5 services: API, cache, vector store, worker, reverse proxy.
This module covers the 7 key skills: Compose files, env config, health checks, networking, debugging, secrets, and capstone project.
This module builds the Compose that gets reused in M4 (LocalStack), M6 (migration), and M8 (production).
The final project is a multi-container AI app with a working FastAPI + Redis.
Prerequisite: Docker Essentials Guide (#15). If you know how to do docker build and docker run, you're ready.

Additional Resources

Docker Compose Documentation — Complete official reference
Docker Compose File Reference — Compose file specification
FastAPI Docker Deployment — Official FastAPI guide with Docker
Redis Docker Hub — Official Redis image
Docker Networking Overview — Networking in Docker
Docker Compose Best Practices — Compose in production

← Previous8. Project: Deployment Decision Workshop Next →2. Docker Compose for AI Apps