From 18d96b54a740e82ce09d7271cd0ae86c88bb4db4 Mon Sep 17 00:00:00 2001
From: Mauricio Siu <47042324+Siumauricio@users.noreply.github.com>
Date: Sun, 7 Sep 2025 12:53:50 -0600
Subject: [PATCH] docs: expand environment variables section to include
 environment-level variables with practical examples

---
 apps/docs/content/docs/core/variables.mdx | 40 +++++++++++++++++++++--
 1 file changed, 38 insertions(+), 2 deletions(-)

diff --git a/apps/docs/content/docs/core/variables.mdx b/apps/docs/content/docs/core/variables.mdx
index 5b83adc..1f29254 100644
--- a/apps/docs/content/docs/core/variables.mdx
+++ b/apps/docs/content/docs/core/variables.mdx
@@ -1,6 +1,6 @@
 ---
 title: Environment Variables
-description: "Dokploy allows you to create and manage shared and service-level environment variables for your projects."
+description: "Dokploy allows you to create and manage shared and service-level environment variables for your projects and environments."
 ---
 
 import { Callout } from "fumadocs-ui/components/callout";
@@ -19,6 +19,7 @@ Environment variables in Dokploy allow you to:
 
 You can declare environment variables either:
 - **Project-level (shared)** — available across all services in the project
+- **Environment-level** — specific to a single environment
 - **Service-level** — specific to a single service
 
 ## Project-Level Variables
@@ -51,6 +52,40 @@ DATABASE_URL=${{project.DATABASE_URL}}
 
 You can use shared environment variables in all the services available in dokploy.
 
+
+## Environment-Level Variables
+
+### Practical Example
+
+Let's consider a scenario where you have:
+- A staging environment with different database credentials
+- Multiple services that need environment-specific configurations
+
+### 1. Define Environment Variable
+
+In the environment's variables section, define:
+
+```bash
+DATABASE_PASSWORD=staging_secret_password
+API_KEY=staging_api_key_12345
+```
+
+### 2. Use the Variable in Services
+
+In each service's environment variables tab, reference the environment variable:
+
+
+```bash
+DATABASE_URL=postgresql://postgres:${{environment.DATABASE_PASSWORD}}@staging-db:5432/postgres
+EXTERNAL_API_KEY=${{environment.API_KEY}}
+```
+
+<Callout type="info">
+  Dokploy will automatically replace `${{environment.VARIABLE_NAME}}` with the value defined in the environment's variables.
+</Callout>
+
+You can use environment variables in all the services available in that specific environment.
+
 ## Service-Level Variables
 
 Service-level variables are specific to a single service and can be used to override shared variables or define service-specific configurations.
@@ -61,7 +96,8 @@ Let's say you have a service that requires a different database user. You can de
 
 ```bash
 DATABASE_USER=service_user
-DATABASE_URL=postgresql://${{DATABASE_USER}}:${{project.DATABASE_PASSWORD}}@service-database:5432/postgres
+DATABASE_PASSWORD=service_password
+DATABASE_URL=postgresql://${{DATABASE_USER}}:${{DATABASE_PASSWORD}}@service-database:5432/postgres
 ```
 
 <Callout type="info">