Principle:Langchain ai Langgraph Docker Deployment
| Property | Value |
|---|---|
| Concept | Deploying a LangGraph Application as a Docker Compose Stack with API Server and Database |
| Category | Container Orchestration |
| Scope | CLI Deployment Workflow |
| Related Workflow | CLI_Deployment |
Overview
Docker Deployment in LangGraph refers to running a complete LangGraph application stack using Docker Compose. The deployment stack comprises multiple services: the LangGraph API server, a PostgreSQL database (with pgvector for vector search), a Redis instance for task queuing, and optionally a debugger service for LangGraph Studio. The `langgraph up` command orchestrates the entire lifecycle -- building the application image, generating the Docker Compose configuration, launching all services, and monitoring health checks until the application is ready.
Description
Service Composition
A LangGraph Docker deployment consists of the following services:
LangGraph API Server (`langgraph-api`)
The main application service, running the LangGraph API server with the user's graph definitions. It is either built from the project configuration (inline Dockerfile) or uses a pre-built image specified via the `--image` flag. The service:
- Exposes the API on the configured port (default 8123).
- Receives `REDIS_URI` and `POSTGRES_URI` environment variables.
- Includes health checks via `/api/healthcheck.py`.
- Depends on Redis and PostgreSQL being healthy before starting.
PostgreSQL (`langgraph-postgres`)
A `pgvector/pgvector:pg16` database instance that provides:
- Persistent storage for checkpoints, thread state, and store data.
- Vector search capabilities via the pgvector extension.
- A data volume (`langgraph-data`) for persistence across restarts.
- Health checks via `pg_isready`.
The PostgreSQL service can be omitted by providing an external `--postgres-uri`.
Redis (`langgraph-redis`)
A `redis:6` instance that provides:
- Task queue management for the API server.
- Health checks via `redis-cli ping`.
Debugger (`langgraph-debugger`)
An optional `langchain/langgraph-debugger` service that provides a local LangGraph Studio UI. It is activated by specifying `--debugger-port` and connects to the API server for graph visualization and interactive testing.
Health Check Strategy
The deployment uses Docker health checks to ensure service dependencies are met before starting dependent services:
- PostgreSQL must respond to `pg_isready` before the API server starts.
- Redis must respond to `redis-cli ping` before the API server starts.
- On Docker 25.0+, `start_interval` is set to 1 second for faster initial health check polling, with a longer `interval` of 60 seconds for steady-state monitoring.
Build Integration
When no pre-built image is specified, the `up` command performs an inline Docker build:
- The Dockerfile is generated by `config_to_docker` and embedded directly in the Docker Compose YAML via `dockerfile_inline`.
- The build context is set to the configuration file's parent directory.
- Additional build contexts are added for local dependencies in parent directories.
Watch Mode
The `--watch` flag enables Docker Compose's file watching feature:
- Monitors the configuration file and all local dependency directories.
- Automatically triggers a rebuild when files change.
- Provides a Docker-based analog to the development server's hot-reload capability.
Usage
Basic Deployment
# Launch the full stack
langgraph up
# Launch on a custom port
langgraph up --port 9000
# Launch with a specific config
langgraph up -c ./prod/langgraph.json
Using a Pre-Built Image
# Skip building, use an existing image
langgraph up --image my-app:latest
# Use without pulling
langgraph up --image my-app:latest --no-pull
External Database
# Connect to an external PostgreSQL
langgraph up --postgres-uri "postgres://user:pass@host:5432/db"
Development with Watch Mode
# Auto-rebuild on file changes
langgraph up --watch
Theoretical Basis
Container Orchestration
Docker Compose provides declarative multi-container orchestration. By defining the entire application stack in a single Compose file, LangGraph ensures that all services are started in the correct order with proper networking, volume mounts, and environment variable injection. This eliminates manual service management and reduces deployment errors.
Service Composition
The microservices pattern separates the API server, database, and cache into independent, replaceable components. Each service can be scaled, updated, or replaced independently. The PostgreSQL service can be swapped for an external managed database, and the Redis service provides a standard interface for task queuing.
Health Checks
Health checks implement the circuit breaker pattern at the container level. By verifying that each service is ready before starting dependent services, the deployment avoids race conditions where the API server attempts to connect to an unready database. The dual-interval strategy (fast start-up polling, slow steady-state polling) optimizes both startup time and runtime overhead.
Production Deployment
The Docker Compose stack generated by `langgraph up` serves as both a local testing environment and a template for production deployment. The `--wait` flag enables headless operation suitable for CI/CD pipelines, while the `--detach` behavior allows the stack to run in the background. For production, users can export the generated Docker Compose configuration (via `langgraph dockerfile --add-docker-compose`) and customize it for their infrastructure.