Melissa/log 779 variables love

src/docs/develop/variables.md

@@ -2,27 +2,28 @@
 title: Variables
 ---
 
-Service variables are provided whenever you build, deploy, or run `railway run`. When
-defined, they are made available to your application at runtime as environment variables.
+Variables provide a powerful way to manage configuration and secrets across services in Railway.
 
-Variables are made available in the following scenarios:
+When defined, they are made available to your application as environment variables in the following scenarios:
 
 - The build process for each service deployment.
 - The running service deployment.
 - The command invoked by `railway run <COMMAND>`
 - The local shell via `railway shell`
 
-## Defining Variables
+In Railway, there is also a notion of configuration variables which allow you to control the behavior of the platform.
 
-Variables can be added via the Railway Dashboard by navigating to a service's "Variables" tab.
+
+## Service variables
+
+Define variables scoped to individual services by navigating to a service's "Variables" tab.
 
 <Image src="https://res.cloudinary.com/railway/image/upload/c_scale,w_2026/v1678820924/docs/CleanShot_2023-03-14_at_12.07.44_2x_rpesxd.png"
 alt="Screenshot of Variables Pane"
 layout="responsive"
 width={2026} height={933} quality={100} />
 
-You can view all variables for the current environment using the [Railway CLI](/develop/cli) with
-`railway variables` and change the environment with `railway environment`.
+Click on `New Variable` to enter your new variable into a form field or use the `RAW Editor`.
 
 ### Raw Editor
 
@@ -33,13 +34,92 @@ alt="Screenshot of Raw Editor"
 layout="responsive"
 width={1954} height={1303} quality={100} />
 
