Principle:Langchain ai Langgraph Docker Image Building
| Property | Value |
|---|---|
| Concept | Building Production Docker Images from LangGraph Project Configuration |
| Category | Containerization |
| Scope | CLI Deployment Workflow |
| Related Workflow | CLI_Deployment |
Overview
Docker Image Building in LangGraph is the process of transforming a project configuration and local graph code into a self-contained Docker image suitable for production deployment. The LangGraph CLI generates a Dockerfile dynamically from the project's `langgraph.json` configuration, installs all declared dependencies, copies local packages into the container, rewrites import paths for the container filesystem, and bakes environment variables into the image. The resulting image extends the official LangGraph API server base image and can be deployed to any Docker-compatible hosting environment.
Description
Containerization Strategy
LangGraph adopts a single-stage Docker build strategy that layers application code and dependencies on top of an official base image (`langchain/langgraph-api` for Python projects or `langchain/langgraphjs-api` for Node.js projects). The base image contains the LangGraph API server runtime, and the generated Dockerfile adds:
- Custom Dockerfile lines from the configuration.
- PyPI dependencies via `pip install` or `uv pip install`.
- Local package requirements files.
- Local "real" packages (with `pyproject.toml` or `setup.py`).
- Local "faux" packages (bare directories with generated packaging metadata).
- All local packages installed in editable mode via `pip install -e .`.
- Environment variables encoding graph definitions, store configuration, authentication, and other runtime settings.
Dockerfile Generation
The Dockerfile is generated programmatically by the `config_to_docker` function, which dispatches to either `python_config_to_docker` or `node_config_to_docker` based on the project's language. For Python projects, the generated Dockerfile follows this structure:
- `FROM <base_image>:<tag>` with the appropriate Python version and distro.
- Custom `dockerfile_lines` injected by the user.
- Installation of PyPI dependencies with constraint files.
- Copying of local dependency directories into `/deps/`.
- Generation of `pyproject.toml` files for faux packages.
- Editable installation of all local packages under `/deps/`.
- Setting of environment variables (`LANGSERVE_GRAPHS`, `LANGGRAPH_STORE`, `LANGGRAPH_AUTH`, etc.).
- Optional JavaScript dependency installation for UI components.
- Cleanup of build tools (`pip`, `setuptools`, `wheel`) from the final image.
- Setting the working directory.
Dependency Packaging
The build system handles several dependency packaging concerns:
- Constraint files: All pip installations use `-c /api/constraints.txt` from the base image to prevent version conflicts with the API server's own dependencies.
- Package installer selection: Supports `pip`, `uv` (a faster Rust-based installer), or `auto` (which selects `uv` for compatible base images).
- pip configuration: An optional `pip_config_file` can be specified for custom package indices or authentication.
- Build tool cleanup: After installation, `pip`, `setuptools`, and `wheel` are removed from the final image to reduce attack surface and image size (configurable via `keep_pkg_tools`).
Image Tagging
The base image tag is constructed from multiple components:
- API version (if specified).
- Language identifier (`py` for Python, `node` for Node.js).
- Runtime version (e.g., `3.11`).
- Distribution suffix (e.g., `-wolfi`, `-bookworm`; omitted for the default `debian`).
For example: `langchain/langgraph-api:3.11` or `langchain/langgraph-api:0.2.18-py3.12-wolfi`.
Usage
Building an Image
# Build a Docker image with a tag
langgraph build -t my-app
# Build with a specific base image
langgraph build -t my-app --base-image langchain/langgraph-server:0.2.18
# Build without pulling the latest base image
langgraph build -t my-app --no-pull
# Build with a pinned API version
langgraph build -t my-app --api-version 0.2.18
# Pass additional Docker build arguments
langgraph build -t my-app --platform linux/amd64
Generating a Dockerfile Without Building
# Generate a standalone Dockerfile
langgraph dockerfile ./Dockerfile
# Generate with Docker Compose support files
langgraph dockerfile ./Dockerfile --add-docker-compose
Theoretical Basis
Containerization
Containerization encapsulates an application and its dependencies into an isolated, portable unit. Docker images provide a reproducible execution environment where the same image produces identical behavior regardless of the host system. For LangGraph, this means a graph application tested locally via `langgraph dev` will behave identically when deployed as a Docker container.
Dockerfile Generation
Generating Dockerfiles programmatically from a higher-level configuration ensures consistency and reduces the expertise required to containerize a LangGraph application. Developers declare what their application needs (dependencies, graphs, environment variables), and the build system determines how to package it. This abstraction eliminates common Dockerfile errors (incorrect layer ordering, missing dependencies, insecure practices) and provides guardrails such as constraint files and build tool cleanup.
Multi-Language Support
The build system's dispatch between Python and Node.js Dockerfile generation reflects the polyglot nature of modern AI applications. By supporting both runtimes in a unified configuration format, LangGraph enables teams to choose the best language for each component while maintaining a single deployment workflow.
Image Size Optimization
The post-installation cleanup of build tools (`pip`, `setuptools`, `wheel`) follows Docker best practices for minimizing image size and reducing the attack surface of production images. The `keep_pkg_tools` configuration option provides an escape hatch for applications that require these tools at runtime (e.g., for dynamic package installation).