Environment Variables Reference

How Gordon handles environment variables for containers.

Variable Sources

Environment variables are loaded from multiple sources and merged:

Source	Priority	Description
Dockerfile `ENV`	Lowest	Default values from image
`.env` file	Highest	Per-route overrides

Higher priority sources override lower priority values.

Environment File Location

Files are stored in the env directory (default: ~/.gordon/env/):

~/.gordon/env/
├── app_mydomain_com.env
├── api_mydomain_com.env
└── admin_mydomain_com.env

Naming: Replace dots with underscores, add .env suffix.

Domain	File Name
`app.mydomain.com`	`app_mydomain_com.env`
`api.company.io`	`api_company_io.env`
`staging.app.dev`	`staging_app_dev.env`

File Format

Standard .env format:

# Comments start with #
KEY=value
ANOTHER_KEY=another value

# Quotes are optional but recommended for values with spaces
MESSAGE="Hello World"

# No spaces around =
DATABASE_URL=postgresql://localhost:5432/mydb

Secret Provider Syntax

Reference secrets from configured backends:

Pass Provider

# Syntax: ${pass:<path>}
DATABASE_PASSWORD=${pass:myapp/database/password}
API_KEY=${pass:company/api-key}
JWT_SECRET=${pass:production/jwt-secret}

SOPS Provider

# Syntax: ${sops:<file>:<key.path>}
DATABASE_PASSWORD=${sops:secrets.yaml:database.password}
API_SECRET=${sops:production.yaml:api.secret.key}
STRIPE_KEY=${sops:secrets.yaml:stripe.api_key}

Variable Expansion

From Secrets

# Password from pass
DB_PASSWORD=${pass:myapp/db-password}

# Then use in connection string
DATABASE_URL=postgresql://user:${DB_PASSWORD}@db:5432/mydb

Static Values

# Simple values
NODE_ENV=production
PORT=3000

# Values with special characters (use quotes)
MESSAGE="Hello, World!"
JSON_CONFIG='{"key": "value"}'

Dockerfile ENV

Variables from Dockerfile serve as defaults:

FROM node:18
ENV NODE_ENV=development
ENV PORT=3000
ENV LOG_LEVEL=info

Override in .env file:

# Override NODE_ENV, keep PORT and LOG_LEVEL defaults
NODE_ENV=production

Result:

NODE_ENV=production (from .env)
PORT=3000 (from Dockerfile)
LOG_LEVEL=info (from Dockerfile)

Common Variables

Node.js

NODE_ENV=production
PORT=3000
LOG_LEVEL=warn

Python

FLASK_ENV=production
DJANGO_SETTINGS_MODULE=myapp.settings.production
PYTHONUNBUFFERED=1

Database Connections

# PostgreSQL
DATABASE_URL=postgresql://user:pass@postgres:5432/mydb

# MySQL
DATABASE_URL=mysql://user:pass@mysql:3306/mydb

# Redis
REDIS_URL=redis://redis:6379/0

External Services

# AWS
AWS_ACCESS_KEY_ID=${pass:aws/access-key}
AWS_SECRET_ACCESS_KEY=${pass:aws/secret-key}
AWS_REGION=us-east-1

# Stripe
STRIPE_SECRET_KEY=${pass:stripe/secret-key}
STRIPE_PUBLISHABLE_KEY=pk_live_...

# SendGrid
SENDGRID_API_KEY=${pass:sendgrid/api-key}

Examples

Minimal

NODE_ENV=production
PORT=3000

With Database

NODE_ENV=production
PORT=3000
DATABASE_URL=postgresql://postgres:5432/myapp
DATABASE_PASSWORD=${pass:myapp/db-password}

Full Production

# Application
NODE_ENV=production
PORT=3000
LOG_LEVEL=warn

# Database
DATABASE_URL=postgresql://postgres:5432/production
DATABASE_PASSWORD=${pass:company/db-password}

# Cache
REDIS_URL=redis://redis:6379/0

# External APIs
STRIPE_SECRET_KEY=${pass:company/stripe-secret}
SENDGRID_API_KEY=${pass:company/sendgrid-key}

# Auth
JWT_SECRET=${pass:company/jwt-secret}
SESSION_SECRET=${pass:company/session-secret}

# Feature flags
ENABLE_ANALYTICS=true
MAINTENANCE_MODE=false

Viewing Container Environment

docker inspect gordon-app-mydomain-com --format '{{json .Config.Env}}' | jq

source