-Variables can be defined as simple key/value pairs or as [Templated Variables](#templated-variables) (eg. `${{Postgres.DATABASE_URL}}`),
-which can dynamically reference other variables, shared variables, or plugin variables (more on this below).
+## Shared Variables
+
+Shared variables help reduce duplication of variables across multiple services within the same project.  They are defined at the project environment level and can be added in Project Settings > Shared Variables.
+
+<Image src="https://res.cloudinary.com/railway/image/upload/v1669678393/docs/shared-variables-settings_vchmzn.png"
+alt="Screenshot of Shared Variables Settings"
+layout="responsive"
+width={2402} height={1388} quality={100} />
+
+To use a shared variable, either click the Share button and select the desired services,
+or visit the Variables tab within the service itself and click "Shared Variable".
+
+<Image src="https://res.cloudinary.com/railway/image/upload/v1667332192/docs/shared-variables-picker_ryjble.png"
+alt="Screenshot of Shared Variables Picker"
+layout="responsive"
+width={1784} height={1168} quality={100} />
+
+Adding a shared variables to a service creates a [Reference Variable](/develop/variables#reference-variables) in the service.
+
+## Reference Variables
+
+Variables can be defined to reference variables in other services or to reference shared variables.  This is useful for ease of maintenace and security, allowing you to set a variable in a single place, wherever it makes the most sense.
+
+Reference variables use Railway's [template syntax](/develop/variables#template-syntax) using a specific format - `${{NAMESPACE.VAR}}` - where `NAMESPACE` can either be a service's name or the value `shared` (depending on where the variable is defined that you need to access) and `VAR` is the variable name.
+
+When using reference variables, you also have access to [Railway-provided variables](/develop/variables#railway-provided-variables).
+
+### Example Scenarios
 
-### Multiline Variables
+Here are some example scenarios to help clarify reference variable usage and syntax.
+
+#### Referencing a Shared variable -
+- You have a shared variable defined in your project called `API_KEY`, and you need to make the API key available to a service.  Go to the service's variables tab, and add a variable with the following value:
+  - `API_KEY=${{shared.API_KEY}}`
+
+#### Referencing another service's variables -
+- You have a variable set on your database service called `DATABASE_URL` which contains the connection string to connect to the database.  The database service name is **Clickhouse**.
+
+  You need to make this connection string available to another service in the project.  Go to the service's variables that needs the connection string and add a variable with the following value:
+  - `DATABASE_URL=${{ Clickhouse.DATABASE_URL }}`
+
+- Your frontend service needs to make requests to your backend.  You do not want to hardcode the backend URL in your frontend code.  Go to your frontend service settings and add the Railway-provided variable for the backend URL -
+  - `API_URL=https://${{ backend.RAILWAY_PUBLIC_DOMAIN }}`
+
+### Autocomplete Dropdown
+
+The Railway dashboard also provides an autocomplete dropdown in both the name and
+value fields to help create reference variables.
+
+<Image src="https://res.cloudinary.com/railway/image/upload/v1699559731/docs/referenceVars_klvijr.gif"
+alt="Screenshot of Variables Pane"
+layout="responsive"
+width={1108} height={1050} quality={100} />
+
+## Multiline Variables
 
 Variables can span multiple lines. Press `Control + Enter` (`Cmd + Enter` on Mac) in the variable value input field to add a newline, or simply type a newline in the Raw Editor.
 
+## Template Syntax
+
+Railway's templating syntax gives you flexibility in managing variables.  You can combine additional text or even other variables, to construct the values that you need.
+
+```plaintext
+DOMAIN=${{shared.DOMAIN}}
+GRAPHQL_PATH=/v1/gql
+GRAPHQL_ENDPOINT=https://${{DOMAIN}}/${{GRAPHQL_PATH}}
+```
+
+The example above illustrates a pattern of maintaining a Shared variable called `DOMAIN` and using that plus a Service variable to construct an endpoint.
+
+
+
+## Using Variables in your services
+
+Variables are made available at runtime as environment variables.  In order to use them in your code, simply use the package appropriate for your language to retrieve environment variables.
+
+For example, in a node app -
+
+```node
+process.env.VARIABLE_NAME
+```
+
+#### Local development
+
+Using the Railway CLI, you can run your code locally with the environment variables configured in your Railway project.  Check out the [CLI docs](/develop/cli#local-development) for the appropriate commands.
+
 ## Railway-Provided Variables
 
 Railway provides the following additional system environment variables to all
@@ -77,7 +157,7 @@ These variables are provided if the deploy originated from a GitHub trigger.
 | `RAILWAY_GIT_REPO_OWNER`     | The name of the repository owner that triggered the deployment. Example: `mycompany`                                                                                                                 |
 | `RAILWAY_GIT_COMMIT_MESSAGE` | The message of the commit that triggered the deployment. Example: `Fixed a few bugs`                                                                                                                 |
 
-## User-Provided Configuration Variables
+### User-Provided Configuration Variables
 
 Users can use the following environment variables to configure Railway's behaviour.
 
@@ -88,69 +168,6 @@ Users can use the following environment variables to configure Railway's behavio
 | `NIXPACKS_CONFIG_FILE`               | The path to the Nixpacks configuration file relative to the root of the app, its default value is `nixpacks.toml`. Example: `frontend.nixpacks.toml` |
 | `RAILWAY_HEALTHCHECK_TIMEOUT_SEC`    | The timeout length (in seconds) of healthchecks. Example: `300`                                                                                      |
 
-## Reference Variables
-
-Variables can use the `${{VAR}}` or `${{NAMESPACE.VAR}}` syntax to reference
-other service variables, shared variables, or plugin variables.
-
-The Railway dashboard provides an autocomplete dropdown in both the name and
-value fields to help create these references.
-
-<Image src="https://res.cloudinary.com/railway/image/upload/c_scale,w_2000/v1678823846/docs/CleanShot_2023-03-14_at_12.56.56_2x_mbb6hu.png"
-alt="Screenshot of Variables Pane"
-layout="responsive"
-width={2408} height={1150} quality={100} />
-
-You can also reference the Railway provided variables of other services. For
-example, in your "frontend" service you can create the variable
-
-```plaintext
-API_URL=https://${{ backend.RAILWAY_PUBLIC_DOMAIN }}
-```
-
-and then use it to make requests to your backend. This prevents the need to
-hardcode the URL in your frontend code.
-
-### Plugin Variables
-
-Railway plugins offer a number variables that can be referenced by Railway services. To include a plugin variable,
-create a reference to the variable using the `${{<PLUGIN_NAME>.<VARIABLE_NAME>}}` syntax.
-
-```plaintext
-DATABASE_URL=${{Postgres.DATABASE_URL}}
-CACHE_HOST=${{Redis.REDISHOST}}
-PRISMA_DB=${{Postgres.DATABASE_URL}}?connection_limit=100
-```
-
-**_NOTE: Railway's autocomplete will help create these references so you don't need to remember the exact syntax._**
-
-### Shared Variables
-
-Shared variables help reduce duplication of variables across multiple services within the same project. They are
-defined at the project environment level and can be added in Project Settings > Shared Variables.
-
-<Image src="https://res.cloudinary.com/railway/image/upload/v1669678393/docs/shared-variables-settings_vchmzn.png"
-alt="Screenshot of Shared Variables Settings"
-layout="responsive"
-width={2402} height={1388} quality={100} />
-
-To use a shared variable, either click the Share button and select the desired services,
-or visit the Variables tab within the service itself and click "Insert Shared Variable".
-
-<Image src="https://res.cloudinary.com/railway/image/upload/v1667332192/docs/shared-variables-picker_ryjble.png"
-alt="Screenshot of Shared Variables Picker"
-layout="responsive"
-width={1784} height={1168} quality={100} />
-
-Under the hood, adding a shared variables to a service creates a new variable that references the shared variable using Railway's templating syntax (eg. `NAME=${{shared.NAME}}`).
-This means that shared variables can be combined with additional text or even other variables, like the following examples illustrate.
-
-```plaintext
-DOMAIN=${{shared.DOMAIN}}
-URL=https://${{shared.DOMAIN}}
-GRAPHQL_ENDPOINT=https://${{shared.DOMAIN}}/${{GRAPHQL_PATH}}
-```
-
 ## Import Variables from Heroku
 
 You can import variables from an existing Heroku app using the command palette
@@ -164,4 +181,8 @@ width={521} height={404} quality={100} />
 
 ## Service Discovery
 
-You can reference other services' public URL via a service variable. Use `RAILWAY_SERVICE_{ServiceName}_URL` to get the public URL of a service within your project. For example, if you have a service named `Backend API`, you can reference it from another service by using `RAILWAY_SERVICE_BACKEND_API_URL`.
+You can reference other services' public URL via a service variable.
+
+Use `RAILWAY_SERVICE_{ServiceName}_URL` to get the public URL of a service within your project. 
+
+For example, if you have a service named `Backend API`, you can reference it from another service by using `RAILWAY_SERVICE_BACKEND_API_URL`.