env.md Raw History Folder

Environment Variables

App environment comes from two places: public [env] in the app file (injected into all services at deploy) and per-service [service.secrets] (values in pass, resolved at deploy). This page covers the installation [env] store location and the provider syntax used in env files.

Configuration

[env]
dir = "~/.gordon/env"  # Default location

Options

Option	Type	Default	Description
`dir`	string	`~/.gordon/env`	Directory for the installation secret store

How It Works

The [env] directory backs the installation secret store:

With the pass backend, gordon secrets set <domain> --from-file stores per-domain secrets in pass under gordon/env/<sanitized-domain>/<KEY> (dots/colons/slashes → underscores). Env files are not used for secrets.
With the pass backend, Gordon imports eligible plaintext .env files into pass at startup and removes each source file only after every entry is stored successfully. If a destination entry already exists or an import fails, Gordon leaves the source file in place for operator review.
With the sops or unsafe backend, env files remain the source of truth; use ${sops:...} syntax for encrypted values when secrets_backend = "sops".

App containers do NOT read these files: services receive the app file's [env] plus their resolved [service.secrets] at deploy time (see App Manifest).

Secret Provider Syntax

Reference secrets from configured backends in env files:

Pass (Unix Password Manager)

DATABASE_PASSWORD=${pass:myapp/database/password}
API_SECRET=${pass:company/api-secret}
JWT_KEY=${pass:production/jwt-signing-key}

SOPS (Encrypted Files)

DATABASE_PASSWORD=${sops:secrets.yaml:database.password}
API_SECRET=${sops:production.yaml:api.secret}
STRIPE_KEY=${sops:secrets.yaml:stripe.api_key}

Syntax Reference

Provider	Syntax	Example
pass	`${pass:<path>}`	`${pass:myapp/db-password}`
sops	`${sops:<file>:<key.path>}`	`${sops:secrets.yaml:db.password}`

File Permissions

The env directory uses secure permissions:

Directory: 0700 (owner only)
Files: 0600 (owner only)

source

1# Environment Variables
2
3App environment comes from two places: public `[env]` in the app file (injected into all services at deploy) and per-service `[service.secrets]` (values in pass, resolved at deploy). This page covers the installation `[env]` store location and the provider syntax used in env files.
4
5## Configuration
6
7```toml
8[env]
9dir = "~/.gordon/env"  # Default location
10```
11
12## Options
13
14| Option | Type | Default | Description |
15|--------|------|---------|-------------|
16| `dir` | string | `~/.gordon/env` | Directory for the installation secret store |
17
18## How It Works
19
20The `[env]` directory backs the installation secret store:
21
22- With the `pass` backend, `gordon secrets set <domain> --from-file` stores per-domain secrets in pass under `gordon/env/<sanitized-domain>/<KEY>` (dots/colons/slashes → underscores). Env files are not used for secrets.
23- With the `pass` backend, Gordon imports eligible plaintext `.env` files into pass at startup and removes each source file only after every entry is stored successfully. If a destination entry already exists or an import fails, Gordon leaves the source file in place for operator review.
24- With the `sops` or `unsafe` backend, env files remain the source of truth; use `${sops:...}` syntax for encrypted values when `secrets_backend = "sops"`.
25
26App containers do NOT read these files: services receive the app file's `[env]` plus their resolved `[service.secrets]` at deploy time (see [App Manifest](./apps.md)).
27
28## Secret Provider Syntax
29
30Reference secrets from configured backends in env files:
31
32### Pass (Unix Password Manager)
33
34```bash
35DATABASE_PASSWORD=${pass:myapp/database/password}
36API_SECRET=${pass:company/api-secret}
37JWT_KEY=${pass:production/jwt-signing-key}
38```
39
40### SOPS (Encrypted Files)
41
42```bash
43DATABASE_PASSWORD=${sops:secrets.yaml:database.password}
44API_SECRET=${sops:production.yaml:api.secret}
45STRIPE_KEY=${sops:secrets.yaml:stripe.api_key}
46```
47
48### Syntax Reference
49
50| Provider | Syntax | Example |
51|----------|--------|---------|
52| pass | `${pass:<path>}` | `${pass:myapp/db-password}` |
53| sops | `${sops:<file>:<key.path>}` | `${sops:secrets.yaml:db.password}` |
54
55## File Permissions
56
57The env directory uses secure permissions:
58- Directory: `0700` (owner only)
59- Files: `0600` (owner only)
60
61## Related
62
63- [Secrets Configuration](./secrets.md)
64- [App Manifest](./apps.md)

env.md RawHistoryFolder