upgrading.md Raw History Folder

Upgrading Gordon

This guide covers breaking changes and migration steps between major versions.

v2.30.0 to v2.31.0

Breaking: Default Port Changes

Gordon now defaults to unprivileged ports that work without root or firewall rules:

Setting	Old default	New default
`server.port`	`80`	`8088`
`server.registry_port`	`5000`	`5000` (unchanged)
`server.tls_port`	(n/a)	`8443`

If you relied on the old defaults (no explicit port in your config), add the port explicitly:

[server]
port = 80

Or set up firewall port forwarding to the new defaults:

sudo firewall-cmd --permanent --add-forward-port=port=80:proto=tcp:toport=8088
sudo firewall-cmd --permanent --add-forward-port=port=443:proto=tcp:toport=8443
sudo firewall-cmd --reload

New: Internal Certificate Authority

Gordon now includes an internal CA for automatic on-demand TLS. Set tls_port = 0 to disable. See Server Configuration for details.

Required for Cloudflare/Proxy Setups: `proxy_allowed_ips`

The internal CA's HTTP onboarding gate rejects non-localhost HTTP requests by default. If Gordon sits behind Cloudflare or another reverse proxy, add the proxy's edge IPs to proxy_allowed_ips:

[server]
proxy_allowed_ips = [
  "173.245.48.0/20", "103.21.244.0/22", "103.22.200.0/22",
  "103.31.4.0/22", "141.101.64.0/18", "108.162.192.0/18",
  "190.93.240.0/20", "188.114.96.0/20", "197.234.240.0/22",
  "198.41.128.0/17", "162.158.0.0/15", "104.16.0.0/13",
  "104.24.0.0/14", "172.64.0.0/13", "131.0.72.0/22",
]

Without this, all proxied HTTP traffic returns 403 Forbidden. Set tls_port = 0 to disable the internal CA and skip this requirement.

v2.16.0 to v2.30.0

Breaking: Password Authentication Removed

Gordon v2.30.0 removes password-based authentication entirely. Only token-based authentication is supported.

What changed:

auth.type = "password" is no longer accepted
auth.password and auth.password_hash config fields are removed
The gordon auth password hash CLI command is removed
The gordon auth login command now requires --token (no more interactive password prompt)
The /auth/password endpoint now returns 410 Gone
Long-lived tokens are no longer accepted on admin/registry endpoints — they must be exchanged for ephemeral tokens via /auth/token

New features:

auth.access_token_ttl configures the lifetime of ephemeral access tokens issued by /auth/token (default: "15m")
gordon auth show-token prints the stored token for a remote
gordon auth logout removes the stored token (with optional --revoke)
Automatic token exchange: the CLI transparently exchanges long-lived tokens for ephemeral ones before API calls
Admin scopes (admin:*:*, admin:routes:read, etc.) allow fine-grained access control for remote CLI operations

Migration steps:

Before upgrading, generate a token on your current Gordon instance:
```
gordon auth token generate --subject deploy --scopes "push,pull" --expiry 0
```
Save this token securely. You will need it after upgrading. Admin scopes (admin:*:*) are only available after upgrading to v2.30.0 — regenerate your token with admin scopes after the upgrade if needed.

Update remotes to use the generated token:

gordon auth login --token <token>
# or
gordon remotes set-token prod <token>

Update your config to remove password fields:

Before (v2.16.0):

[auth]
enabled = true
secrets_backend = "pass"
username = "deploy"
password_hash = "gordon/auth/password_hash"
token_secret = "gordon/auth/token_secret"

After (v2.30.0):

[auth]
enabled = true
secrets_backend = "pass"
token_secret = "gordon/auth/token_secret"
access_token_ttl = "15m"

Update CI/CD pipelines to use GORDON_TOKEN environment variable for authentication. See the deployment guides.

Upgrade the binary and restart:

curl -fsSL https://gordon.bnema.dev/install | bash
systemctl --user restart gordon

Verify the server starts without errors:
```
journalctl --user -u gordon -f
```

New: Configurable Access Token TTL

Ephemeral access tokens issued by /auth/token now have a configurable lifetime via auth.access_token_ttl (default "15m", maximum "1h").

Tokens with a lifetime at or below MaxAccessTokenLifetime (1 hour) are treated as ephemeral: they skip token store validation for performance, which means they cannot be individually revoked. They become invalid only when they naturally expire. Shortening auth.access_token_ttl only reduces the exposure window; it does not enable per-token revocation. If you need explicit revocation, use a stored long-lived token instead of /auth/token.

[auth]
access_token_ttl = "30m"

New: Admin Scopes

Tokens can now include fine-grained admin scopes for remote CLI operations:

# Full admin access
gordon auth token generate --subject admin --scopes "push,pull,admin:*:*" --expiry 0

