docs: Update global variable documentation

docs/docs/Settings/settings-global-variables.md

@@ -5,159 +5,205 @@ slug: /settings-global-variables
 ---
 
 import ReactPlayer from "react-player";
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
 
-:::info
+Global variables let you store and reuse generic input values and credentials across your projects.
+You can use a global variable in any text input field that displays the 🌐 icon.
 
-This page may contain outdated information. It will be updated as soon as possible.
+Langflow stores global variables in its internal database, and encrypts the values using a secret key.
 
-:::
+## Create a global variable {#3543d5ef00eb453aa459b97ba85501e5}
 
+1. In the Langflow UI, click your profile icon, and then select **Settings**.
 
+2. Click **Global Variables**.
 
+3. Click **Add New**.
 
-Global Variables are a useful feature of Langflow, allowing you to define reusable variables accessed from any Text field in your project.
+4. In the **Create Variable** dialog, enter a name for your variable in the **Variable Name** field.
 
+5. Optional: Select a **Type** for your global variable. The available types are **Generic** (default) and **Credential**.
 
-**TL;DR**
+    No matter which **Type** you select, Langflow still encrypts the **Value** of the global variable.
 
-- Global Variables are reusable variables accessible from any Text field in your project.
-- To create one, click the 🌐 button in a Text field and then **+ Add New Variable**.
-- Define the **Name**, **Type**, and **Value** of the variable.
-- Click **Save Variable** to create it.
-- All Credential Global Variables are encrypted and accessible only by you.
-- Set _`LANGFLOW_STORE_ENVIRONMENT_VARIABLES`_ to _`true`_ in your `.env` file to add all variables in _`LANGFLOW_VARIABLES_TO_GET_FROM_ENVIRONMENT`_ to your user's Global Variables.
+6. Enter the **Value** for your global variable.
 
-### Create and Add a Global Variable {#3543d5ef00eb453aa459b97ba85501e5}
+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**.
 
-To create and add a global variable, click the 🌐 button in a Text field, and then click **+ Add New Variable**.
+You can now select your global variable from any text input field that displays the 🌐 icon.
 
+:::info
+Because values are encrypted, you can't view the actual values of your global variables.
+In **Settings > Global Variables**, the **Value** column shows the encrypted hash for **Generic** type variables, and shows nothing for **Credential** type variables.
+:::
 
-Text fields are where you write text without opening a Text area, and are identified with the 🌐 icon.
+<ReactPlayer controls url="https://youtu.be/RedPOCsYNAM" />
 
+## Edit a global variable
 
-For example, to create an environment variable for the **OpenAI** component:
+1. In the Langflow UI, click your profile icon, and then select **Settings**.
 
-1. In the **OpenAI API Key** text field, click the 🌐 button, then **Add New Variable**.
-2. Enter `openai_api_key` in the **Variable Name** field.
-3. Paste your OpenAI API Key (`sk-...`) in the **Value** field.
-4. Select **Credential** for the **Type**.
-5. Choose **OpenAI API Key** in the **Apply to Fields** field to apply this variable to all fields named **OpenAI API Key**.
-6. Click **Save Variable**.
+2. Click **Global Variables**.
 
-You now have a `openai_api_key` global environment variable for your Langflow project.
-Subsequently, clicking the 🌐 button in a Text field will display the new variable in the dropdown.
+3. Click on the global variable you want to edit.
 
+4. In the **Update Variable** dialog, you can edit the following fields: **Variable Name**, **Value**, and **Apply To Fields**.
 
-:::tip
+5. Click **Update Variable**
 
-You can also create global variables in Settings &gt; Global Variables.
+## Delete a global variable
 
+:::warning
+Deleting a global variable permanently deletes any references to it from your existing projects.
 :::
 