1# Environment Variables Reference
2
3How Gordon handles environment variables for containers.
4
5## Variable Sources
6
7Environment variables are loaded from multiple sources and merged:
8
9| Source | Priority | Description |
10|--------|----------|-------------|
11| Dockerfile `ENV` | Lowest | Default values from image |
12| `.env` file | Highest | Per-route overrides |
13
14Higher priority sources override lower priority values.
15
16## Environment File Location
17
18Files are stored in the env directory (default: `~/.gordon/env/`):
19
20```
21~/.gordon/env/
22├── app_mydomain_com.env
23├── api_mydomain_com.env
24└── admin_mydomain_com.env
25```
26
27**Naming:** Replace dots with underscores, add `.env` suffix.
28
29| Domain | File Name |
30|--------|-----------|
31| `app.mydomain.com` | `app_mydomain_com.env` |
32| `api.company.io` | `api_company_io.env` |
33| `staging.app.dev` | `staging_app_dev.env` |
34
35## File Format
36
37Standard `.env` format:
38
39```bash
40# Comments start with #
41KEY=value
42ANOTHER_KEY=another value
43
44# Quotes are optional but recommended for values with spaces
45MESSAGE="Hello World"
46
47# No spaces around =
48DATABASE_URL=postgresql://localhost:5432/mydb
49```
50
51## Secret Provider Syntax
52
53Reference secrets from configured backends:
54
55### Pass Provider
56
57```bash
58# Syntax: ${pass:<path>}
59DATABASE_PASSWORD=${pass:myapp/database/password}
60API_KEY=${pass:company/api-key}
61JWT_SECRET=${pass:production/jwt-secret}
62```
63
64### SOPS Provider
65
66```bash
67# Syntax: ${sops:<file>:<key.path>}
68DATABASE_PASSWORD=${sops:secrets.yaml:database.password}
69API_SECRET=${sops:production.yaml:api.secret.key}
70STRIPE_KEY=${sops:secrets.yaml:stripe.api_key}
71```
72
73## Variable Expansion
74
75### From Secrets
76
77```bash
78# Password from pass
79DB_PASSWORD=${pass:myapp/db-password}
80
81# Then use in connection string
82DATABASE_URL=postgresql://user:${DB_PASSWORD}@db:5432/mydb
83```
84
85### Static Values
86
87```bash
88# Simple values
89NODE_ENV=production
90PORT=3000
91
92# Values with special characters (use quotes)
93MESSAGE="Hello, World!"
94JSON_CONFIG='{"key": "value"}'
95```
96
97## Dockerfile ENV
98
99Variables from Dockerfile serve as defaults:
100
101```dockerfile
102FROM node:18
103ENV NODE_ENV=development
104ENV PORT=3000
105ENV LOG_LEVEL=info
106```
107
108Override in `.env` file:
109
110```bash
111# Override NODE_ENV, keep PORT and LOG_LEVEL defaults
112NODE_ENV=production
113```
114
115Result:
116- `NODE_ENV=production` (from .env)
117- `PORT=3000` (from Dockerfile)
118- `LOG_LEVEL=info` (from Dockerfile)
119
120## Common Variables
121
122### Node.js
123
124```bash
125NODE_ENV=production
126PORT=3000
127LOG_LEVEL=warn
128```
129
130### Python
131
132```bash
133FLASK_ENV=production
134DJANGO_SETTINGS_MODULE=myapp.settings.production
135PYTHONUNBUFFERED=1
136```
137
138### Database Connections
139
140```bash
141# PostgreSQL
142DATABASE_URL=postgresql://user:pass@postgres:5432/mydb
143
144# MySQL
145DATABASE_URL=mysql://user:pass@mysql:3306/mydb
146
147# Redis
148REDIS_URL=redis://redis:6379/0
149```
150
151### External Services
152
153```bash
154# AWS
155AWS_ACCESS_KEY_ID=${pass:aws/access-key}
156AWS_SECRET_ACCESS_KEY=${pass:aws/secret-key}
157AWS_REGION=us-east-1
158
159# Stripe
160STRIPE_SECRET_KEY=${pass:stripe/secret-key}
161STRIPE_PUBLISHABLE_KEY=pk_live_...
162
163# SendGrid
164SENDGRID_API_KEY=${pass:sendgrid/api-key}
165```
166
167## Examples
168
169### Minimal
170
171```bash
172NODE_ENV=production
173PORT=3000
174```
175
176### With Database
177
178```bash
179NODE_ENV=production
180PORT=3000
181DATABASE_URL=postgresql://postgres:5432/myapp
182DATABASE_PASSWORD=${pass:myapp/db-password}
183```
184
185### Full Production
186
187```bash
188# Application
189NODE_ENV=production
190PORT=3000
191LOG_LEVEL=warn
192
193# Database
194DATABASE_URL=postgresql://postgres:5432/production
195DATABASE_PASSWORD=${pass:company/db-password}
196
197# Cache
198REDIS_URL=redis://redis:6379/0
199
200# External APIs
201STRIPE_SECRET_KEY=${pass:company/stripe-secret}
202SENDGRID_API_KEY=${pass:company/sendgrid-key}
203
204# Auth
205JWT_SECRET=${pass:company/jwt-secret}
206SESSION_SECRET=${pass:company/session-secret}
207
208# Feature flags
209ENABLE_ANALYTICS=true
210MAINTENANCE_MODE=false
211```
212
213## Viewing Container Environment
214
215```bash
216docker inspect gordon-app-mydomain-com --format '{{json .Config.Env}}' | jq
217```
218
219## Related
220
221- [Environment Configuration](../config/env.md)
222- [Secrets Configuration](../config/secrets.md)

env-variables.md RawHistoryFolder