# Read-only monitoring
gordon auth token generate --subject monitor --scopes "admin:status:read" --expiry 30d

# CI deploy with route read + config write
gordon auth token generate --subject ci --scopes "push,pull,admin:routes:read,admin:config:write" --expiry 0

See Token Scopes for the full list.

v2.6.0 to v2.7.0

Breaking: Token Secret Required

Gordon v2.7.0 requires a token_secret for JWT authentication. The server will not start without it configured.

Error you'll see:

Error: token_secret is required for JWT token generation; set GORDON_AUTH_TOKEN_SECRET environment variable or configure auth.token_secret

Choose one of these migration options:

Option A: Environment Variable (simplest)

# Generate a random secret
export GORDON_AUTH_TOKEN_SECRET="$(openssl rand -base64 32)"

# Add to your shell profile or systemd service
echo 'export GORDON_AUTH_TOKEN_SECRET="your-secret"' >> ~/.bashrc

For systemd services:

mkdir -p ~/.config/systemd/user/gordon.service.d
cat > ~/.config/systemd/user/gordon.service.d/token.conf << EOF
[Service]
Environment="GORDON_AUTH_TOKEN_SECRET=$(openssl rand -base64 32)"
EOF
systemctl --user daemon-reload
systemctl --user restart gordon

Option B: Config File with Pass (recommended for production)

# Generate and store secret in pass
openssl rand -base64 32 | pass insert -e gordon/auth/token_secret

# Update your gordon.toml

[auth]
enabled = true
secrets_backend = "pass"
token_secret = "gordon/auth/token_secret"

Option C: Config File with Unsafe Backend (development only)

# Generate secret file
mkdir -p ~/.gordon/secrets
openssl rand -base64 32 > ~/.gordon/secrets/token_secret
chmod 600 ~/.gordon/secrets/token_secret

[auth]
enabled = true
secrets_backend = "unsafe"
token_secret = "token_secret"

Breaking: Unsafe Token Store Warning

Using secrets_backend = "unsafe" now logs a warning on startup:

WRN using unsafe secrets backend - secrets are stored in plain text

This is intentional to encourage secure secret storage in production. The warning can be ignored for development.

New Features

Attachment secrets discovery: gordon secrets list <domain> now shows secrets for attachment containers
Auth login command: gordon auth login --remote <name> for token authentication
Rate limiting: Configurable rate limits under [api.rate_limit]

Security Improvements

v2.7.0 includes a comprehensive security audit with:

JWT tokens now include "not before" (nbf) claim
SSRF protection for external routes
Security headers middleware
Rate limiting on registry and token endpoints
Command injection prevention in pass provider
Path traversal prevention in secrets store

v2.5.0 to v2.6.0

Breaking: Config Restructure

The [secrets] and [registry_auth] sections were merged into [auth].

Before (v2.5.0):

[secrets]
backend = "pass"

[registry_auth]
enabled = true
type = "password"
password_hash = "gordon/registry/password_hash"

After (v2.6.0+):

[auth]
enabled = true
secrets_backend = "pass"
password_hash = "gordon/auth/password_hash"

Breaking: Auth Enabled by Default