+1. In the Langflow UI, click your profile icon, and then select **Settings**.
+
+2. Click **Global Variables**.
+
+3. Click the checkbox next to the global variable that you want to delete.
+
+4. Click the Trash icon.
+
+The global variable, and any existing references to it, are deleted.
+
+## Add global variables from the environment {#76844a93dbbc4d1ba551ea1a4a89ccdd}
+
+You can use the `LANGFLOW_VARIABLES_TO_GET_FROM_ENVIRONMENT` environment variable to source global variables from your runtime environment.
+
+<Tabs>
+
+<TabItem value="local" label="Local" default>
+
+If you installed Langflow locally, you must define the `LANGFLOW_VARIABLES_TO_GET_FROM_ENVIRONMENT` environment variable in a `.env` file.
+
+1. Create a `.env` file and open it in your preferred editor.
+
+2. Add the `LANGFLOW_VARIABLES_TO_GET_FROM_ENVIRONMENT` environment variable as follows:
+
+    ```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`.
+
+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
+    ```
 
+    :::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.
+    :::
 
-![](./418277339.png)
+5. Confirm that Langflow successfully sourced the global variables from the environment.
 
+   1. In the Langflow UI, click your profile icon, and then select **Settings**.
 
-To view and manage your project's global environment variables, visit **Settings** &gt; **Global Variables**.
+   2. Click **Global Variables**.
 
+    The environment variables appear in the list of **Global Variables**.
 
-### Configure Environment Variables in your .env file {#76844a93dbbc4d1ba551ea1a4a89ccdd}
+</TabItem>
 
+<TabItem value="docker" label="Docker">
 
-Setting `LANGFLOW_STORE_ENVIRONMENT_VARIABLES` to `true` in your `.env` file (default) adds all variables in `LANGFLOW_VARIABLES_TO_GET_FROM_ENVIRONMENT` to your user's Global Variables.
+If you're using Docker, you can pass `LANGFLOW_VARIABLES_TO_GET_FROM_ENVIRONMENT` directly from the command line or from a `.env` file.
 
+To pass `LANGFLOW_VARIABLES_TO_GET_FROM_ENVIRONMENT` directly from the command line:
 
-These variables are accessible like any other Global Variable.
+```bash
+docker run -it --rm \
+    -p 7860:7860 \
+    -e LANGFLOW_VARIABLES_TO_GET_FROM_ENVIRONMENT="VARIABLE1,VARIABLE2" \
+    -e VARIABLE1="VALUE1" \
+    -e VARIABLE2="VALUE2" \
+    langflowai/langflow:latest
+```
 
+To pass `LANGFLOW_VARIABLES_TO_GET_FROM_ENVIRONMENT` from a `.env` file:
+
+```bash
+docker run -it --rm \
+    -p 7860:7860 \
+    --env-file .env \
+    -e VARIABLE1="VALUE1" \
+    -e VARIABLE2="VALUE2" \
+    langflowai/langflow:latest
+```
+
+</TabItem>
+
+</Tabs>
 
 :::info
+When adding global variables from the environment, the following limitations apply:
 
-To prevent this behavior, set `LANGFLOW_STORE_ENVIRONMENT_VARIABLES` to `false` in your `.env` file.
+- 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.
 :::
 
+:::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:
 
+```plaintext title=".env"
+LANGFLOW_STORE_ENVIRONMENT_VARIABLES=false
+```
 
+:::
 
-You can specify variables to get from the environment by listing them in `LANGFLOW_VARIABLES_TO_GET_FROM_ENVIRONMENT`, as a comma-separated list (e.g., _`VARIABLE1, VARIABLE2`_).
+<!-- 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
 
+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.
 
-The default list of variables includes the ones below and more:
+### Use a custom secret key
 
-- ANTHROPIC_API_KEY
-- ASTRA_DB_API_ENDPOINT
-- ASTRA_DB_APPLICATION_TOKEN
-- AZURE_OPENAI_API_KEY
-- AZURE_OPENAI_API_DEPLOYMENT_NAME
-- AZURE_OPENAI_API_EMBEDDINGS_DEPLOYMENT_NAME
-- AZURE_OPENAI_API_INSTANCE_NAME
-- AZURE_OPENAI_API_VERSION
-- COHERE_API_KEY
-- GOOGLE_API_KEY
-- GROQ_API_KEY
-- HUGGINGFACEHUB_API_TOKEN
-- OPENAI_API_KEY
-- PINECONE_API_KEY
-- SEARCHAPI_API_KEY
-- SERPAPI_API_KEY
-- UPSTASH_VECTOR_REST_URL
-- UPSTASH_VECTOR_REST_TOKEN
-- VECTARA_CUSTOMER_ID
-- VECTARA_CORPUS_ID
-- VECTARA_API_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.
 
-<ReactPlayer controls url="https://youtu.be/RedPOCsYNAM" />
+Use the `LANGFLOW_SECRET_KEY` environment variable to provide a custom value for the secret key when you start Langflow.
 
+### Protect the secret key
 
-### Precautions
+Make sure to store the secret key in a secure location.
 
-Global variables are stored in the database, and their values are protected by encryption using a secret
-key. To preserve access to your global variables and avoid losing them, you should take a few precautions:
+By default, Langflow stores the secret key in its configuration directory.
+The location of the configuration directory depends on your operating system:
 
-1. Keep your secret key safe: Even if your database is secure, it won’t be of much use if you can't decrypt
-the values. Ideally, you can set your own secret key using the `LANGFLOW_SECRET_KEY` environment variable. If
-you don't provide a custom value for the secret key, one will be generated randomly and saved in the Langflow
-installation directory.
+- macOS: `~/Library/Caches/langflow/secret_key`
+- Linux: `~/.cache/langflow/secret_key`
+- Windows: `%USERPROFILE%\AppData\Local\langflow\secret_key`
 
-2. We use SQLite as the default database, and Langflow saves the database file in the installation directory.
-To ensure the security of your data, it’s a good practice to regularly back up this file. If needed, you can
-also change the database location by setting the `LANGFLOW_SAVE_DB_IN_CONFIG_DIR` environment variable to true
-and configuring `LANGFLOW_CONFIG_DIR` to point to a directory of your choice. Alternatively, you can opt to use
-an external database such as PostgreSQL, in which case these configurations are no longer necessary.
+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.
 
-For your convenience, if you’re running Langflow directly on your system or in a virtual environment
-via a pip installation, you can set these values by providing Langflow with a .env file containing these
-environment variables, using the following command:
+### Protect the database
 
-```bash
-langflow run --env-file .env
-```
+Make sure to store Langflow's internal database file in a secure location, and take regular backups to prevent accidental data loss.
 
-If you’re running Langflow in a Docker container, you can set these values by providing Langflow with:
+By default, Langflow stores the database file in its installation directory.
+The location of the file depends on your operating system and installation method:
 
-```bash
-docker run \
-        --privileged \
-        --user 1000:0 \
-        -p 7860:7860 \
-        -e LANGFLOW_SECRET_KEY=<YOUR_SECRET_KEY_VALUE> \
-        -e LANGFLOW_SAVE_DB_IN_CONFIG_DIR=true \
-        -e LANGFLOW_CONFIG_DIR=/app/container_path \
-        -v $(PWD)/your_path:/app/container_path \
-        langflowai/langflow:latest
-```
+- 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`
 
-or
+To change the location of the database file, follow these steps:
 
-```bash
-docker run \
-	--privileged \
-	--user 1000:0 \
-	-p 7860:7860 \
-	--env-file .env \
-	-v $(PWD)/your_path:/app/container_path \
-    langflowai/langflow:latest
-```
+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. -->