LangGraph Tutorial (Python): deploying with Docker for beginners

This tutorial shows you how to package a small LangGraph app into a Docker image and run it locally like a real service. You need this when your graph works on your laptop but you want a repeatable runtime for deployment, CI, or handing it off to someone else.

What You'll Need

• •Python 3.11+
• •Docker Desktop or Docker Engine installed
• •A valid OPENAI_API_KEY
• •Basic familiarity with LangGraph StateGraph
• •These Python packages:
  • •langgraph
  • •langchain-openai
  • •python-dotenv

Step-by-Step

1. •Start with a minimal graph that calls an LLM and returns a response. Keep the state small and explicit so the container stays easy to debug.

# app.py
from typing import TypedDict

from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, START, END


class State(TypedDict):
    question: str
    answer: str


llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)


def answer_node(state: State) -> dict:
    response = llm.invoke(state["question"])
    return {"answer": response.content}


graph_builder = StateGraph(State)
graph_builder.add_node("answer", answer_node)
graph_builder.add_edge(START, "answer")
graph_builder.add_edge("answer", END)

app = graph_builder.compile()

2. •Add a small entrypoint so you can run the graph from the command line inside the container. This is the easiest way to prove the image works before wiring in an API server.

# run.py
import os
from dotenv import load_dotenv

from app import app

load_dotenv()

if __name__ == "__main__":
    result = app.invoke({"question": "What is LangGraph?"})
    print(result["answer"])

3. •Create a locked-down dependency file and install only what you need. In Docker, fewer moving parts means fewer surprises when you rebuild later.

# requirements.txt
langgraph==0.2.38
langchain-openai==0.1.25
python-dotenv==1.0.1

4. •Add a Dockerfile that copies your code, installs dependencies, and runs the script. Use a slim Python base image so the final image stays small enough for local development and CI.

FROM python:3.11-slim

WORKDIR /app

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app.py run.py ./

CMD ["python", "run.py"]

5. •Pass your API key at runtime instead of baking it into the image. That keeps secrets out of your build artifacts and matches how you should deploy this in practice.

# .env
OPENAI_API_KEY=your_openai_api_key_here

6. •Build and run the container locally. If everything is wired correctly, the container will execute the graph and print the model output to stdout.

docker build -t langgraph-demo .
docker run --rm --env-file .env langgraph-demo

Testing It

If the container starts successfully, you should see a plain text answer printed in your terminal instead of a stack trace. That tells you Docker can install dependencies, load environment variables, and execute your LangGraph app.

If it fails, check these first:

• •The OPENAI_API_KEY value is present in .env
• •Your Dockerfile copied both app.py and run.py
• •The package versions in requirements.txt are compatible with each other

A good next test is changing the prompt in run.py and rebuilding the image to confirm your code changes are actually being picked up. If you want faster iteration, mount your source directory as a volume during local development instead of rebuilding every time.

Next Steps

• •Wrap this same graph in FastAPI so Docker runs an HTTP service instead of a one-shot script.
• •Add structured state with multiple nodes, then persist checkpoints using LangGraph’s checkpointer support.
• •Push the image to a registry like ECR or Docker Hub and deploy it behind an internal API gateway.

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.