Workflow:Langchain ai Langgraph CLI Deployment
| Knowledge Sources | |
|---|---|
| Domains | LLM_Ops, Deployment, DevOps |
| Last Updated | 2026-02-11 15:00 GMT |
Overview
End-to-end process for deploying a LangGraph application using the CLI, from project configuration through Docker-based production deployment and local development serving.
Description
This workflow covers the full deployment lifecycle of a LangGraph application using the `langgraph-cli` package. It starts with creating a project configuration file (`langgraph.json`) that declares graph definitions, dependencies, and environment settings. The CLI provides commands for local development with hot reloading (`langgraph dev`), Docker-based deployment (`langgraph up`), building production Docker images (`langgraph build`), and generating Dockerfiles for custom deployments (`langgraph dockerfile`). The deployment includes a Postgres database for persistence and connects to LangGraph Studio for visual debugging.
Usage
Execute this workflow when you need to deploy a LangGraph application as a production API server, set up a local development environment with hot reloading, or build Docker images for deployment to cloud infrastructure. This is the standard path for taking a LangGraph application from development to production.
Execution Steps
Step 1: Create the Project Configuration
Create a `langgraph.json` configuration file in your project root. This file declares the graph definitions (Python module paths to compiled graph objects), package dependencies, environment variable files, Python version, and optional Dockerfile customizations. The configuration is the single source of truth for the deployment.
Key considerations:
- The `graphs` field maps graph names to Python module paths (e.g., `"agent": "./my_app.py:graph"`)
- The `dependencies` field lists pip packages and local package paths
- The `env` field points to a `.env` file for environment variables (API keys, etc.)
- Supported Python versions are 3.11 and 3.12
- The `dockerfile_lines` field allows custom Dockerfile instructions
Step 2: Define the Graph Module
Create a Python module that exports a compiled LangGraph graph object. The module path and variable name must match what is declared in `langgraph.json`. The graph should be fully compiled and ready for execution.
Key considerations:
- The module must contain a compiled graph (result of `builder.compile()`)
- The variable name after the colon in the config path must exist at module level
- Multiple graphs can be defined in separate modules and registered in the config
- Import all dependencies at module level for proper dependency resolution
Step 3: Run in Development Mode
Use `langgraph dev` to start a local API server with hot reloading. This runs the graph in-process (requires `langgraph-cli[inmem]` extra) with automatic code change detection, browser-based UI via LangGraph Studio, and debugging support. The development server runs on port 2024 by default.
Key considerations:
- Install with `pip install "langgraph-cli[inmem]"` for development mode
- The server automatically reloads when source files change
- Access the API at `http://localhost:2024` and docs at `http://localhost:2024/docs`
- LangGraph Studio opens automatically for visual graph debugging
- Use `--debug-port` for remote debugger attachment
Step 4: Build the Docker Image
Use `langgraph build -t <tag>` to create a production Docker image. The CLI reads the configuration, generates a Dockerfile from templates, resolves dependencies, and builds the image. The base image includes the LangGraph API server runtime.
Key considerations:
- The `-t` flag specifies the Docker image tag (required)
- Use `--platform` for multi-architecture builds (e.g., `linux/amd64,linux/arm64`)
- Use `--pull` to ensure the latest base image is used
- The build context is the directory containing `langgraph.json`
- Custom base images can be specified with `--base-image`
Step 5: Deploy with Docker Compose
Use `langgraph up` to launch the full deployment stack including the LangGraph API server, Postgres database, and Redis (if configured). The CLI generates a Docker Compose configuration, pulls images, and starts all services. The deployment includes health checks, volume persistence, and optional file watching.
Key considerations:
- The API server runs on port 8123 by default
- A Postgres database is automatically provisioned for checkpoint storage
- Use `--wait` to block until all services are healthy
- Use `--watch` for file-change-triggered rebuilds
- Environment variables require LANGSMITH_API_KEY or LANGGRAPH_CLOUD_LICENSE_KEY
- Use `--postgres-uri` to connect to an existing Postgres instance
Step 6: Connect Remote Clients
Once deployed, connect client applications using the `RemoteGraph` class from `langgraph.pregel.remote` or the Python SDK (`langgraph_sdk`). RemoteGraph implements the same `PregelProtocol` as local graphs, allowing seamless switching between local and remote execution with identical `invoke()`, `stream()`, and state management APIs.
Key considerations:
- `RemoteGraph` connects to the deployed API URL
- The Python SDK provides lower-level HTTP client access
- Both sync and async execution are supported
- State management (get_state, update_state) works identically to local graphs
- Authentication is handled via API keys in headers