docs: update docs for global variables page and security (#4878)

* Added best practices document * Refactored global variables page * added category * move-security-page * link * Removed title from Security Best Practices * Avoid empty headings * Sentence case for headings * Remove general best practices not related to Langflow * Add bulleted list instead of numbered list * changed default secret locations to use the default secret key locations * Add periods on end of sentences * Changed title to be imperative --------- Co-authored-by: Mendon Kissling <59585235+mendonk@users.noreply.github.com>
2024-12-02 16:32:57 -03:00 · 2024-12-02 16:32:57 -03:00 · 008c65b6b7
commit 008c65b6b7
parent 19d2974904
3 changed files with 183 additions and 141 deletions
--- a/docs/docs/Configuration/configuration-global-variables.md
+++ b/docs/docs/Configuration/configuration-global-variables.md
@ -25,12 +25,11 @@ Langflow stores global variables in its internal database, and encrypts the valu

 5. Optional: Select a **Type** for your global variable. The available types are **Generic** (default) and **Credential**.

-    No matter which **Type** you select, Langflow still encrypts the **Value** of the global variable.
+   No matter which **Type** you select, Langflow still encrypts the **Value** of the global variable.

 6. Enter the **Value** for your global variable.

-7. Optional: Use the **Apply To Fields** menu to select one or more fields that you want Langflow to automatically apply your global variable to.
-For example, if you select **OpenAI API Key**, Langflow will automatically apply the variable to any **OpenAI API Key** field.
+7. Optional: Use the **Apply To Fields** menu to select one or more fields that you want Langflow to automatically apply your global variable to. For example, if you select **OpenAI API Key**, Langflow will automatically apply the variable to any **OpenAI API Key** field.

 8. Click **Save Variable**.

@ -71,6 +70,8 @@ The global variable, and any existing references to it, are deleted.

 ## Add global variables from the environment {#76844a93dbbc4d1ba551ea1a4a89ccdd}

+### Custom environment variables
+
 You can use the `LANGFLOW_VARIABLES_TO_GET_FROM_ENVIRONMENT` environment variable to source global variables from your runtime environment.

 <Tabs>
@ -83,26 +84,26 @@ If you installed Langflow locally, you must define the `LANGFLOW_VARIABLES_TO_GE

 2. Add the `LANGFLOW_VARIABLES_TO_GET_FROM_ENVIRONMENT` environment variable as follows:

-    ```plaintext title=".env"
-    LANGFLOW_VARIABLES_TO_GET_FROM_ENVIRONMENT=VARIABLE1,VARIABLE2
-    ```
+   ```plaintext title=".env"
+   LANGFLOW_VARIABLES_TO_GET_FROM_ENVIRONMENT=VARIABLE1,VARIABLE2
+   ```

-    Replace `VARIABLE1,VARIABLE2` with a comma-separated list (no spaces) of variables that you want Langflow to source from the environment.
-    For example, `my_key,some_string`.
+   Replace `VARIABLE1,VARIABLE2` with a comma-separated list (no spaces) of variables that you want Langflow to source from the environment.
+   For example, `my_key,some_string`.

 3. Save and close the file.

 4. Start Langflow with the `.env` file:

-    ```bash
-    VARIABLE1="VALUE1" VARIABLE2="VALUE2" python -m langflow run --env-file .env
-    ```
+   ```bash
+   VARIABLE1="VALUE1" VARIABLE2="VALUE2" python -m langflow run --env-file .env
+   ```

-    :::note
-    In this example, the environment variables (`VARIABLE1="VALUE1"` and `VARIABLE2="VALUE2"`) are prefixed to the startup command.
-    This is a rudimentary method for exposing environment variables to Python on the command line, and is meant for illustrative purposes.
-    Make sure to expose your environment variables to Langflow in a manner that best suits your own environment.
-    :::
+   :::note
+   In this example, the environment variables (`VARIABLE1="VALUE1"` and `VARIABLE2="VALUE2"`) are prefixed to the startup command.
+   This is a rudimentary method for exposing environment variables to Python on the command line, and is meant for illustrative purposes.
+   Make sure to expose your environment variables to Langflow in a manner that best suits your own environment.
+   :::

 5. Confirm that Langflow successfully sourced the global variables from the environment.

@ -110,7 +111,7 @@ If you installed Langflow locally, you must define the `LANGFLOW_VARIABLES_TO_GE

   2. Click **Global Variables**.

-    The environment variables appear in the list of **Global Variables**.
+   The environment variables appear in the list of **Global Variables**.

 </TabItem>

@ -150,8 +151,8 @@ When adding global variables from the environment, the following limitations app
 - You can only source the **Name** and **Value** from the environment.
  To add additional parameters, such as the **Apply To Fields** parameter, you must edit the global variables in the Langflow UI.

- Global variables that you add from the the environment always have the **Credential** type.
-:::
+- Global variables that you add from the environment always have the **Credential** type.
+  :::

 :::tip
 If you want to explicitly prevent Langflow from sourcing global variables from the environment, set `LANGFLOW_STORE_ENVIRONMENT_VARIABLES` to `false` in your `.env` file:
@ -162,46 +163,36 @@ LANGFLOW_STORE_ENVIRONMENT_VARIABLES=false

 :::

-<!-- TODO: Most of the information in this section should be documented on other pages dedicated to environment variables and best practices. However, until those pages exist, we'll just have to keep this information here. Once those pages are added, we can reduce this section to a bulleted list with cross references. -->
-## Precautions
+### Default environment variables

-Even though Langflow stores global variables in its internal database, and encrypts the values using a secret key, you should consider taking extra precautions to ensure the database and secret key are protected.
+Langflow automatically detects and converts some environment variables into global variables of the type **Credential**, which are applied to the specific fields in components that require them. Currently, the following variables are supported:

-### Use a custom secret key
+- `OPENAI_API_KEY`
+- `ANTHROPIC_API_KEY`
+- `GOOGLE_API_KEY`
+- `COHERE_API_KEY`
+- `GROQ_API_KEY`
+- `HUGGINGFACEHUB_API_TOKEN`
+- `SEARCHAPI_API_KEY`
+- `SERPAPI_API_KEY`
+- `AZURE_OPENAI_API_KEY`
+- `AZURE_OPENAI_API_VERSION`
+- `AZURE_OPENAI_API_INSTANCE_NAME`
+- `AZURE_OPENAI_API_DEPLOYMENT_NAME`
+- `AZURE_OPENAI_API_EMBEDDINGS_DEPLOYMENT_NAME`
+- `PINECONE_API_KEY`
+- `ASTRA_DB_APPLICATION_TOKEN`
+- `ASTRA_DB_API_ENDPOINT`
+- `UPSTASH_VECTOR_REST_URL`
+- `UPSTASH_VECTOR_REST_TOKEN`
+- `VECTARA_CUSTOMER_ID`
+- `VECTARA_CORPUS_ID`
+- `VECTARA_API_KEY`
+- `AWS_ACCESS_KEY_ID`
+- `AWS_SECRET_ACCESS_KEY`

-By default, Langflow generates a random secret key.
-However, you should provide your own secret key, as it's more secure to use a key that is already known to you.
+For information about other environment variables and their usage, see [Environment Variables](/environment-variables).

-Use the `LANGFLOW_SECRET_KEY` environment variable to provide a custom value for the secret key when you start Langflow.
+## Security best practices

-### Protect the secret key
-
-Make sure to store the secret key in a secure location.
-
-By default, Langflow stores the secret key in its configuration directory.
-The location of the configuration directory depends on your operating system:
-
- macOS: `~/Library/Caches/langflow/secret_key`
- Linux: `~/.cache/langflow/secret_key`
- Windows: `%USERPROFILE%\AppData\Local\langflow\secret_key`
-
-To change the location of the the configuration directory, and thus the location of the secret key, set the `LANGFLOW_CONFIG_DIR` environment variable to your preferred storage directory.
-
-### Protect the database
-
-Make sure to store Langflow's internal database file in a secure location, and take regular backups to prevent accidental data loss.
-
-By default, Langflow stores the database file in its installation directory.
-The location of the file depends on your operating system and installation method:
-
- macOS: `PYTHON_LOCATION/site-packages/langflow/langflow.db`
- Linux: `PYTHON_LOCATION/site-packages/langflow/langflow.db`
- Windows: `PYTHON_LOCATION\Lib\site-packages\langflow\langflow.db`
-
-To change the location of the database file, follow these steps:
-
-1. Set the `LANGFLOW_SAVE_DB_IN_CONFIG_DIR` environment variable to `true`.
-2. Set the `LANGFLOW_CONFIG_DIR` environment variable to your preferred storage directory.
-
-<!-- TODO: Add documentation for external database support. -->
-<!-- Alternatively, you can configure Langflow to store data in an *external* database, such as PostgreSQL, instead of its own internal database. -->
+For information about securing your global variables and other sensitive data, see [Security best practices](/configuration-security-best-practices).
--- a/docs/docs/Configuration/configuration-security-best-practices.md
+++ b/docs/docs/Configuration/configuration-security-best-practices.md
@ -0,0 +1,48 @@
+---
+title: Security best practices
+sidebar_position: 1
+slug: /configuration-security-best-practices
+---
+
+This guide outlines security best practices for deploying and managing Langflow.
+
+## Secret key protection
+
+The secret key is critical for encrypting sensitive data in Langflow. Follow these guidelines:
+
+- Always use a custom secret key in production:
+
+  ```bash
+  LANGFLOW_SECRET_KEY=your-secure-secret-key
+  ```
+
+- Store the secret key securely:
+
+  - Use environment variables or secure secret management systems.
+  - Never commit the secret key to version control.
+  - Regularly rotate the secret key.
+
+- Use the default secret key locations:
+  - macOS: `~/Library/Caches/langflow/secret_key`
+  - Linux: `~/.cache/langflow/secret_key`
+  - Windows: `%USERPROFILE%\AppData\Local\langflow\secret_key`
+
+## API keys and credentials
+
+- Store API keys and credentials as encrypted global variables.
+- Use the Credential type for sensitive information.
+- Implement proper access controls for users who can view/edit credentials.
+- Regularly audit and rotate API keys.
+
+## Database file protection
+
+- Store the database in a secure location:
+
+   ```bash
+   LANGFLOW_SAVE_DB_IN_CONFIG_DIR=true
+   LANGFLOW_CONFIG_DIR=/secure/path/to/config
+   ```
+
+- Use the default database locations:
+   - macOS/Linux: `PYTHON_LOCATION/site-packages/langflow/langflow.db`
+   - Windows: `PYTHON_LOCATION\Lib\site-packages\langflow\langflow.db`
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@ -1,17 +1,17 @@
 module.exports = {
  docs: [
-    'Get-Started/welcome-to-langflow',
+    "Get-Started/welcome-to-langflow",
    {
-      type: 'category',
-      label: 'Get Started',
+      type: "category",
+      label: "Get Started",
      items: [
-        'Get-Started/get-started-installation',
-        'Get-Started/get-started-quickstart',
+        "Get-Started/get-started-installation",
+        "Get-Started/get-started-quickstart",
      ],
    },
    {
-      type: 'category',
-      label: 'Starter Projects',
+      type: "category",
+      label: "Starter Projects",
      items: [
        'Starter-Projects/starter-projects-basic-prompting',
        'Starter-Projects/starter-projects-blog-writer',
@ -24,124 +24,127 @@ module.exports = {
      ],
    },
    {
-      type: 'category',
-      label: 'Workspace',
+      type: "category",
+      label: "Workspace",
      items: [
-        'Workspace/workspace-overview',
-        'Workspace/workspace-api',
-        'Workspace/workspace-logs',
-        'Workspace/workspace-playground',
+        "Workspace/workspace-overview",
+        "Workspace/workspace-api",
+        "Workspace/workspace-logs",
+        "Workspace/workspace-playground",
      ],
    },
    {
-      type: 'category',
-      label: 'Agents',
+      type: "category",
+      label: "Agents",
      items: [
-        'Agents/agents-overview',
-        'Agents/agent-tool-calling-agent-component',
+        "Agents/agents-overview",
+        "Agents/agent-tool-calling-agent-component",
      ],
    },
    {
-      type: 'category',
-      label: 'Configuration',
+      type: "category",
+      label: "Configuration",
      items: [
-        'Configuration/configuration-api-keys',
-        'Configuration/configuration-authentication',
-        'Configuration/configuration-auto-saving',
-        'Configuration/configuration-backend-only',
-        'Configuration/configuration-cli',
-        'Configuration/configuration-global-variables',
-        'Configuration/environment-variables',
+        "Configuration/configuration-api-keys",
+        "Configuration/configuration-authentication",
+        "Configuration/configuration-auto-saving",
+        "Configuration/configuration-backend-only",
+        "Configuration/configuration-cli",
+        "Configuration/configuration-global-variables",
+        "Configuration/environment-variables",
+        "Configuration/configuration-security-best-practices"
      ],
    },
    {
-      type: 'category',
-      label: 'Components',
+      type: "category",
+      label: "Components",
      items: [
-        'Components/components-overview',
-        'Components/components-agents',
-        'Components/components-custom-components',
-        'Components/components-data',
-        'Components/components-embedding-models',
-        'Components/components-helpers',
-        'Components/components-io',
-        'Components/components-loaders',
-        'Components/components-logic',
-        'Components/components-memories',
-        'Components/components-models',
-        'Components/components-prompts',
-        'Components/components-rag',
-        'Components/components-tools',
-        'Components/components-vector-stores',
+        "Components/components-overview",
+        "Components/components-agents",
+        "Components/components-custom-components",
+        "Components/components-data",
+        "Components/components-embedding-models",
+        "Components/components-helpers",
+        "Components/components-io",
+        "Components/components-loaders",
+        "Components/components-logic",
+        "Components/components-memories",
+        "Components/components-models",
+        "Components/components-prompts",
+        "Components/components-rag",
+        "Components/components-tools",
+        "Components/components-vector-stores",
      ],
    },
    {
-      type: 'category',
-      label: 'Guides',
+      type: "category",
+      label: "Guides",
      items: [
-        'Guides/guides-chat-memory',
-        'Guides/guides-data-message',
-        'Guides/guides-new-to-llms',
+        "Guides/guides-chat-memory",
+        "Guides/guides-data-message",
+        "Guides/guides-new-to-llms",
      ],
    },
    {
-      type: 'category',
-      label: 'Deployment',
+      type: "category",
+      label: "Deployment",
      items: [
-        'Deployment/deployment-docker',
-        'Deployment/deployment-gcp',
-        'Deployment/deployment-hugging-face-spaces',
-        'Deployment/deployment-kubernetes',
-        'Deployment/deployment-railway',
-        'Deployment/deployment-render',
+        "Deployment/deployment-docker",
+        "Deployment/deployment-gcp",
+        "Deployment/deployment-hugging-face-spaces",
+        "Deployment/deployment-kubernetes",
+        "Deployment/deployment-railway",
+        "Deployment/deployment-render",
      ],
    },
    {
-      type: 'category',
-      label: 'Integrations',
+      type: "category",
+      label: "Integrations",
      items: [
-        'Integrations/integrations-assemblyai',
-        'Integrations/integrations-langfuse',
-        'Integrations/integrations-langsmith',
-        'Integrations/integrations-langwatch',
+        "Integrations/integrations-assemblyai",
+        "Integrations/integrations-langfuse",
+        "Integrations/integrations-langsmith",
+        "Integrations/integrations-langwatch",
        {
-          type: 'category',
-          label: 'Google',
-          items: ['Integrations/Google/integrations-setup-google-oauth-langflow'],
+          type: "category",
+          label: "Google",
+          items: [
+            "Integrations/Google/integrations-setup-google-oauth-langflow",
+          ],
        },
        {
-          type: 'category',
-          label: 'Notion',
+          type: "category",
+          label: "Notion",
          items: [
-            'Integrations/Notion/integrations-notion',
-            'Integrations/Notion/notion-agent-conversational',
-            'Integrations/Notion/notion-agent-meeting-notes',
+            "Integrations/Notion/integrations-notion",
+            "Integrations/Notion/notion-agent-conversational",
+            "Integrations/Notion/notion-agent-meeting-notes",
          ],
        },
      ],
    },
    {
-      type: 'category',
-      label: 'Contributing',
+      type: "category",
+      label: "Contributing",
      items: [
-        'Contributing/contributing-community',
-        'Contributing/contributing-components',
-        'Contributing/contributing-github-discussion-board',
-        'Contributing/contributing-github-issues',
-        'Contributing/contributing-how-to-contribute',
-        'Contributing/contributing-telemetry',
+        "Contributing/contributing-community",
+        "Contributing/contributing-components",
+        "Contributing/contributing-github-discussion-board",
+        "Contributing/contributing-github-issues",
+        "Contributing/contributing-how-to-contribute",
+        "Contributing/contributing-telemetry",
      ],
    },
    {
-      type: 'category',
-      label: 'API Reference',
+      type: "category",
+      label: "API Reference",
      items: [
        {
-          type: 'link',
-          label: 'API Documentation',
-          href: '/api',
+          type: "link",
+          label: "API Documentation",
+          href: "/api",
        },
      ],
    },
  ],
-};
+};