upgrading.md Raw History Folder

Upgrading Gordon

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

Route-Domain Validation

Route keys must be plain hostnames. Use inline tables like "app.example.com" = { image = "myapp:latest" }. Gordon still reads legacy http://... route entries for backward compatibility and rewrites them on the next save. Update [routes], CLI commands, and automation that reference the old values.

Next major: Unified smart TCP entrypoints

Breaking: `server.port` / `server.tls_port` no longer define public listeners

Public application traffic is configured entrypoint-first. Migrate old HTTP/HTTPS listener settings to a smart TCP edge entrypoint.

Before:

[server]
port = 8088
tls_port = 8443
registry_port = 5000
gordon_domain = "gordon.example.com"

After:

[server]
registry_port = 5000
gordon_domain = "gordon.example.com"

[entrypoints.edge]
address = ":443"
protocol = "smart_tcp"

edge is the conventional route default, but it has no built-in port. address = ":443", address = ":9000", firewall forwarding, and container mappings such as -p 443:9000 are deployment choices, not protocol modes. The smart_tcp protocol accepts TCP, sniffs HTTP/h2c/TLS, routes TLS passthrough by SNI when configured, and otherwise uses normal Gordon HTTPS fallback.

If you run rootless and cannot bind 443 directly, bind a high port and map external ports to it:

[entrypoints.edge]
address = ":9000"
protocol = "smart_tcp"

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

Keep server.registry_port for Docker/Podman push and pull traffic; it is separate from public app entrypoints.

ACME migration notes

DNS-01 (cloudflare-dns-01) does not require a special external port 80 edge.
HTTP-01 requires an HTTP-capable smart_tcp entrypoint reachable on external port 80 for each hostname being validated.
TLS-ALPN-01 is unsupported.
Normal HTTPS fallback certificate priority is static certificates, then public ACME certificates, then Gordon's internal CA.

v2.30.0 to v2.31.0

Breaking: Public listener migration

server.port and server.tls_port no longer create public listeners. Gordon refuses to start when either legacy key is present without an [entrypoints] entry, preventing routes from silently becoming unavailable.

Replace the legacy listener settings with a route-capable entrypoint:

[server]
registry_port = 5000
gordon_domain = "gordon.example.com"

[entrypoints.edge]
address = ":443"
protocol = "smart_tcp"

Keep server.registry_port for Docker and Podman registry traffic. For public TLS, configure [tls.acme] or static certificates; do not use server.tls_port.

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. Remove TLS-capable entrypoints to disable the internal CA and skip this requirement.

Breaking: `server.gordon_domain` Replaces `server.registry_domain`

Gordon now uses server.gordon_domain as the public registry and admin host. Migrate older configs that still set only server.registry_domain before restarting:

Before:

[server]
registry_domain = "gordon.example.com"

After:

[server]
gordon_domain = "gordon.example.com"

If you do not migrate, gordon status --remote ... and gordon routes list --remote ... can fail with /auth/token 404, and reg-domain/v2/ or /admin/status can return 404.

Staged Registry Host Rename

If you cannot rename the Gordon registry host in one step, keep the new host in server.gordon_domain and list the old Gordon registry hosts in server.legacy_registry_domains during the cutover:

[server]
gordon_domain = "gordon.example.com"
legacy_registry_domains = [
  "registry.example.com",
  "registry.example.com:5000",
]

Recommended rollout:

Set gordon_domain to the new host.
Add every old Gordon registry host that clients still use to legacy_registry_domains.
Restart Gordon.
Move Docker/Podman logins, pushes, pulls, and image references to the new host.
Remove legacy_registry_domains after every client has moved.

During the transition, Gordon treats both the current and legacy hosts as its own registry for image matching and internal pulls, then saves canonical refs back to gordon_domain. Remote CLI and admin API traffic should use the new gordon_domain.

Breaking: `gordon rollback` Renamed to `gordon pin`

If you have scripts or runbooks using gordon rollback, switch them to gordon pin:

gordon pin app.example.com
gordon pin app.example.com --tag v2.30.1
gordon pin list app.example.com

Breaking-ish: `routes list` Is Inventory-Only

gordon routes list now shows domain/image inventory only. Detailed runtime state, HTTP probe status, and attachment status moved to gordon routes status.

If you have automation parsing status-like fields from routes list, migrate it to routes status --json.

New: Public ACME TLS

Gordon can now obtain public certificates with [tls.acme] using either http-01 or cloudflare-dns-01.

