1# Secrets Configuration
2
3Configure how Gordon stores and retrieves sensitive data.
4
5## Configuration
6
7```toml
8[secrets]
9backend = "pass"  # "pass", "sops", or "unsafe"
10```
11
12## Options
13
14| Option | Type | Default | Description |
15|--------|------|---------|-------------|
16| `backend` | string | `"unsafe"` | Secrets storage backend |
17
18## Backends
19
20### Pass (Recommended for Production)
21
22Uses the Unix password manager (`pass`) for secure secret storage:
23
24```toml
25[secrets]
26backend = "pass"
27```
28
29**Setup:**
30```bash
31# Install pass
32sudo apt install pass
33
34# Initialize with GPG key
35pass init your-gpg-key-id
36
37# Store secrets
38pass insert gordon/registry/password_hash
39pass insert gordon/registry/token_secret
40```
41
42**Usage in config:**
43```toml
44[registry_auth]
45password_hash = "gordon/registry/password_hash"  # Path in pass store
46token_secret = "gordon/registry/token_secret"
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### SOPS
56
57Uses Mozilla SOPS for encrypted file-based secrets:
58
59```toml
60[secrets]
61backend = "sops"
62```
63
64**Setup:**
65```bash
66# Install sops
67brew install sops  # macOS
68# or download from https://github.com/getsops/sops/releases
69
70# Create encrypted secrets file
71sops secrets.yaml
72```
73
74**Usage in env files:**
75```bash
76# ~/.gordon/env/app_mydomain_com.env
77API_SECRET=${sops:secrets.yaml:api.secret}
78DB_PASSWORD=${sops:secrets.yaml:database.password}
79```
80
81**Benefits:**
82- Multiple encryption backends (AWS KMS, GCP KMS, Azure Key Vault, PGP)
83- YAML/JSON file encryption
84- Git-friendly (encrypted files in repo)
85
86### Unsafe (Development Only)
87
88Stores secrets as plain text files:
89
90```toml
91[secrets]
92backend = "unsafe"
93```
94
95**Storage location:**
96```
97{data_dir}/secrets/
98├── gordon/
99│   └── registry/
100│       ├── password_hash
101│       └── token_secret
102```
103
104**Usage:**
105```bash
106# Create secret
107mkdir -p ~/.gordon/secrets/gordon/registry
108echo "your-bcrypt-hash" > ~/.gordon/secrets/gordon/registry/password_hash
109```
110
111> **Warning:** Only use for local development. Secrets are stored in plain text.
112
113## Secret Provider Syntax
114
115In environment files, reference secrets using provider syntax:
116
117### Pass Provider
118
119```bash
120# ${pass:<path>}
121DATABASE_PASSWORD=${pass:myapp/database/password}
122API_KEY=${pass:myapp/api-key}
123```
124
125### SOPS Provider
126
127```bash
128# ${sops:<file>:<key.path>}
129DATABASE_PASSWORD=${sops:secrets.yaml:database.password}
130API_SECRET=${sops:production.yaml:api.secret.key}
131```
132
133## Examples
134
135### Production with Pass
136
137```toml
138[secrets]
139backend = "pass"
140
141[registry_auth]
142enabled = true
143type = "token"
144token_secret = "gordon/registry/token_secret"
145```
146
147```bash
148# Setup
149pass insert gordon/registry/token_secret
150# Enter a random 32+ character string
151
152# Generate tokens
153gordon auth token generate --subject deploy --expiry 0
154```
155
156### Development with Unsafe
157
158```toml
159[secrets]
160backend = "unsafe"
161
162[registry_auth]
163enabled = false
164```
165
166### Enterprise with SOPS
167
168```toml
169[secrets]
170backend = "sops"
171
172[registry_auth]
173enabled = true
174type = "token"
175token_secret = "gordon/registry/token_secret"
176```
177
178Environment file:
179```bash
180# ~/.gordon/env/app_company_com.env
181NODE_ENV=production
182DATABASE_URL=postgresql://db:5432/app
183DATABASE_PASSWORD=${sops:secrets.yaml:database.password}
184API_KEY=${sops:secrets.yaml:api.key}
185JWT_SECRET=${sops:secrets.yaml:jwt.secret}
186```
187
188## Security Recommendations
189
1901. **Production**: Always use `pass` or `sops` backend
1912. **Never commit**: Don't commit unencrypted secrets to git
1923. **Rotate regularly**: Regenerate tokens and passwords periodically
1934. **Least privilege**: Use separate secrets per environment
194
195## Related
196
197- [Registry Authentication](./registry-auth.md)
198- [Environment Variables](./env.md)
199- [Configuration Overview](./index.md)