1# Secrets Configuration
2
3Configure how Gordon stores and retrieves sensitive data. Two separate stores exist: installation secrets (this page) and app secret values (managed with `gordon apps secrets`, values in pass under `gordon/apps/<uuid>/<service>/<name>`).
4
5## Configuration
6
7The secrets backend is configured within the `[auth]` section:
8
9```toml
10[auth]
11secrets_backend = "pass"  # "pass", "sops", or "unsafe"
12```
13
14## Options
15
16| Option | Type | Default | Description |
17|--------|------|---------|-------------|
18| `secrets_backend` | string | `"unsafe"` | Secrets storage backend |
19
20## Backends
21
22### Pass (Recommended for Production)
23
24Uses the Unix password manager (`pass`) for secure secret storage:
25
26```toml
27[auth]
28secrets_backend = "pass"
29```
30
31**Setup:**
32```bash
33# Install pass
34sudo apt install pass
35
36# Initialize with GPG key
37pass init your-gpg-key-id
38
39# Store secrets
40pass insert gordon/auth/token_secret
41```
42
43**Usage in config:**
44```toml
45[auth]
46token_secret = "gordon/auth/token_secret"  # Path in pass store
47```
48
49**Benefits:**
50- GPG-encrypted storage
51- Version control friendly (encrypted files)
52- Standard Unix tooling
53- Works with team GPG keys
54
55**Installation secrets storage:**
56- `gordon secrets set <domain> --from-file` stores per-domain secrets in pass under `gordon/env/<sanitized-domain>/<KEY>` (dots/colons/slashes → underscores)
57- Eligible plaintext `.env` files are imported into pass at startup and removed only after all entries are stored successfully; conflicts or failures leave the source file for operator review
58
59### SOPS
60
61Uses Mozilla SOPS for encrypted file-based secrets:
62
63```toml
64[auth]
65secrets_backend = "sops"
66```
67
68**Setup:**
69```bash
70# Install sops
71brew install sops  # macOS
72# or download from https://github.com/getsops/sops/releases
73
74# Create encrypted secrets file
75sops secrets.yaml
76```
77
78**Usage in env files:**
79```bash
80API_SECRET=${sops:secrets.yaml:api.secret}
81DB_PASSWORD=${sops:secrets.yaml:database.password}
82```
83
84**Benefits:**
85- Multiple encryption backends (AWS KMS, GCP KMS, Azure Key Vault, PGP)
86- YAML/JSON file encryption
87- Git-friendly (encrypted files in repo)
88
89**Security:**
90- Absolute paths are rejected to prevent arbitrary file access
91- Path traversal (`..`) is blocked
92- Only relative paths from your config directory are allowed
93
94### Unsafe (Development Only)
95
96Stores secrets as plain text files:
97
98```toml
99[auth]
100secrets_backend = "unsafe"
101```
102
103**Storage location:**
104```
105{data_dir}/secrets/
106├── gordon/
107│   └── auth/
108│       └── token_secret
109```
110
111**Usage:**
112```bash
113# Create secret
114mkdir -p ~/.gordon/secrets/gordon/auth
115echo "your-token-secret" > ~/.gordon/secrets/gordon/auth/token_secret
116```
117
118> **Warning:** Only use for local development. Secrets are stored in plain text.
119
120## Secret Provider Syntax
121
122In environment files, reference secrets using provider syntax:
123
124### Pass Provider
125
126```bash
127# ${pass:<path>}
128DATABASE_PASSWORD=${pass:myapp/database/password}
129API_KEY=${pass:myapp/api-key}
130```
131
132### SOPS Provider
133
134```bash
135# ${sops:<file>:<key.path>}
136DATABASE_PASSWORD=${sops:secrets.yaml:database.password}
137API_SECRET=${sops:production.yaml:api.key}
138```
139
140## App Secret Values
141
142App secret names are registered in the app manifest (`[service.secrets]` maps ENV name to secret name); values are written separately and stay in pass:
143
144```bash
145gordon apps secrets set blog --service web DATABASE_URL=...
146```
147
148Values affect the next deploy/restart, never running containers. Only key names are ever echoed back, never values. See [App Manifest](./apps.md) and [Apps CLI](../cli/apps.md).
149
150## Examples
151
152### Production with Pass
153
154```toml
155[auth]
156enabled = true
157secrets_backend = "pass"
158token_secret = "gordon/auth/token_secret"
159```
160
161```bash
162# Setup
163pass insert gordon/auth/token_secret
164# Enter a random 32+ character string
165
166# Generate tokens
167gordon auth token generate --subject deploy --expiry 0
168```
169
170### Development with Unsafe
171
172```toml
173[auth]
174enabled = false
175secrets_backend = "unsafe"
176```
177
178## Security Recommendations
179
1801. **Production**: Always use `pass` or `sops` backend
1812. **Never commit**: Don't commit unencrypted secrets to git (app files must never contain secret values)
1823. **Rotate regularly**: Regenerate tokens and passwords periodically
1834. **Least privilege**: Use separate secrets per environment
1845. **Path validation**: SOPS provider rejects absolute paths and path traversal attempts for security
185
186## Related
187
188- [Authentication](./auth.md)
189- [App Manifest](./apps.md)
190- [Configuration Overview](./index.md)