Normal HTTPS fallback must be available on a TLS-capable entrypoint
http-01 needs an HTTP-capable smart TCP entrypoint reachable on external port 80 for each hostname being validated
cloudflare-dns-01 needs a Cloudflare token with zone-read and DNS-edit access for every zone used by HTTPS routes and does not require a special port-80 edge
obtain_batch_size limits new ACME orders per reconcile pass to reduce rate-limit spikes

New: DNS Resolver Settings for ACME DNS-01

[dns] controls the recursive resolvers Gordon uses to verify public DNS propagation for ACME DNS-01.

Add this if you need non-default resolvers, split-horizon-aware testing, or a slower propagation window:

[dns]
resolvers = ["1.1.1.1:53", "8.8.8.8:53"]
propagation_timeout = "5m"
polling_interval = "5s"

Runtime Change: Managed Containers Use Restart Policy `always`

Newly created managed route containers now use the runtime restart policy always. Existing containers pick this up on redeploy/recreate.

This improves crash recovery and keeps Docker/Podman behavior aligned with Gordon's startup reconciliation.

New: Saved Remote Inference for Targeted Commands

When you do not pass --remote, Gordon can now infer a saved remote for some target-based commands when exactly one configured remote matches the route, image, attachment target, or repository.

If multiple remotes match or probing fails, Gordon now stops and asks you to pass --remote explicitly instead of guessing.

New: Dedicated Access Log

