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