detached 45239b9

docs: add upgrading guide for v2.7.0 breaking changes

- Add docs/upgrading.md with migration steps for token_secret requirement
- Document v2.6.0 to v2.7.0 breaking changes
- Document v2.5.0 to v2.6.0 migration for reference
- Link upgrading guide from docs index
commit
45239b9aa3aba8934e00391f3578bb95aadd7812
author
brice · · 2026-01-18 08:26 UTC
parent
830beb2
signature
unsigned
2 files · +153 -0
Unified
UnifiedSplit
M docs/index.md +1 -0
@@ -39,6 +39,7 @@ Gordon runs on your VPS and provides:
3939
4040 - [Getting Started](./getting-started.md) - Deploy your first app in minutes
4141 - [Installation](./installation.md) - Detailed installation instructions
42+- [Upgrading](./upgrading.md) - Migration guide for breaking changes
4243 - [Concepts](./concepts.md) - Core concepts and architecture
4344
4445 ### Configuration
@@ -39,6 +39,7 @@ Gordon runs on your VPS and provides:
39 39
40 - [Getting Started](./getting-started.md) - Deploy your first app in minutes40 - [Getting Started](./getting-started.md) - Deploy your first app in minutes
41 - [Installation](./installation.md) - Detailed installation instructions41 - [Installation](./installation.md) - Detailed installation instructions
42+- [Upgrading](./upgrading.md) - Migration guide for breaking changes
42 - [Concepts](./concepts.md) - Core concepts and architecture43 - [Concepts](./concepts.md) - Core concepts and architecture
43 44
44 ### Configuration45 ### Configuration
A docs/upgrading.md +152 -0
@@ -0,0 +1,152 @@
1+# Upgrading Gordon
2+
3+This 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+
9+Gordon 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+```
13+Error: 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
22+export GORDON_AUTH_TOKEN_SECRET="$(openssl rand -base64 32)"
23+
24+# Add to your shell profile or systemd service
25+echo 'export GORDON_AUTH_TOKEN_SECRET="your-secret"' >> ~/.bashrc
26+```
27+
28+For systemd services:
29+```bash
30+mkdir -p ~/.config/systemd/user/gordon.service.d
31+cat > ~/.config/systemd/user/gordon.service.d/token.conf << EOF
32+[Service]
33+Environment="GORDON_AUTH_TOKEN_SECRET=$(openssl rand -base64 32)"
34+EOF
35+systemctl --user daemon-reload
36+systemctl --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
43+openssl rand -base64 32 | pass insert -e gordon/auth/token_secret
44+
45+# Update your gordon.toml
46+```
47+
48+```toml
49+[auth]
50+enabled = true
51+secrets_backend = "pass"
52+token_secret = "gordon/auth/token_secret"
53+```
54+
55+#### Option C: Config File with Unsafe Backend (development only)
56+
57+```bash
58+# Generate secret file
59+mkdir -p ~/.gordon/secrets
60+openssl rand -base64 32 > ~/.gordon/secrets/token_secret
61+chmod 600 ~/.gordon/secrets/token_secret
62+```
63+
64+```toml
65+[auth]
66+enabled = true
67+secrets_backend = "unsafe"
68+token_secret = "token_secret"
69+```
70+
71+### Breaking: Unsafe Token Store Warning
72+
73+Using `secrets_backend = "unsafe"` now logs a warning on startup:
74+```
75+WRN using unsafe secrets backend - secrets are stored in plain text
76+```
77+
78+This 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+
88+v2.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+
101+The `[secrets]` and `[registry_auth]` sections were merged into `[auth]`.
102+
103+**Before (v2.5.0):**
104+```toml
105+[secrets]
106+backend = "pass"
107+
108+[registry_auth]
109+enabled = true
110+type = "password"
111+password_hash = "gordon/registry/password_hash"
112+```
113+
114+**After (v2.6.0+):**
115+```toml
116+[auth]
117+enabled = true
118+secrets_backend = "pass"
119+password_hash = "gordon/auth/password_hash"
120+```
121+
122+### Breaking: Auth Enabled by Default
123+
124+Gordon now requires explicit auth configuration. Set `auth.enabled = false` to disable.
125+
126+### Breaking: Secret Paths Changed
127+
128+If using pass or sops, update your secret paths:
129+- `gordon/registry/*` → `gordon/auth/*`
130+
131+## General Upgrade Process
132+
133+1. **Read the changelog** for your target version
134+2. **Backup your config** before upgrading
135+3. **Test in staging** if possible
136+4. **Upgrade the binary**:
137+ ```bash
138+ curl -fsSL https://gordon.bnema.dev/install | bash
139+ ```
140+5. **Restart Gordon**:
141+ ```bash
142+ systemctl --user restart gordon
143+ ```
144+6. **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)
@@ -0,0 +1,152 @@
1+# Upgrading Gordon
2+
3+This 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+
9+Gordon 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+```
13+Error: 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
22+export GORDON_AUTH_TOKEN_SECRET="$(openssl rand -base64 32)"
23+
24+# Add to your shell profile or systemd service
25+echo 'export GORDON_AUTH_TOKEN_SECRET="your-secret"' >> ~/.bashrc
26+```
27+
28+For systemd services:
29+```bash
30+mkdir -p ~/.config/systemd/user/gordon.service.d
31+cat > ~/.config/systemd/user/gordon.service.d/token.conf << EOF
32+[Service]
33+Environment="GORDON_AUTH_TOKEN_SECRET=$(openssl rand -base64 32)"
34+EOF
35+systemctl --user daemon-reload
36+systemctl --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
43+openssl rand -base64 32 | pass insert -e gordon/auth/token_secret
44+
45+# Update your gordon.toml
46+```
47+
48+```toml
49+[auth]
50+enabled = true
51+secrets_backend = "pass"
52+token_secret = "gordon/auth/token_secret"
53+```
54+
55+#### Option C: Config File with Unsafe Backend (development only)
56+
57+```bash
58+# Generate secret file
59+mkdir -p ~/.gordon/secrets
60+openssl rand -base64 32 > ~/.gordon/secrets/token_secret
61+chmod 600 ~/.gordon/secrets/token_secret
62+```
63+
64+```toml
65+[auth]
66+enabled = true
67+secrets_backend = "unsafe"
68+token_secret = "token_secret"
69+```
70+
71+### Breaking: Unsafe Token Store Warning
72+
73+Using `secrets_backend = "unsafe"` now logs a warning on startup:
74+```
75+WRN using unsafe secrets backend - secrets are stored in plain text
76+```
77+
78+This 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+
88+v2.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+
101+The `[secrets]` and `[registry_auth]` sections were merged into `[auth]`.
102+
103+**Before (v2.5.0):**
104+```toml
105+[secrets]
106+backend = "pass"
107+
108+[registry_auth]
109+enabled = true
110+type = "password"
111+password_hash = "gordon/registry/password_hash"
112+```
113+
114+**After (v2.6.0+):**
115+```toml
116+[auth]
117+enabled = true
118+secrets_backend = "pass"
119+password_hash = "gordon/auth/password_hash"
120+```
121+
122+### Breaking: Auth Enabled by Default
123+
124+Gordon now requires explicit auth configuration. Set `auth.enabled = false` to disable.
125+
126+### Breaking: Secret Paths Changed
127+
128+If using pass or sops, update your secret paths:
129+- `gordon/registry/*` → `gordon/auth/*`
130+
131+## General Upgrade Process
132+
133+1. **Read the changelog** for your target version
134+2. **Backup your config** before upgrading
135+3. **Test in staging** if possible
136+4. **Upgrade the binary**:
137+ ```bash
138+ curl -fsSL https://gordon.bnema.dev/install | bash
139+ ```
140+5. **Restart Gordon**:
141+ ```bash
142+ systemctl --user restart gordon
143+ ```
144+6. **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)

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. Elsewhere: into the side panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 7

Tags 106

↑↓ moveenter openesc close