Gordon keeps auth enabled by default. If you set auth.enabled = false, Gordon runs in local-only mode (/admin/* disabled, /v2/* loopback-only).

Breaking: Secret Paths Changed

If using pass or sops, update your secret paths:

gordon/registry/* → gordon/auth/*

General Upgrade Process

Read the changelog for your target version
Backup your config before upgrading
Test in staging if possible

Upgrade the binary:

curl -fsSL https://gordon.bnema.dev/install | bash

Restart Gordon:
```
systemctl --user restart gordon
```
Check logs for any errors:
```
gordon logs
```

Getting Help

source

1# Upgrading Gordon
2
3This guide covers breaking changes and migration steps between major versions.
4
5## v2.30.0 to v2.31.0
6
7### Breaking: Default Port Changes
8
9Gordon now defaults to unprivileged ports that work without root or firewall rules:
10
11| Setting | Old default | New default |
12|---------|-------------|-------------|
13| `server.port` | `80` | `8088` |
14| `server.registry_port` | `5000` | `5000` (unchanged) |
15| `server.tls_port` | *(n/a)* | `8443` |
16
17**If you relied on the old defaults** (no explicit `port` in your config), add the port explicitly:
18
19```toml
20[server]
21port = 80
22```
23
24Or set up firewall port forwarding to the new defaults:
25
26```bash
27sudo firewall-cmd --permanent --add-forward-port=port=80:proto=tcp:toport=8088
28sudo firewall-cmd --permanent --add-forward-port=port=443:proto=tcp:toport=8443
29sudo firewall-cmd --reload
30```
31
32### New: Internal Certificate Authority
33
34Gordon now includes an internal CA for automatic on-demand TLS. Set `tls_port = 0` to disable. See [Server Configuration](./config/server.md#internal-ca-and-tls) for details.
35
36### Required for Cloudflare/Proxy Setups: `proxy_allowed_ips`
37
38The internal CA's HTTP onboarding gate rejects non-localhost HTTP requests by default. If Gordon sits behind Cloudflare or another reverse proxy, add the proxy's edge IPs to `proxy_allowed_ips`:
39
40```toml
41[server]
42proxy_allowed_ips = [
43  "173.245.48.0/20", "103.21.244.0/22", "103.22.200.0/22",
44  "103.31.4.0/22", "141.101.64.0/18", "108.162.192.0/18",
45  "190.93.240.0/20", "188.114.96.0/20", "197.234.240.0/22",
46  "198.41.128.0/17", "162.158.0.0/15", "104.16.0.0/13",
47  "104.24.0.0/14", "172.64.0.0/13", "131.0.72.0/22",
48]
49```
50
51Without this, all proxied HTTP traffic returns `403 Forbidden`. Set `tls_port = 0` to disable the internal CA and skip this requirement.
52
53## v2.16.0 to v2.30.0
54
55### Breaking: Password Authentication Removed
56
57Gordon v2.30.0 removes password-based authentication entirely. Only token-based authentication is supported.
58
59**What changed:**
60
61- `auth.type = "password"` is no longer accepted
62- `auth.password` and `auth.password_hash` config fields are removed
63- The `gordon auth password hash` CLI command is removed
64- The `gordon auth login` command now requires `--token` (no more interactive password prompt)
65- The `/auth/password` endpoint now returns `410 Gone`
66- Long-lived tokens are no longer accepted on admin/registry endpoints — they must be exchanged for ephemeral tokens via `/auth/token`
67
68**New features:**
69
70- `auth.access_token_ttl` configures the lifetime of ephemeral access tokens issued by `/auth/token` (default: `"15m"`)
71- `gordon auth show-token` prints the stored token for a remote
72- `gordon auth logout` removes the stored token (with optional `--revoke`)
73- Automatic token exchange: the CLI transparently exchanges long-lived tokens for ephemeral ones before API calls
74- Admin scopes (`admin:*:*`, `admin:routes:read`, etc.) allow fine-grained access control for remote CLI operations
75
76**Migration steps:**
77
781. **Before upgrading**, generate a token on your current Gordon instance:
79
80   ```bash
81   gordon auth token generate --subject deploy --scopes "push,pull" --expiry 0
82   ```
83
84   Save this token securely. You will need it after upgrading. Admin scopes (`admin:*:*`) are only available after upgrading to v2.30.0 — regenerate your token with admin scopes after the upgrade if needed.
85
862. **Update remotes** to use the generated token:
87
88   ```bash
89   gordon auth login --token <token>
90   # or
91   gordon remotes set-token prod <token>
92   ```
93
943. **Update your config** to remove password fields:
95
96   **Before (v2.16.0):**
97
98   ```toml
99   [auth]
100   enabled = true
101   secrets_backend = "pass"
102   username = "deploy"
103   password_hash = "gordon/auth/password_hash"
104   token_secret = "gordon/auth/token_secret"
105   ```
106
107   **After (v2.30.0):**
108
109   ```toml
110   [auth]
111   enabled = true
112   secrets_backend = "pass"
113   token_secret = "gordon/auth/token_secret"
114   access_token_ttl = "15m"
115   ```
116
1174. **Update CI/CD pipelines** to use `GORDON_TOKEN` environment variable for authentication. See the [deployment guides](./deployment/index.md).
118
1195. **Upgrade the binary** and restart:
120
121   ```bash
122   curl -fsSL https://gordon.bnema.dev/install | bash
123   systemctl --user restart gordon
124   ```
125
1266. **Verify** the server starts without errors:
127
128   ```bash
129   journalctl --user -u gordon -f
130   ```
131
132### New: Configurable Access Token TTL
133
134Ephemeral access tokens issued by `/auth/token` now have a configurable lifetime via `auth.access_token_ttl` (default `"15m"`, maximum `"1h"`).
135
136Tokens with a lifetime at or below `MaxAccessTokenLifetime` (1 hour) are treated as ephemeral: they skip token store validation for performance, which means they **cannot be individually revoked**. They become invalid only when they naturally expire. Shortening `auth.access_token_ttl` only reduces the exposure window; it does not enable per-token revocation. If you need explicit revocation, use a stored long-lived token instead of `/auth/token`.
137
138```toml
139[auth]
140access_token_ttl = "30m"
141```
142
143### New: Admin Scopes
144
145Tokens can now include fine-grained admin scopes for remote CLI operations:
146
147```bash
148# Full admin access
149gordon auth token generate --subject admin --scopes "push,pull,admin:*:*" --expiry 0
150
151# Read-only monitoring
152gordon auth token generate --subject monitor --scopes "admin:status:read" --expiry 30d
153
154# CI deploy with route read + config write
155gordon auth token generate --subject ci --scopes "push,pull,admin:routes:read,admin:config:write" --expiry 0
156```
157
158See [Token Scopes](./config/auth.md#token-scopes) for the full list.
159
160## v2.6.0 to v2.7.0
161
162### Breaking: Token Secret Required
163
164Gordon v2.7.0 requires a `token_secret` for JWT authentication. The server will not start without it configured.
165
166**Error you'll see:**
167```
168Error: token_secret is required for JWT token generation; set GORDON_AUTH_TOKEN_SECRET environment variable or configure auth.token_secret
169```
170
171**Choose one of these migration options:**
172
173#### Option A: Environment Variable (simplest)
174
175```bash
176# Generate a random secret
177export GORDON_AUTH_TOKEN_SECRET="$(openssl rand -base64 32)"
178
179# Add to your shell profile or systemd service
180echo 'export GORDON_AUTH_TOKEN_SECRET="your-secret"' >> ~/.bashrc
181```
182
183For systemd services:
184```bash
185mkdir -p ~/.config/systemd/user/gordon.service.d
186cat > ~/.config/systemd/user/gordon.service.d/token.conf << EOF
187[Service]
188Environment="GORDON_AUTH_TOKEN_SECRET=$(openssl rand -base64 32)"
189EOF
190systemctl --user daemon-reload
191systemctl --user restart gordon
192```
193
194#### Option B: Config File with Pass (recommended for production)
195
196```bash
197# Generate and store secret in pass
198openssl rand -base64 32 | pass insert -e gordon/auth/token_secret
199
200# Update your gordon.toml
201```
202
203```toml
204[auth]
205enabled = true
206secrets_backend = "pass"
207token_secret = "gordon/auth/token_secret"
208```
209
210#### Option C: Config File with Unsafe Backend (development only)
211
212```bash
213# Generate secret file
214mkdir -p ~/.gordon/secrets
215openssl rand -base64 32 > ~/.gordon/secrets/token_secret
216chmod 600 ~/.gordon/secrets/token_secret
217```
218
219```toml
220[auth]
221enabled = true
222secrets_backend = "unsafe"
223token_secret = "token_secret"
224```
225
226### Breaking: Unsafe Token Store Warning
227
228Using `secrets_backend = "unsafe"` now logs a warning on startup:
229```
230WRN using unsafe secrets backend - secrets are stored in plain text
231```
232
233This is intentional to encourage secure secret storage in production. The warning can be ignored for development.
234
235### New Features
236
237- **Attachment secrets discovery**: `gordon secrets list <domain>` now shows secrets for attachment containers
238- **Auth login command**: `gordon auth login --remote <name>` for token authentication
239- **Rate limiting**: Configurable rate limits under `[api.rate_limit]`
240
241### Security Improvements
242
243v2.7.0 includes a comprehensive security audit with:
244
245- JWT tokens now include "not before" (nbf) claim
246- SSRF protection for external routes
247- Security headers middleware
248- Rate limiting on registry and token endpoints
249- Command injection prevention in pass provider
250- Path traversal prevention in secrets store
251
252## v2.5.0 to v2.6.0
253
254### Breaking: Config Restructure
255
256The `[secrets]` and `[registry_auth]` sections were merged into `[auth]`.
257
258**Before (v2.5.0):**
259```toml
260[secrets]
261backend = "pass"
262
263[registry_auth]
264enabled = true
265type = "password"
266password_hash = "gordon/registry/password_hash"
267```
268
269**After (v2.6.0+):**
270```toml
271[auth]
272enabled = true
273secrets_backend = "pass"
274password_hash = "gordon/auth/password_hash"
275```
276
277### Breaking: Auth Enabled by Default
278
279Gordon keeps auth enabled by default. If you set `auth.enabled = false`, Gordon runs in local-only mode (`/admin/*` disabled, `/v2/*` loopback-only).
280
281### Breaking: Secret Paths Changed
282
283If using pass or sops, update your secret paths:
284- `gordon/registry/*` → `gordon/auth/*`
285
286## General Upgrade Process
287
2881. **Read the changelog** for your target version
2892. **Backup your config** before upgrading
2903. **Test in staging** if possible
2914. **Upgrade the binary**:
292   ```bash
293   curl -fsSL https://gordon.bnema.dev/install | bash
294   ```
2955. **Restart Gordon**:
296   ```bash
297   systemctl --user restart gordon
298   ```
2996. **Check logs** for any errors:
300   ```bash
301   gordon logs
302   ```
303
304## Getting Help
305
306- [GitHub Issues](https://github.com/bnema/gordon/issues)
307- [Documentation](https://gordon.bnema.dev/docs)

upgrading.md RawHistoryFolder