In the last post we built a tiny FastAPI agent: it answers general questions directly and calls a get_weather tool (Open-Meteo, no key) only for weather queries. We ran the whole thing with a single docker compose up.
This time we focus on reliability and portability without rewriting Python. Two small files do the heavy lifting:
- Dockerfile — freezes the environment (exact Python + pinned libraries).
- compose.yaml — declares how to run (ports, env vars, health, restart).
A simple mental model
- Dockerfile = the image: your code plus a fixed Python and pinned dependencies.
- compose.yaml = the runtime: how that image runs — ports, env vars, health checks, restart policy.
To change how it runs, edit compose.yaml; to change what’s inside, edit the Dockerfile — not your app code.
Dockerfile — same interpreter, same libs, every time
What it is: a tiny recipe for your runtime image.
Why it matters: no “works on my machine,” fast rebuilds (cached deps), clear contract for teammates and CI.
Minimal template
FROM python:3.12-slim
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 PIP_NO_CACHE_DIR=1
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY agent.py tools.py ./
# Optional but recommended: drop root privileges
RUN useradd -u 10001 -m appuser
USER appuser
EXPOSE 8000
CMD ["uvicorn", "agent:app", "--host", "0.0.0.0", "--port", "8000"]
Concepts to remember
- Base image pins the interpreter and OS libs.
requirements.txtkeeps dependency installs deterministic.- Dropping root is a small, high-value hardening step.
compose.yaml — one file that says how to run
What it is: a declarative runtime contract you can share and version.
Why it matters: one command runs the same stack everywhere; you get operability (health, restart) without touching code.
services:
agent:
build: .
env_file: .env
ports: ["8000:8000"]
restart: unless-stopped
healthcheck:
test: ["CMD", "wget", "-qO-", "http://localhost:8000/docs"]
interval: 10s
timeout: 3s
retries: 10
Concepts to remember
- Ports expose your API; env_file injects config at start time.
- Restart and healthcheck add resilience and readiness with zero code changes.
- When you add a cache/DB/proxy later, you just add another service here.
Two tiny helpers
requirements.txt— pin Python dependencies to prevent version drift (e.g., matchingopenaiandhttpx)..env— hold runtime settings and secrets (e.g.,OPENAI_API_KEY) that Compose injects at start; don’t bake them into images.
What breaks without these — and how this setup fixes it

Everyday ops
docker compose logs -f agent
docker compose build --no-cache
docker compose down
Production-Ready Next Steps
- Profiles & overrides: keep
compose.yamlsimple; addcompose.prod.yamlfor stricter prod settings—still no code changes. - Add a cache/DB/proxy: declare new services in Compose; the wiring stays in YAML.
- Scale out later: introduce a lightweight proxy and run multiple
agentreplicas—again, mostly Compose edits.
This two-part series shows how Docker Compose turns a fragile prompt app into a small, dependable AI agent service you can share and scale.
Part 1 builds a FastAPI agent that answers normally and, only for weather questions, calls a get_weather tool using Open-Meteo (no API key); the Dockerfile, compose.yaml, pinned requirements.txt, and a .env make it one-command, reproducible, and tidy.
Part 2 focuses on concepts: the Dockerfile locks the environment (exact Python + deps) while compose.yaml defines the runtime (ports, env, health, restart), giving reliability and a clean path to grow—add services or scale—by editing Compose rather than rewriting code.



Comments