1# Upgrading Gordon
2
3This guide covers breaking changes and migration steps between major versions.
4
5## v2.6.0 to v2.7.0
6
7### Breaking: Token Secret Required
8
9Gordon v2.7.0 requires a `token_secret` for JWT authentication. The server will not start without it configured.
10
11**Error you'll see:**
12```
13Error: token_secret is required for JWT token generation; set GORDON_AUTH_TOKEN_SECRET environment variable or configure auth.token_secret
14```
15
16**Choose one of these migration options:**
17
18#### Option A: Environment Variable (simplest)
19
20```bash
21# Generate a random secret
22export GORDON_AUTH_TOKEN_SECRET="$(openssl rand -base64 32)"
23
24# Add to your shell profile or systemd service
25echo 'export GORDON_AUTH_TOKEN_SECRET="your-secret"' >> ~/.bashrc
26```
27
28For systemd services:
29```bash
30mkdir -p ~/.config/systemd/user/gordon.service.d
31cat > ~/.config/systemd/user/gordon.service.d/token.conf << EOF
32[Service]
33Environment="GORDON_AUTH_TOKEN_SECRET=$(openssl rand -base64 32)"
34EOF
35systemctl --user daemon-reload
36systemctl --user restart gordon
37```
38
39#### Option B: Config File with Pass (recommended for production)
40
41```bash
42# Generate and store secret in pass
43openssl rand -base64 32 | pass insert -e gordon/auth/token_secret
44
45# Update your gordon.toml
46```
47
48```toml
49[auth]
50enabled = true
51secrets_backend = "pass"
52token_secret = "gordon/auth/token_secret"
53```
54
55#### Option C: Config File with Unsafe Backend (development only)
56
57```bash
58# Generate secret file
59mkdir -p ~/.gordon/secrets
60openssl rand -base64 32 > ~/.gordon/secrets/token_secret
61chmod 600 ~/.gordon/secrets/token_secret
62```
63
64```toml
65[auth]
66enabled = true
67secrets_backend = "unsafe"
68token_secret = "token_secret"
69```
70
71### Breaking: Unsafe Token Store Warning
72
73Using `secrets_backend = "unsafe"` now logs a warning on startup:
74```
75WRN using unsafe secrets backend - secrets are stored in plain text
76```
77
78This is intentional to encourage secure secret storage in production. The warning can be ignored for development.
79
80### New Features
81
82- **Attachment secrets discovery**: `gordon secrets list <domain>` now shows secrets for attachment containers
83- **Auth login command**: `gordon auth login --remote <name>` for password authentication
84- **Rate limiting**: Configurable rate limits under `[api.rate_limit]`
85
86### Security Improvements
87
88v2.7.0 includes a comprehensive security audit with:
89
90- JWT tokens now include "not before" (nbf) claim
91- SSRF protection for external routes
92- Security headers middleware
93- Rate limiting on registry and token endpoints
94- Command injection prevention in pass provider
95- Path traversal prevention in secrets store
96
97## v2.5.0 to v2.6.0
98
99### Breaking: Config Restructure
100
101The `[secrets]` and `[registry_auth]` sections were merged into `[auth]`.
102
103**Before (v2.5.0):**
104```toml
105[secrets]
106backend = "pass"
107
108[registry_auth]
109enabled = true
110type = "password"
111password_hash = "gordon/registry/password_hash"
112```
113
114**After (v2.6.0+):**
115```toml
116[auth]
117enabled = true
118secrets_backend = "pass"
119password_hash = "gordon/auth/password_hash"
120```
121
122### Breaking: Auth Enabled by Default
123
124Gordon keeps auth enabled by default. If you set `auth.enabled = false`, Gordon runs in local-only mode (`/admin/*` disabled, `/v2/*` loopback-only).
125
126### Breaking: Secret Paths Changed
127
128If using pass or sops, update your secret paths:
129- `gordon/registry/*` → `gordon/auth/*`
130
131## General Upgrade Process
132
1331. **Read the changelog** for your target version
1342. **Backup your config** before upgrading
1353. **Test in staging** if possible
1364. **Upgrade the binary**:
137   ```bash
138   curl -fsSL https://gordon.bnema.dev/install | bash
139   ```
1405. **Restart Gordon**:
141   ```bash
142   systemctl --user restart gordon
143   ```
1446. **Check logs** for any errors:
145   ```bash
146   gordon logs
147   ```
148
149## Getting Help
150
151- [GitHub Issues](https://github.com/bnema/gordon/issues)
152- [Documentation](https://gordon.bnema.dev/docs)