From 008c65b6b752fb941dfc443c58492dd8751a5a97 Mon Sep 17 00:00:00 2001 From: Lucas Oliveira <62335616+lucaseduoli@users.noreply.github.com> Date: Mon, 2 Dec 2024 16:32:57 -0300 Subject: [PATCH] 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> --- .../configuration-global-variables.md | 105 +++++------ .../configuration-security-best-practices.md | 48 +++++ docs/sidebars.js | 171 +++++++++--------- 3 files changed, 183 insertions(+), 141 deletions(-) create mode 100644 docs/docs/Configuration/configuration-security-best-practices.md diff --git a/docs/docs/Configuration/configuration-global-variables.md b/docs/docs/Configuration/configuration-global-variables.md index ea63dea6f..2900ab786 100644 --- 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. @@ -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**. @@ -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 ::: - -## 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. - - - \ No newline at end of file +For information about securing your global variables and other sensitive data, see [Security best practices](/configuration-security-best-practices). \ No newline at end of file diff --git a/docs/docs/Configuration/configuration-security-best-practices.md b/docs/docs/Configuration/configuration-security-best-practices.md new file mode 100644 index 000000000..053ff5662 --- /dev/null +++ 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` diff --git a/docs/sidebars.js b/docs/sidebars.js index 7c1412511..f9e50d97c 100644 --- 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", }, ], }, ], -}; \ No newline at end of file +};