docs: deployment overview (#7108)

* sidebars * init * more-content * backend-only-dockerfile * more-content * postgres-page * cleanup * cleanup * multiple-postgres-db * move-content * test * spacing-issue * remove-link-temporarily-for-build * code-review * add-note-for-readOnlyRootFilesystem * Apply suggestions from code review Co-authored-by: KimberlyFields <46325568+KimberlyFields@users.noreply.github.com> * rename-concepts-to-overview * docs: Refactor deployment overview for clarity and conciseness * improve-sentence-add-comma-remove-trailing-spaces * code-review --------- Co-authored-by: KimberlyFields <46325568+KimberlyFields@users.noreply.github.com>
2025-03-27 16:38:19 -04:00 · 2025-03-27 16:38:19 -04:00 · d428d734c6
commit d428d734c6
parent d5bf54831e
5 changed files with 183 additions and 25 deletions
--- a/docs/docs/Configuration/configuration-custom-database.md
+++ b/docs/docs/Configuration/configuration-custom-database.md
@ -4,7 +4,7 @@ slug: /configuration-custom-database
 ---
 Langflow's default database is [SQLite](https://www.sqlite.org/docs.html), but you can configure Langflow to use PostgreSQL instead.

-This guide will walk you through the process of setting up an external database for Langflow by replacing the default SQLite connection string `sqlite:///./langflow.db` with PostgreSQL.
+This guide walks you through setting up an external database for Langflow by replacing the default SQLite connection string `sqlite:///./langflow.db` with PostgreSQL.

 ## Prerequisite

@ -16,13 +16,11 @@ To connect Langflow to PostgreSQL, follow these steps.

 1. Find your PostgreSQL database's connection string.
 It looks like `postgresql://user:password@host:port/dbname`.
-For example, if you started PostgreSQL with this Docker command:

-```
-docker run --name some-postgres -e POSTGRES_PASSWORD=mysecretpassword -d -p 5432:5432 postgres
-```
-
-Your connection string would be `postgresql://some-postgres:mysecretpassword@localhost:5432/postgres`.
+The hostname in your connection string depends on how you're running PostgreSQL.
+- If you're running PostgreSQL directly on your machine, use `localhost`.
+- If you're running PostgreSQL in Docker Compose, use the service name, such as `postgres`.
+- If you're running PostgreSQL in a separate Docker container with `docker run`, use the container's IP address or network alias.

 2. Create a `.env` file for configuring Langflow.
 ```
@ -30,7 +28,7 @@ touch .env
 ```

 3. To set the database URL environment variable, add it to your `.env` file:
-```plaintext
+```text
 LANGFLOW_DATABASE_URL="postgresql://user:password@localhost:5432/dbname"
 ```

@ -42,35 +40,141 @@ Replace the value for `LANGFLOW_DATABASE_URL` with your PostgreSQL connection st

 4. Run Langflow with the `.env` file:
 ```bash
-langflow run --env-file .env
+uv run langflow run --env-file .env
 ```

 5. In Langflow, create traffic by running a flow.
 6. Inspect your PostgreSQL deployment's tables and activity.
-You will see new tables and traffic created.
+New tables and traffic are created.

 ## Example Langflow and PostgreSQL docker-compose.yml

-The Langflow project includes a [`docker-compose.yml`](https://github.com/langflow-ai/langflow/blob/main/docker_example/docker-compose.yml) file  for quick deployment with PostgreSQL.
+The Langflow project includes a [docker-compose.yml](https://github.com/langflow-ai/langflow/blob/main/docker_example/docker-compose.yml) file for quick deployment with PostgreSQL.

-This configuration launches Langflow and PostgreSQL containers, with Langflow pre-configured to use the PostgreSQL database. Customize the database credentials as needed.
+This configuration launches Langflow and PostgreSQL containers in the same Docker network, ensuring proper connectivity between services. It also sets up persistent volumes for both Langflow and PostgreSQL data.

 To start the services, navigate to the `/docker_example` directory, and then run `docker-compose up`.

 ```yaml
 services:
  langflow:
-    image: langflow-ai/langflow:latest
-    environment:
-      - LANGFLOW_DATABASE_URL=postgresql://user:password@postgres:5432/langflow
+    image: langflowai/langflow:latest    # or another version tag on https://hub.docker.com/r/langflowai/langflow
+    pull_policy: always                   # set to 'always' when using 'latest' image
+    ports:
+      - "7860:7860"
    depends_on:
      - postgres
+    environment:
+      - LANGFLOW_DATABASE_URL=postgresql://langflow:langflow@postgres:5432/langflow
+      # This variable defines where the logs, file storage, monitor data, and secret keys are stored.
+      - LANGFLOW_CONFIG_DIR=app/langflow
+    volumes:
+      - langflow-data:/app/langflow

  postgres:
-    image: postgres:15
+    image: postgres:16
    environment:
-      - POSTGRES_USER=user
-      - POSTGRES_PASSWORD=password
-      - POSTGRES_DB=langflow
+      POSTGRES_USER: langflow
+      POSTGRES_PASSWORD: langflow
+      POSTGRES_DB: langflow
+    ports:
+      - "5432:5432"
+    volumes:
+      - langflow-postgres:/var/lib/postgresql/data
+
+volumes:
+  langflow-postgres:    # Persistent volume for PostgreSQL data
+  langflow-data:        # Persistent volume for Langflow data
 ```

+:::note
+Docker Compose creates an isolated network for all services defined in the docker-compose.yml file. This ensures that the services can communicate with each other using their service names as hostnames, for example, `postgres` in the database URL. If you were to run PostgreSQL separately using `docker run`, it would be in a different network and Langflow wouldn't be able to connect to it using the service name.
+:::
+
+## Deploy multiple Langflow instances with a shared database
+
+To configure multiple Langflow instances that share the same PostgreSQL database, modify your `docker-compose.yml` file to include multiple Langflow services.
+
+Use environment variables for more centralized configuration management:
+
+1. Update your `.env` file with values for your PostgreSQL database:
+```text
+POSTGRES_USER=langflow
+POSTGRES_PASSWORD=your_secure_password
+POSTGRES_DB=langflow
+POSTGRES_HOST=postgres
+POSTGRES_PORT=5432
+LANGFLOW_CONFIG_DIR=app/langflow
+LANGFLOW_PORT_1=7860
+LANGFLOW_PORT_2=7861
+LANGFLOW_HOST=0.0.0.0
+```
+2. Reference these variables in your `docker-compose.yml`:
+```yaml
+services:
+  postgres:
+    image: postgres:16
+    environment:
+      - POSTGRES_USER=${POSTGRES_USER}
+      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
+      - POSTGRES_DB=${POSTGRES_DB}
+    ports:
+      - "${POSTGRES_PORT}:5432"
+    volumes:
+      - langflow-postgres:/var/lib/postgresql/data
+
+  langflow-1:
+    image: langflowai/langflow:latest
+    pull_policy: always
+    ports:
+      - "${LANGFLOW_PORT_1}:7860"
+    depends_on:
+      - postgres
+    environment:
+      - LANGFLOW_DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
+      - LANGFLOW_CONFIG_DIR=${LANGFLOW_CONFIG_DIR}
+      - LANGFLOW_HOST=${LANGFLOW_HOST}
+      - PORT=7860
+    volumes:
+      - langflow-data-1:/app/langflow
+
+  langflow-2:
+    image: langflowai/langflow:latest
+    pull_policy: always
+    ports:
+      - "${LANGFLOW_PORT_2}:7860"
+    depends_on:
+      - postgres
+    environment:
+      - LANGFLOW_DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
+      - LANGFLOW_CONFIG_DIR=${LANGFLOW_CONFIG_DIR}
+      - LANGFLOW_HOST=${LANGFLOW_HOST}
+      - PORT=7860
+    volumes:
+      - langflow-data-2:/app/langflow
+
+volumes:
+  langflow-postgres:
+  langflow-data-1:
+  langflow-data-2:
+```
+
+3. Deploy the file with `docker-compose up`.
+You can access the first Langflow instance at `http://localhost:7860`, and the second Langflow instance at `http://localhost:7861`.
+
+4. To confirm both instances are using the same database, run the `docker exec` command to start `psql` in your PostgreSQL container.
+Your container name may vary.
+```bash
+docker exec -it docker-test-postgres-1 psql -U langflow -d langflow
+```
+
+5. Query the database for active connections:
+```sql
+langflow=# SELECT * FROM pg_stat_activity WHERE datname = 'langflow';
+```
+
+6. Examine the query results for multiple connections with different `client_addr` values, for example `172.21.0.3` and `172.21.0.4`.
+
+Since each Langflow instance runs in its own container on the Docker network, using different incoming IP addresses confirms that both instances are actively connected to the PostgreSQL database.
+
+7. To quit psql, type `quit`.
--- a/docs/docs/Deployment/deployment-docker.md
+++ b/docs/docs/Deployment/deployment-docker.md
@ -102,7 +102,7 @@ wget https://raw.githubusercontent.com/langflow-ai/langflow-helm-charts/refs/hea

 3. Create a Dockerfile:
 ```dockerfile
-FROM langflowai/langflow:latest
+FROM langflowai/langflow-backend:latest
 RUN mkdir /app/flows
 COPY ./*json /app/flows/.
 ```
--- a/docs/docs/Deployment/deployment-kubernetes.md
+++ b/docs/docs/Deployment/deployment-kubernetes.md
@ -184,6 +184,14 @@ The runtime chart is tailored for deploying applications in a production environ

 The `langflow-runtime` Helm chart is available in the [Langflow Helm Charts repository](https://github.com/langflow-ai/langflow-helm-charts/tree/main/charts/langflow-runtime).

+:::important
+By default, the [Langflow runtime Helm chart](https://github.com/langflow-ai/langflow-helm-charts/blob/main/charts/langflow-runtime/values.yaml#L46) enables `readOnlyRootFilesystem: true` as a security best practice. This setting prevents modifications to the container's root filesystem at runtime, which is a recommended security measure in production environments.
+
+Disabling `readOnlyRootFilesystem` reduces the security of your deployment. Only disable this setting if you understand the security implications and have implemented other security measures.
+
+For more information, see the [Kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/).
+:::
+
 ### Prerequisites

 - A [Kubernetes](https://kubernetes.io/docs/setup/) server
--- a/docs/docs/Deployment/deployment-overview.md
+++ b/docs/docs/Deployment/deployment-overview.md
@ -0,0 +1,40 @@
+---
+title: Langflow deployment overview
+slug: /deployment-overview
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+You have a flow, and want to share it with the world in a production environment.
+
+This page outlines the journey from locally-run flow to a cloud-hosted production server.
+
+More specific instructions are available in the [Docker](/deployment-docker) and [Kubernetes](/deployment-kubernetes) pages.
+
+## Langflow deployment architecture
+
+Langflow can be deployed as an [IDE](https://github.com/langflow-ai/langflow-helm-charts/tree/main/charts/langflow-ide) or as a [runtime](https://github.com/langflow-ai/langflow-helm-charts/tree/main/charts/langflow-runtime).
+
+The **IDE** includes the frontend for visual development of your flow. The default [docker-compose.yml](https://github.com/langflow-ai/langflow/blob/main/docker_example/docker-compose.yml) file hosted in the Langflow repository builds the Langflow IDE image. To deploy the Langflow IDE, see [Docker](/deployment-docker).
+
+The **runtime** is a headless or backend-only mode. The server exposes your flow as an endpoint, and runs only the processes necessary to serve your flow, with PostgreSQL as the database for improved scalability. Use the Langflow **runtime** to deploy your flows, because you don't require the frontend for visual development.
+
+## Package your flow with the Langflow runtime image
+
+To package your flow as a Docker image, copy your flow's `.JSON` file with a command in the Dockerfile.
+
+An example [Dockerfile](https://github.com/langflow-ai/langflow-helm-charts/blob/main/examples/langflow-runtime/docker/Dockerfile) for bundling flows is hosted in the Langflow Helm Charts repository.
+
+For more on building the Langflow docker image and pushing it to Docker Hub, see [Package your flow as a docker image](/deployment-docker#package-your-flow-as-a-docker-image).
+
+## Deploy to Kubernetes
+
+After your flow is packaged as a Docker image and available on Docker Hub, deploy your application by overriding the values in the [langflow-runtime](https://github.com/langflow-ai/langflow-helm-charts/blob/main/charts/langflow-runtime/Chart.yaml) Helm chart.
+
+For more information, see [Deploy Langflow on Kubernetes](/deployment-kubernetes).
+
+
+
+
+
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@ -79,6 +79,7 @@ module.exports = {
        "Configuration/configuration-auto-saving",
        "Configuration/configuration-backend-only",
        "Configuration/configuration-cli",
+        "Configuration/configuration-custom-database",
        "Configuration/configuration-global-variables",
        "Configuration/environment-variables",
        "Configuration/configuration-security-best-practices"
@ -88,11 +89,21 @@ module.exports = {
      type: "category",
      label: "Deployment",
      items: [
+        {
+          type:"doc",
+          id: "Deployment/deployment-overview",
+          label: "Deployment overview"
+        },
        {
          type: "doc",
          id: "Deployment/deployment-docker",
          label: "Docker"
        },
+        {
+          type: "doc",
+          id: "Deployment/deployment-kubernetes",
+          label: "Kubernetes"
+        },
        {
          type: "doc",
          id: "Deployment/deployment-gcp",
@ -103,11 +114,6 @@ module.exports = {
          id: "Deployment/deployment-hugging-face-spaces",
          label: "Hugging Face Spaces"
        },
-        {
-          type: "doc",
-          id: "Deployment/deployment-kubernetes",
-          label: "Kubernetes"
-        },
        {
          type: "doc",
          id: "Deployment/deployment-railway",