Update deployments section + hosting for app deployment control plane (#1106)

katmayb · lnhsingh · web-flow · commit e96586a178c5 · 2025-10-28T11:42:57.000-04:00
Fixes DOC-398, DOC-399

It was a little confusing to find app deployment instructions for
self-hosted and Hybrid instances. The Deployment tab only covered Cloud
(GitHub-based) deployments.

This PR creates clear separation between infrastructure setup (one-time)
and application deployment (ongoing):

New file:
- deploy-with-control-plane.mdx - Guide for deploying apps to
Hybrid/Self-hosted with control plane using Docker images
Updated files:
- deploy-hybrid.mdx &amp; deploy-self-hosted-full-platform.mdx - Removed app
deployment steps, now focus just on infrastructure setup
- deployments.mdx - Updated to show all three deployment paths (Cloud,
Hybrid/Self-hosted with control plane, Standalone servers)

---------

Co-authored-by: Lauren Hirata Singh &lt;lauren@langchain.dev&gt;
diff --git a/src/docs.json b/src/docs.json
@@ -1153,12 +1153,19 @@
               "langsmith/local-server",
               "langsmith/app-development",
               {
-                "group": "Deploy to Cloud",
+                "group": "Deploy to cloud",
                 "pages": [
                   "langsmith/deployment-quickstart",
                   "langsmith/deploy-to-cloud"
                 ]
               },
+              {
+                "group": "Deploy to self-hosted or hybrid",
+                "pages": [
+                  "langsmith/deploy-with-control-plane",
+                  "langsmith/deploy-standalone-server"
+                ]
+              },
               {
                 "group": "Configure for deployment",
                 "pages": [
diff --git a/src/langsmith/deploy-hybrid.mdx b/src/langsmith/deploy-hybrid.mdx
@@ -13,11 +13,6 @@ The [**hybrid**](/langsmith/hybrid) model lets you run the [data plane](/langsmi
 
 The following steps describe how to connect your self-hosted data plane to the managed LangSmith control plane.
 
-## Prerequisites
-
-1. Use the [LangGraph CLI](/langsmith/cli) to [test your application locally](/langsmith/local-server).
-2. Use the [LangGraph CLI](/langsmith/cli) to build a Docker image (i.e. `langgraph build`) and push it to a registry your Kubernetes cluster or Amazon ECS cluster has access to.
-
 ## Kubernetes
 
 ### Prerequisites
@@ -90,8 +85,9 @@ The following steps describe how to connect your self-hosted data plane to the m
       langgraph-dataplane-operator-6b88879f9b-t76gk   1/1     Running             0          26s
       langgraph-dataplane-redis-0                     1/1     Running             0          25s
     ```
-7. Create a deployment from the [control plane UI](/langsmith/control-plane#control-plane-ui).
-    1. Select the desired listener from the list of `Compute IDs` in the dropdown menu.
-    2. Select the Kubernetes namespace to deploy to.
-    3. Fill out all other required fields and select `Submit` in the top-right of the panel.
-    4. The deployment will be deployed on the Kubernetes cluster where the listener is deployed and in the Kubernetes namespace specified in step 7b.
+
+    Your hybrid infrastructure is now ready to create deployments.
+
+## Next steps
+
+Once your infrastructure is set up, you're ready to deploy applications. See the deployment guides in the [Deployment tab](/langsmith/deployments) for instructions on building and deploying your applications.
diff --git a/src/langsmith/deploy-self-hosted-full-platform.mdx b/src/langsmith/deploy-self-hosted-full-platform.mdx
@@ -28,9 +28,7 @@ This guide builds on top of the [Kubernetes installation guide](/langsmith/kuber
 
 1. You are using Kubernetes.
 2. You have an instance of [self-hosted LangSmith](/langsmith/kubernetes) running.
-3. Use the [LangGraph CLI](/langsmith/cli) to [test your application locally](/langsmith/local-server).
-4. Use the [LangGraph CLI](/langsmith/cli) to build a Docker image (i.e. `langgraph build`) and push it to a registry your Kubernetes cluster has access to.
-5. `KEDA` is installed on your cluster.
+3. `KEDA` is installed on your cluster.
 ```bash
   helm repo add kedacore https://kedacore.github.io/charts
   helm install keda kedacore/keda --namespace keda --create-namespace
@@ -77,4 +75,9 @@ As of v0.12.0, the `langgraphPlatform` option is deprecated. Use `config.deploym
 ```
 4. In your `values.yaml` file, configure the `hostBackendImage` and `operatorImage` options (if you need to mirror images)
 5. You can also configure base templates for your agents by overriding the base templates [here](https://github.com/langchain-ai/helm/blob/main/charts/langsmith/values.yaml#L898).
-6. You create a deployment from the [control plane UI](/langsmith/control-plane#control-plane-ui).
+
+    Your self-hosted infrastructure is now ready to create deployments.
+
+## Next steps
+
+Once your infrastructure is set up, you're ready to deploy applications. See the deployment guides in the [Deployment tab](/langsmith/deployments) for instructions on building and deploying your applications.
diff --git a/src/langsmith/deploy-with-control-plane.mdx b/src/langsmith/deploy-with-control-plane.mdx
@@ -0,0 +1,126 @@
+---
+title: Deploy with control plane
+sidebarTitle: With control plane
+icon: "cloud-arrow-up"
+---
+
+This guide shows you how to deploy your applications to [hybrid](/langsmith/hybrid) or [self-hosted](/langsmith/self-hosted) instances with a [control plane](/langsmith/control-plane). With a control plane, you build Docker images locally, push them to a registry that your Kubernetes cluster has access to, and deploy them with the [LangSmith UI](https://smith.langchain.com).
+
+<Note>
+**This guide is for deploying applications, not setting up infrastructure.**
+
+Before using this guide, you must have already completed infrastructure setup:
+- **[Hybrid setup](/langsmith/deploy-hybrid)**: For hybrid hosting.
+- **[Self-hosted with deployment setup](/langsmith/deploy-self-hosted-full-platform)**: For self-hosted with control plane.
+
+If you haven't set up your infrastructure yet, start with the [Hosting section](/langsmith/hosting).
+</Note>
+
+## Overview
+
+Applications deployed to hybrid or self-hosted LangSmith instances with control plane use Docker images. In this guide, the application deployment workflow is:
+
+1. Test your application locally using `langgraph dev` or [Studio](/langsmith/studio).
+1. Build a Docker image using the `langgraph build` command.
+1. Push the image to a container registry accessible by your infrastructure.
+1. Deploy from the [control plane UI](/langsmith/control-plane#control-plane-ui) by specifying the image URL.
+
+## Prerequisites
+
+Before completing this guide, you'll need the following:
+
+- Completed infrastructure setup to enable your [data plane](/langsmith/data-plane) to receive application deployments:
+  - [Hybrid setup](/langsmith/deploy-hybrid): Installs data plane components (listener, operator, CRDs) in your Kubernetes cluster that connect to LangChain's managed control plane.
+  - [Self-hosted with deployment setup](/langsmith/deploy-self-hosted-full-platform): Enables deployment management on your self-hosted LangSmith instance.
+- Access to the [LangSmith UI](https://smith.langchain.com) with deployment management enabled.
+- A container registry accessible by your Kubernetes cluster.
+
+## Step 1. Test locally
+
+Before deploying, test your application locally. You can use the [LangGraph CLI](/langsmith/cli#dev) to run a LangGraph server in development mode:
+
+```bash
+langgraph dev
+```
+
+For a full guide local testing, refer to the [Local server quickstart](/langsmith/local-server).
+
+## Step 2. Build Docker image
+
+Build a Docker image of your application using the [`langgraph build`](/langsmith/cli#build) command:
+
+```bash
+langgraph build -t my-image
+```
+
+Build command options include:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-t, --tag TEXT` | Required | Tag for the Docker image |
+| `--platform TEXT` | | Target platform(s) to build for (e.g., `linux/amd64,linux/arm64`) |
+| `--pull / --no-pull` | `--pull` | Build with latest remote Docker image |
+| `-c, --config FILE` | `langgraph.json` | Path to configuration file |
+
+Example with platform specification:
+
+```bash
+langgraph build --platform linux/amd64 -t my-image:v1.0.0
+```
+
+For full details, see the [CLI reference](/langsmith/cli#build).
+
+## Step 3. Push to container registry
+
+Push your image to a container registry accessible by your Kubernetes cluster. The specific commands depend on your registry provider.
+
+<Tip>
+Tag your images with version information (e.g., `my-registry.com/my-app:v1.0.0`) to make rollbacks easier.
+</Tip>
+
+## Step 4. Deploy with the control plane UI
+
+The [control plane UI](/langsmith/control-plane#control-plane-ui) allows you to create and manage deployments, view logs and metrics, and update configurations. To create a new deployment in the [LangSmith UI](https://smith.langchain.com):
+
+1. In the left-hand navigation panel, select **Deployments**.
+1. In the top-right corner, select **+ New Deployment**.
+1. In the deployment configuration panel, provide:
+   - **Image URL**: The full image URL you pushed in [Step 3](#step-3-push-to-container-registry).
+   - **Listener/Compute ID**: Select the listener configured for your infrastructure.
+   - **Namespace**: The Kubernetes namespace to deploy to.
+   - **Environment variables**: Any required configuration (API keys, etc.).
+   - Other deployment settings as needed.
+1. Select **Submit**.
+
+The control plane will coordinate with your [data plane](/langsmith/data-plane) listener to deploy your application.
+
+After creating a deployment, the infrastructure is [provisioned asynchronously](/langsmith/control-plane#asynchronous-deployment). Deployment can take up to several minutes, with initial deployments taking longer due to database creation.
+
+From the control plane UI, you can view build logs, server logs, and deployment metrics including CPU/memory usage, replicas, and API performance. For more details, refer to the [control plane monitoring documentation](/langsmith/control-plane#monitoring).
+
+<Note>
+A [LangSmith Observability tracing project](/langsmith/observability) is automatically created for each deployment with the same name as the deployment. Tracing environment variables are set automatically by the control plane.
+</Note>
+
+## Update deployment
+
+To deploy a new version of your application, create a [new revision](/langsmith/control-plane#revisions):
+
+Starting from the LangSmith UI:
+
+1. In the left-hand navigation panel, select **Deployments**.
+1. Select an existing deployment.
+1. In the Deployment view, select **+ New Revision** in the top-right corner.
+1. Update the configuration:
+   - Update the **Image URL** to your new image version.
+   - Update environment variables if needed.
+   - Adjust other settings as needed.
+1. Select **Submit**.
+
+## Next steps
+
+- **[Control plane](/langsmith/control-plane)**: Learn more about control plane features.
+- **[Data plane](/langsmith/data-plane)**: Understand data plane architecture.
+- **[Observability](/langsmith/observability)**: Monitor your deployments with automatic tracing.
+- **[Studio](/langsmith/studio)**: Test and debug deployed applications.
+- **[LangGraph CLI](/langsmith/cli)**: Full CLI reference documentation.
diff --git a/src/langsmith/deployments.mdx b/src/langsmith/deployments.mdx
@@ -13,17 +13,13 @@ This section covers how to package, build, and deploy your _agents_ and applicat
 A typical deployment workflow consists of the following steps:
 
 1. **[Test locally](/langsmith/local-server)**: Run your application on a local server.
-2. **[Choose hosting](/langsmith/hosting)**: Select Cloud, Hybrid, or Self-hosted.
-3. **Deploy your app**: Push code or build images to your chosen environment.
+2. **[Choose hosting](/langsmith/hosting)**: (Required for deployment) Select Cloud, Hybrid, or Self-hosted.
+3. **Deploy your app**:
+   - [**Cloud**](/langsmith/deploy-to-cloud): Push code from a git repository
+   - [**Hybrid or Self-hosted with control plane**](/langsmith/deploy-with-control-plane): Build and push Docker images, deploy via UI
+   - [**Standalone servers**](/langsmith/deploy-standalone-server): Deploy directly without control plane
 4. **[Monitor & manage](/langsmith/observability)**: Track traces, alerts, and dashboards.
 
-<Info>
-**Prerequisites:** Before deploying applications, you need a LangSmith instance to deploy to. Choose a [hosting option](/langsmith/hosting) first:
-- [**Cloud**](/langsmith/cloud): Fully managed with automated CI/CD from a Git repository.
-- [**Hybrid**](/langsmith/hybrid): Enterprise option for data residency requirements.
-- [**Self-hosted**](/langsmith/self-hosted): Full control and data isolation.
-</Info>
-
 ## What you'll learn
 
 - Configure your [app for deployment](/langsmith/application-structure) (dependencies, [project setup](/langsmith/setup-app-requirements-txt), and [monorepo support](/langsmith/monorepo-support)).
diff --git a/src/langsmith/evaluation.mdx b/src/langsmith/evaluation.mdx
@@ -4,6 +4,8 @@ sidebarTitle: Overview
 mode: wide
 ---
 
+import HostingSetup from '/snippets/langsmith/hosting-setup-note.mdx';
+
 The following sections help you create datasets, run evaluations, and analyze results:
 
 <Columns cols={3}>
@@ -63,3 +65,5 @@ The following sections help you create datasets, run evaluations, and analyze re
   </Card>
 
 </Columns>
+
+<HostingSetup/>
diff --git a/src/langsmith/hosting.mdx b/src/langsmith/hosting.mdx
@@ -4,10 +4,12 @@ sidebarTitle: Hosting LangSmith
 mode: wide
 ---
 
-This section covers how to host and manage **LangSmith**: the infrastructure, services, and datastores that power your observability, evaluation, and agent deployment capabilities.
+This section covers how to host and manage LangSmith infrastructure. You have the flexibility of setting up LangSmith for [observability](/langsmith/observability), [evaluation](/langsmith/evaluation), and [prompt engineering](/langsmith/prompt-engineering) features or using the full platform that also includes optional [LangSmith Deployment](/langsmith/deployments) features for deploying your applications through the UI.
 
 <Callout icon="building" color="#2563EB" iconType="regular">
-**Start here if you're setting up or maintaining LangSmith infrastructure.** If you're ready to deploy your agent application, the [Deployment section](/langsmith/deployments) covers application structure, deployment configuration, and guides for deploying to Cloud.
+**Start here if you're setting up or maintaining LangSmith infrastructure.**
+
+If you want to deploy an agent application, the [Deployment section](/langsmith/deployments) covers application structure and deployment configuration.
 </Callout>
 
 ## Choose your hosting option
@@ -25,7 +27,7 @@ You'll deploy LangSmith in one of three modes:
     href="/langsmith/cloud"
     cta="Get started"
   >
-    Run all components fully managed in LangChain’s cloud.
+    Fully managed observability, evaluation, prompt engineering, and application deployment. Deploy from GitHub with automated CI/CD.
   </Card>
 
   <Card
@@ -34,7 +36,7 @@ You'll deploy LangSmith in one of three modes:
     href="/langsmith/hybrid"
     cta="Set up Hybrid"
   >
-    **(Enterprise)** Manage the data plane running in your cloud while LangChain manages the control plane.
+    **(Enterprise)** Observability, evaluation, prompt engineering, and application deployment with your applications running in your infrastructure.
   </Card>
 
   <Card
@@ -44,7 +46,7 @@ You'll deploy LangSmith in one of three modes:
     href="/langsmith/self-hosted"
     cta="Run self-hosted"
   >
-    **(Enterprise)** Run the full LangSmith or run standalone LangGraph Servers without the control plane UI.
+    **(Enterprise)** Full control with observability, evaluation, and prompt engineering. Optionally add application deployment or run standalone servers.
   </Card>
 </Columns>
 
diff --git a/src/langsmith/observability.mdx b/src/langsmith/observability.mdx
@@ -4,6 +4,8 @@ sidebarTitle: Overview
 mode: wide
 ---
 
+import HostingSetup from '/snippets/langsmith/hosting-setup-note.mdx';
+
 The following sections help you set up and use tracing, monitoring, and observability features:
 
 <Columns cols={3}>
@@ -63,3 +65,5 @@ The following sections help you set up and use tracing, monitoring, and observab
 </Columns>
 
 For terminology definitions and core concepts, refer to [Observability concepts](/langsmith/observability-concepts).
+
+<HostingSetup/>
diff --git a/src/langsmith/prompt-engineering.mdx b/src/langsmith/prompt-engineering.mdx
@@ -4,6 +4,8 @@ sidebarTitle: Overview
 mode: wide
 ---
 
+import HostingSetup from '/snippets/langsmith/hosting-setup-note.mdx';
+
 The following sections help you create, manage, and optimize your prompts:
 
 <Columns cols={3}>
@@ -62,3 +64,5 @@ The following sections help you create, manage, and optimize your prompts:
   </Card>
 
 </Columns>
+
+<HostingSetup/>
diff --git a/src/langsmith/self-hosted.mdx b/src/langsmith/self-hosted.mdx
@@ -8,7 +8,7 @@ sidebarTitle: Overview
 Self-hosted LangSmith is an add-on to the Enterprise plan designed for our largest, most security-conscious customers. For more details, refer to [Pricing](https://www.langchain.com/pricing). [Contact our sales team](https://www.langchain.com/contact-sales) if you want to get a license key to trial LangSmith in your environment.
 </Note>
 
-LangSmith supports different self-hosted configurations depending on your scale, security, and infrastructure needs. This page provides an overview of the supported self-hosted models:
+LangSmith supports different self-hosted configurations depending on your scale, security, and infrastructure needs. **Note that LangSmith Deployment (for deploying your applications) is a separate feature from LangSmith itself (for observability and evaluation).** You do not need LangSmith Deployment to use self-hosted LangSmith. This page provides an overview of the supported self-hosted models:
 
 - **[LangSmith](#langsmith)**: Deploy an instance of the LangSmith application that includes observability, tracing, and evaluations in the UI and API. Best for teams who want self-hosted monitoring and evaluation without deploying agents.
 - **[LangSmith with deployment](#langsmith-with-deployment)**: Deploy a _graph_ to LangGraph Server via the control plane. The control plane and data plane form the full LangSmith platform, providing UI and API management for running and monitoring agents. This includes observability, evaluation, and deployment management.
diff --git a/src/snippets/langsmith/hosting-setup-note.mdx b/src/snippets/langsmith/hosting-setup-note.mdx
@@ -0,0 +1,3 @@
+<Note>
+To set up a LangSmith instance, visit the [Hosting section](/langsmith/hosting) to choose between cloud, hybrid, or self-hosted. All options include observability, evaluation, prompt engineering, and deployment.
+</Note>