You can now enable logging.access_log.* for a dedicated HTTP access log separate from the main process log. This is useful for request auditing, GoAccess, CrowdSec, or fail2ban-style tooling.

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 locally
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## Route-Domain Validation
6
7Route keys must be plain hostnames. Use inline tables like `"app.example.com" = { image = "myapp:latest" }`. Gordon still reads legacy `http://...` route entries for backward compatibility and rewrites them on the next save. Update `[routes]`, CLI commands, and automation that reference the old values.
8
9## Next major: Unified smart TCP entrypoints
10
11### Breaking: `server.port` / `server.tls_port` no longer define public listeners
12
13Public application traffic is configured entrypoint-first. Migrate old HTTP/HTTPS listener settings to a smart TCP edge entrypoint.
14
15**Before:**
16
17```toml
18[server]
19port = 8088
20tls_port = 8443
21registry_port = 5000
22gordon_domain = "gordon.example.com"
23```
24
25**After:**
26
27```toml
28[server]
29registry_port = 5000
30gordon_domain = "gordon.example.com"
31
32[entrypoints.edge]
33address = ":443"
34protocol = "smart_tcp"
35```
36
37`edge` is the conventional route default, but it has no built-in port. `address = ":443"`, `address = ":9000"`, firewall forwarding, and container mappings such as `-p 443:9000` are deployment choices, not protocol modes. The `smart_tcp` protocol accepts TCP, sniffs HTTP/h2c/TLS, routes TLS passthrough by SNI when configured, and otherwise uses normal Gordon HTTPS fallback.
38
39If you run rootless and cannot bind 443 directly, bind a high port and map external ports to it:
40
41```toml
42[entrypoints.edge]
43address = ":9000"
44protocol = "smart_tcp"
45```
46
47```bash
48sudo firewall-cmd --permanent --add-forward-port=port=80:proto=tcp:toport=9000
49sudo firewall-cmd --permanent --add-forward-port=port=443:proto=tcp:toport=9000
50sudo firewall-cmd --reload
51```
52
53Keep `server.registry_port` for Docker/Podman push and pull traffic; it is separate from public app entrypoints.
54
55### ACME migration notes
56
57- DNS-01 (`cloudflare-dns-01`) does not require a special external port 80 edge.
58- HTTP-01 requires an HTTP-capable `smart_tcp` entrypoint reachable on external port 80 for each hostname being validated.
59- TLS-ALPN-01 is unsupported.
60- Normal HTTPS fallback certificate priority is static certificates, then public ACME certificates, then Gordon's internal CA.
61
62## v2.30.0 to v2.31.0
63
64### Breaking: Public listener migration
65
66`server.port` and `server.tls_port` no longer create public listeners. Gordon refuses to start when either legacy key is present without an `[entrypoints]` entry, preventing routes from silently becoming unavailable.
67
68Replace the legacy listener settings with a route-capable entrypoint:
69
70```toml
71[server]
72registry_port = 5000
73gordon_domain = "gordon.example.com"
74
75[entrypoints.edge]
76address = ":443"
77protocol = "smart_tcp"
78```
79
80Keep `server.registry_port` for Docker and Podman registry traffic. For public TLS, configure `[tls.acme]` or static certificates; do not use `server.tls_port`.
81
82### Required for Cloudflare/Proxy Setups: `proxy_allowed_ips`
83
84The 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`:
85
86```toml
87[server]
88proxy_allowed_ips = [
89  "173.245.48.0/20", "103.21.244.0/22", "103.22.200.0/22",
90  "103.31.4.0/22", "141.101.64.0/18", "108.162.192.0/18",
91  "190.93.240.0/20", "188.114.96.0/20", "197.234.240.0/22",
92  "198.41.128.0/17", "162.158.0.0/15", "104.16.0.0/13",
93  "104.24.0.0/14", "172.64.0.0/13", "131.0.72.0/22",
94]
95```
96
97Without this, all proxied HTTP traffic returns `403 Forbidden`. Remove TLS-capable entrypoints to disable the internal CA and skip this requirement.
98
99### Breaking: `server.gordon_domain` Replaces `server.registry_domain`
100
101Gordon now uses `server.gordon_domain` as the public registry and admin host. Migrate older configs that still set only `server.registry_domain` before restarting:
102
103**Before:**
104
105```toml
106[server]
107registry_domain = "gordon.example.com"
108```
109
110**After:**
111
112```toml
113[server]
114gordon_domain = "gordon.example.com"
115```
116
117If you do not migrate, `gordon status --remote ...` and `gordon routes list --remote ...` can fail with `/auth/token` `404`, and `reg-domain/v2/` or `/admin/status` can return `404`.
118
119### Staged Registry Host Rename
120
121If you cannot rename the Gordon registry host in one step, keep the new host in `server.gordon_domain` and list the old Gordon registry hosts in `server.legacy_registry_domains` during the cutover:
122
123```toml
124[server]
125gordon_domain = "gordon.example.com"
126legacy_registry_domains = [
127  "registry.example.com",
128  "registry.example.com:5000",
129]
130```
131
132Recommended rollout:
133
1341. Set `gordon_domain` to the new host.
1352. Add every old Gordon registry host that clients still use to `legacy_registry_domains`.
1363. Restart Gordon.
1374. Move Docker/Podman logins, pushes, pulls, and image references to the new host.
1385. Remove `legacy_registry_domains` after every client has moved.
139
140During the transition, Gordon treats both the current and legacy hosts as its own registry for image matching and internal pulls, then saves canonical refs back to `gordon_domain`. Remote CLI and admin API traffic should use the new `gordon_domain`.
141
142### Breaking: `gordon rollback` Renamed to `gordon pin`
143
144If you have scripts or runbooks using `gordon rollback`, switch them to `gordon pin`:
145
146```bash
147gordon pin app.example.com
148gordon pin app.example.com --tag v2.30.1
149gordon pin list app.example.com
150```
151
152### Breaking-ish: `routes list` Is Inventory-Only
153
154`gordon routes list` now shows domain/image inventory only. Detailed runtime state, HTTP probe status, and attachment status moved to `gordon routes status`.
155
156If you have automation parsing status-like fields from `routes list`, migrate it to `routes status --json`.
157
158### New: Public ACME TLS
159
160Gordon can now obtain public certificates with `[tls.acme]` using either `http-01` or `cloudflare-dns-01`.
161
162- Normal HTTPS fallback must be available on a TLS-capable entrypoint
163- `http-01` needs an HTTP-capable smart TCP entrypoint reachable on external port 80 for each hostname being validated
164- `cloudflare-dns-01` needs a Cloudflare token with zone-read and DNS-edit access for every zone used by HTTPS routes and does not require a special port-80 edge
165- `obtain_batch_size` limits new ACME orders per reconcile pass to reduce rate-limit spikes
166
167### New: DNS Resolver Settings for ACME DNS-01
168
169`[dns]` controls the recursive resolvers Gordon uses to verify public DNS propagation for ACME DNS-01.
170
171Add this if you need non-default resolvers, split-horizon-aware testing, or a slower propagation window:
172
173```toml
174[dns]
175resolvers = ["1.1.1.1:53", "8.8.8.8:53"]
176propagation_timeout = "5m"
177polling_interval = "5s"
178```
179
180### Runtime Change: Managed Containers Use Restart Policy `always`
181
182Newly created managed route containers now use the runtime restart policy `always`. Existing containers pick this up on redeploy/recreate.
183
184This improves crash recovery and keeps Docker/Podman behavior aligned with Gordon's startup reconciliation.
185
186### New: Saved Remote Inference for Targeted Commands
187
188When you do not pass `--remote`, Gordon can now infer a saved remote for some target-based commands when exactly one configured remote matches the route, image, attachment target, or repository.
189
190If multiple remotes match or probing fails, Gordon now stops and asks you to pass `--remote` explicitly instead of guessing.
191
192### New: Dedicated Access Log
193
194You can now enable `logging.access_log.*` for a dedicated HTTP access log separate from the main process log. This is useful for request auditing, GoAccess, CrowdSec, or fail2ban-style tooling.
195
196## v2.16.0 to v2.30.0
197
198### Breaking: Password Authentication Removed
199
200Gordon v2.30.0 removes password-based authentication entirely. Only token-based authentication is supported.
201
202**What changed:**
203
204- `auth.type = "password"` is no longer accepted
205- `auth.password` and `auth.password_hash` config fields are removed
206- The `gordon auth password hash` CLI command is removed
207- The `gordon auth login` command now requires `--token` (no more interactive password prompt)
208- The `/auth/password` endpoint now returns `410 Gone`
209- Long-lived tokens are no longer accepted on admin/registry endpoints — they must be exchanged for ephemeral tokens via `/auth/token`
210
211**New features:**
212
213- `auth.access_token_ttl` configures the lifetime of ephemeral access tokens issued by `/auth/token` (default: `"15m"`)
214- `gordon auth show-token` prints the stored token for a remote
215- `gordon auth logout` removes the stored token locally
216- Automatic token exchange: the CLI transparently exchanges long-lived tokens for ephemeral ones before API calls
217- Admin scopes (`admin:*:*`, `admin:routes:read`, etc.) allow fine-grained access control for remote CLI operations
218
219**Migration steps:**
220
2211. **Before upgrading**, generate a token on your current Gordon instance:
222
223   ```bash
224   gordon auth token generate --subject deploy --scopes "push,pull" --expiry 0
225   ```
226
227   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.
228
2292. **Update remotes** to use the generated token:
230
231   ```bash
232   gordon auth login --token <token>
233   # or
234   gordon remotes set-token prod <token>
235   ```
236
2373. **Update your config** to remove password fields:
238
239   **Before (v2.16.0):**
240
241   ```toml
242   [auth]
243   enabled = true
244   secrets_backend = "pass"
245   username = "deploy"
246   password_hash = "gordon/auth/password_hash"
247   token_secret = "gordon/auth/token_secret"
248   ```
249
250   **After (v2.30.0):**
251
252   ```toml
253   [auth]
254   enabled = true
255   secrets_backend = "pass"
256   token_secret = "gordon/auth/token_secret"
257   access_token_ttl = "15m"
258   ```
259
2604. **Update CI/CD pipelines** to use `GORDON_TOKEN` environment variable for authentication. See the [deployment guides](./deployment/index.md).
261
2625. **Upgrade the binary** and restart:
263
264   ```bash
265   curl -fsSL https://gordon.bnema.dev/install | bash
266   systemctl --user restart gordon
267   ```
268
2696. **Verify** the server starts without errors:
270
271   ```bash
272   journalctl --user -u gordon -f
273   ```
274
275### New: Configurable Access Token TTL
276
277Ephemeral access tokens issued by `/auth/token` now have a configurable lifetime via `auth.access_token_ttl` (default `"15m"`, maximum `"1h"`).
278
279Tokens 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`.
280
281```toml
282[auth]
283access_token_ttl = "30m"
284```
285
286### New: Admin Scopes
287
288Tokens can now include fine-grained admin scopes for remote CLI operations:
289
290```bash
291# Full admin access
292gordon auth token generate --subject admin --scopes "push,pull,admin:*:*" --expiry 0
293
294# Read-only monitoring
295gordon auth token generate --subject monitor --scopes "admin:status:read" --expiry 30d
296
297# CI deploy with route read + config write
298gordon auth token generate --subject ci --scopes "push,pull,admin:routes:read,admin:config:write" --expiry 0
299```
300
301See [Token Scopes](./config/auth.md#token-scopes) for the full list.
302
303## v2.6.0 to v2.7.0
304
305### Breaking: Token Secret Required
306
307Gordon v2.7.0 requires a `token_secret` for JWT authentication. The server will not start without it configured.
308
309**Error you'll see:**
310```
311Error: token_secret is required for JWT token generation; set GORDON_AUTH_TOKEN_SECRET environment variable or configure auth.token_secret
312```
313
314**Choose one of these migration options:**
315
316#### Option A: Environment Variable (simplest)
317
318```bash
319# Generate a random secret
320export GORDON_AUTH_TOKEN_SECRET="$(openssl rand -base64 32)"
321
322# Add to your shell profile or systemd service
323echo 'export GORDON_AUTH_TOKEN_SECRET="your-secret"' >> ~/.bashrc
324```
325
326For systemd services:
327```bash
328mkdir -p ~/.config/systemd/user/gordon.service.d
329cat > ~/.config/systemd/user/gordon.service.d/token.conf << EOF
330[Service]
331Environment="GORDON_AUTH_TOKEN_SECRET=$(openssl rand -base64 32)"
332EOF
333systemctl --user daemon-reload
334systemctl --user restart gordon
335```
336
337#### Option B: Config File with Pass (recommended for production)
338
339```bash
340# Generate and store secret in pass
341openssl rand -base64 32 | pass insert -e gordon/auth/token_secret
342
343# Update your gordon.toml
344```
345
346```toml
347[auth]
348enabled = true
349secrets_backend = "pass"
350token_secret = "gordon/auth/token_secret"
351```
352
353#### Option C: Config File with Unsafe Backend (development only)
354
355```bash
356# Generate secret file
357mkdir -p ~/.gordon/secrets
358openssl rand -base64 32 > ~/.gordon/secrets/token_secret
359chmod 600 ~/.gordon/secrets/token_secret
360```
361
362```toml
363[auth]
364enabled = true
365secrets_backend = "unsafe"
366token_secret = "token_secret"
367```
368
369### Breaking: Unsafe Token Store Warning
370
371Using `secrets_backend = "unsafe"` now logs a warning on startup:
372```
373WRN using unsafe secrets backend - secrets are stored in plain text
374```
375
376This is intentional to encourage secure secret storage in production. The warning can be ignored for development.
377
378### New Features
379
380- **Attachment secrets discovery**: `gordon secrets list <domain>` now shows secrets for attachment containers
381- **Auth login command**: `gordon auth login --remote <name>` for token authentication
382- **Rate limiting**: Configurable rate limits under `[api.rate_limit]`
383
384### Security Improvements
385
386v2.7.0 includes a comprehensive security audit with:
387
388- JWT tokens now include "not before" (nbf) claim
389- SSRF protection for external routes
390- Security headers middleware
391- Rate limiting on registry and token endpoints
392- Command injection prevention in pass provider
393- Path traversal prevention in secrets store
394
395## v2.5.0 to v2.6.0
396
397### Breaking: Config Restructure
398
399The `[secrets]` and `[registry_auth]` sections were merged into `[auth]`.
400
401**Before (v2.5.0):**
402```toml
403[secrets]
404backend = "pass"
405
406[registry_auth]
407enabled = true
408type = "password"
409password_hash = "gordon/registry/password_hash"
410```
411
412**After (v2.6.0+):**
413```toml
414[auth]
415enabled = true
416secrets_backend = "pass"
417password_hash = "gordon/auth/password_hash"
418```
419
420### Breaking: Auth Enabled by Default
421
422Gordon keeps auth enabled by default. If you set `auth.enabled = false`, Gordon runs in local-only mode (`/admin/*` disabled, `/v2/*` loopback-only).
423
424### Breaking: Secret Paths Changed
425
426If using pass or sops, update your secret paths:
427- `gordon/registry/*` → `gordon/auth/*`
428
429## General Upgrade Process
430
4311. **Read the changelog** for your target version
4322. **Backup your config** before upgrading
4333. **Test in staging** if possible
4344. **Upgrade the binary**:
435   ```bash
436   curl -fsSL https://gordon.bnema.dev/install | bash
437   ```
4385. **Restart Gordon**:
439   ```bash
440   systemctl --user restart gordon
441   ```
4426. **Check logs** for any errors:
443   ```bash
444   gordon logs
445   ```
446
447## Getting Help
448
449- [GitHub Issues](https://github.com/bnema/gordon/issues)
450- [Documentation](https://gordon.bnema.dev/docs)

upgrading.md RawHistoryFolder