1# Server Configuration
2
3Core server settings for Gordon.
4
5## Configuration
6
7```toml
8[server]
9registry_port = 5000                     # Container registry port
10gordon_domain = "gordon.mydomain.com"    # Gordon domain (required)
11# tls_cert_file = ""                       # Optional: PEM certificate for static TLS
12# tls_key_file = ""                        # Optional: PEM key for static TLS
13# force_https_redirect = false             # Redirect cleartext HTTP requests to HTTPS
14# legacy_registry_domains = ["registry.example.com:5000"]
15# data_dir = "~/.gordon"                 # Data storage directory (default)
16max_blob_chunk_size = "95MB"             # Max registry blob upload chunk
17max_blob_size = "1GB"                    # Max cumulative registry blob/layer upload
18
19[entrypoints.edge]
20address = ":443"                         # Deployment-selected public TCP socket
21protocol = "smart_tcp"
22```
23
24## Options
25
26| Option | Type | Default | Description |
27|--------|------|---------|-------------|
28| `registry_port` | int | `5000` | Docker registry port for image push/pull |
29| `tls_cert_file` | string | `""` | Path to PEM certificate file. When set with `tls_key_file`, matching SNI domains use this static cert before ACME or internal CA certs |
30| `tls_key_file` | string | `""` | Path to PEM private key file. Must be set together with `tls_cert_file` |
31| `force_https_redirect` | bool | `false` | Redirect cleartext HTTP requests to HTTPS on HTTP-capable edge entrypoints |
32| `gordon_domain` | string | **required** | Domain for Gordon (registry + admin API) |
33| `registry_domain` | string | - | Deprecated migration key. Set `gordon_domain` instead. |
34| `legacy_registry_domains` | []string | `[]` | Additional Gordon registry hosts treated as aliases during staged migration. See [Upgrading: Staged Registry Host Rename](../upgrading.md#staged-registry-host-rename). |
35| `data_dir` | string | `~/.gordon` | Directory for registry data, logs, and env files |
36| `max_proxy_body_size` | string | `"512MB"` | Maximum request body size for proxied requests |
37| `max_blob_chunk_size` | string | `"95MB"` | Maximum request body size for a single registry blob upload chunk |
38| `max_blob_size` | string | `"1GB"` | Maximum cumulative size for one registry blob/layer upload |
39| `registry_allowed_ips` | []string | `[]` | IPs or CIDR ranges allowed to access the registry (empty = allow all) |
40| `proxy_allowed_ips` | []string | `[]` | IPs or CIDR ranges allowed to reach HTTP proxy paths (empty = allow all) |
41| `registry_listen_address` | string | `""` | Bind address for registry (empty = all interfaces) |
42
43Public application traffic is configured under `[entrypoints]`. The standard edge listener is a `smart_tcp` socket:
44
45```toml
46[entrypoints.edge]
47address = ":443"
48protocol = "smart_tcp"
49```
50
51`entrypoints.edge.address` is not an HTTP or HTTPS port. It is the TCP address Gordon sniffs for cleartext HTTP, h2c, TLS passthrough, normal HTTPS fallback, or explicit raw TCP fallback. Gordon does not provide a built-in default public port; choose `:443`, a high port such as `:9000`, or container/firewall mappings to match your deployment.
52
53## Internal CA and TLS
54
55Gordon includes an internal certificate authority that issues on-demand TLS certificates for proxied domains served through HTTPS fallback on a TLS-capable entrypoint such as `smart_tcp`.
56
57With TLS-capable edge traffic:
58- Gordon runs an internal CA (root + intermediate) stored in `{data_dir}/pki/`
59- Leaf certificates are issued on-demand per domain (SNI-based) and cached in memory
60- The intermediate CA auto-renews before expiry
61- An onboarding page at `https://<gordon-host>/.well-known/gordon/` lets clients download the root CA certificate
62- The root CA is stable across restarts (generated once, persisted to disk)
63
64#### Custom certificates
65
66To use your own certificate (e.g. from Tailscale, Let's Encrypt, or a corporate CA) alongside ACME/internal CA fallback:
67
68```toml
69[server]
70tls_cert_file = "/etc/gordon/tls/cert.pem"
71tls_key_file = "/etc/gordon/tls/key.pem"
72```
73
74Certificate priority for normal HTTPS fallback is: static certificates first, then public ACME certificates, then Gordon's internal CA.
75
76#### Public ACME certificates
77
78Gordon can obtain public certificates through Let's Encrypt-compatible ACME when `[tls.acme]` is enabled. Normal HTTPS fallback must be available on a TLS-capable entrypoint.
79
80```toml
81[entrypoints.edge]
82address = ":443"
83protocol = "smart_tcp"
84
85[dns]
86resolvers = ["1.1.1.1:53", "8.8.8.8:53"]
87propagation_timeout = "5m"
88polling_interval = "5s"
89
90[tls.acme]
91enabled = true
92email = "admin@example.com"
93challenge = "auto"       # auto, http-01, or cloudflare-dns-01
94obtain_batch_size = 1    # maximum new certificate orders per reconcile run
95```
96
97Challenge behavior:
98- `cloudflare-dns-01` uses a Cloudflare API token from `pass`, `GORDON_CLOUDFLARE_API_TOKEN_FILE`, or `GORDON_CLOUDFLARE_API_TOKEN`; it does not need a special public port 80 edge.
99- `http-01` serves `/.well-known/acme-challenge/<token>` through Gordon's HTTP handler and requires an HTTP-capable `smart_tcp` entrypoint reachable on external port 80 for each hostname being validated.
100- `auto` selects Cloudflare DNS-01 when a token is available, otherwise falls back to HTTP-01.
101- `tls-alpn-01` is not supported.
102
103HTTP-01 requires public access to external port 80 for each hostname being validated. If you use Cloudflare in DNS-only/gray-cloud mode, your firewall/NAT must allow direct public traffic to the HTTP-capable smart TCP entrypoint. A firewall rule that only allows Cloudflare source IPs on port 80 is compatible with orange-cloud proxying, but it blocks gray-cloud HTTP-01 validation; use DNS-01 or temporarily open port 80 for direct validation.
104
105Gordon automatically includes `server.gordon_domain` in public ACME coverage in addition to configured HTTPS routes. The management hostname therefore needs the same challenge reachability: public port 80 for HTTP-01, or zone-read and DNS-edit permissions for its zone with Cloudflare DNS-01.
106
107Gordon limits new ACME certificate orders to `obtain_batch_size` per reconcile run (default `1`) so enabling ACME on an existing multi-route server does not burst through every route and hit Let's Encrypt rate limits. The management hostname consumes a place in the same batch; later reloads, restarts, or other explicit reconcile runs continue issuing remaining certificates.
108
109If the initial ACME reconcile fails (e.g. due to a transient network error or misconfiguration), Gordon logs the failure and keeps serving any existing certificates. The renewal loop retries reconcile work periodically, so missing certificates self-heal after the underlying issue is fixed without requiring a restart.
110
111For Cloudflare Full/Strict, Cloudflare terminates browser TLS at the edge and connects to Gordon over HTTPS. A public ACME certificate served by Gordon is the preferred origin certificate because Cloudflare Strict can validate it without custom origin trust. Cloudflare Flexible mode (HTTPS at the edge, HTTP to Gordon) is not end-to-end HTTPS.
112
113Static certificates have priority, then public ACME certificates, then Gordon's internal CA fallback. Gordon uses the `go-acme/lego` ACME client, including its DNS-provider support for Cloudflare DNS-01.
114
115DNS-01 uses the Cloudflare API to create TXT records, then checks public DNS visibility through `[dns].resolvers`. These resolvers are recursive resolvers (for example Cloudflare DNS or Google DNS), not the authoritative DNS provider. A domain can be hosted at Cloudflare while Gordon verifies propagation through Google DNS.
116
117The defaults avoid relying on host-local DNS. This matters on hosts using Tailscale MagicDNS, split-horizon corporate DNS, or Pi-hole, where `/etc/resolv.conf` may not reflect public DNS visibility as Let's Encrypt sees it.
118
119Because Gordon's ACME challenge mode is global, `cloudflare-dns-01` requires a Cloudflare token that can read zones and edit DNS records for every zone used by configured HTTPS routes. If that is not desirable, use `http-01` until Gordon supports per-route or per-zone challenge policy.
120
121#### Direct HTTP CA onboarding paths (`/.well-known/gordon/ca`)
122
123When Gordon is serving TLS-capable edge traffic, direct cleartext HTTP clients (those not arriving through a trusted proxy) are restricted to CA onboarding paths only:
124
125- `/.well-known/gordon/`, `/.well-known/gordon/ca`, `/.well-known/gordon/ca.crt`, `/.well-known/gordon/ca.mobileconfig` — serve the onboarding page and CA certificate downloads
126- `/.well-known/acme-challenge/*` — serves ACME HTTP-01 challenges when public ACME HTTP-01 is enabled, otherwise returns `404 Not Found`
127- All other paths return `403 Forbidden`
128
129This lets new clients discover and trust the internal CA over plain HTTP without exposing the full application. Trusted proxy traffic (e.g. from Cloudflare) continues through the normal HTTP proxy path unaffected.
130
131On HTTPS, onboarding paths are served only on `server.gordon_domain`; app hosts can use their own routes without Gordon intercepting them. If `gordon_domain` is empty, HTTPS onboarding paths are not served at all to avoid intercepting app hosts.
132
133#### HTTP to HTTPS redirect
134
135When clients connect directly (no Cloudflare or reverse proxy in front), enable `force_https_redirect` to redirect cleartext HTTP traffic to HTTPS on the same smart TCP edge.
136
137```toml
138[server]
139force_https_redirect = true
140```
141
142When `proxy_allowed_ips` is configured, non-proxy clients are redirected automatically even without this flag — trusted proxy IPs pass through to serve Cloudflare-proxied traffic.
143
144#### Firewall and Container Port Mapping
145
146Choose the bind address in `[entrypoints.edge]` and map external ports to it as needed. For example, a rootless service can bind a high port while the firewall exposes 443:
147
148```toml
149[entrypoints.edge]
150address = ":9000"
151protocol = "smart_tcp"
152```
153
154```bash
155sudo firewall-cmd --permanent --add-forward-port=port=443:proto=tcp:toport=9000
156sudo firewall-cmd --reload
157```
158
159`:443`, `:9000`, and container `-p 443:9000` mappings are deployment choices, not protocol modes.
160
161### Registry Port
162
163The `registry_port` setting controls where Gordon accepts image pushes:
164
165```toml
166[server]
167registry_port = 5000
168```
169
170Docker/Podman clients push to this port:
171
172```bash
173docker push registry.mydomain.com:5000/myapp:latest
174```
175
176If the registry is served over plain HTTP (no TLS), clients must be configured to allow insecure access. See [Troubleshooting: insecure registry](../reference/troubleshooting.md#server-gave-http-response-to-https-client) for Docker and Podman instructions.
177
178## Gordon Domain
179
180The `gordon_domain` is required and must match your DNS configuration:
181
182```toml
183[server]
184gordon_domain = "gordon.mydomain.com"
185```
186
187This domain is used for:
188- Docker login and image push/pull operations
189- Admin API access (`/admin/*` endpoints)
190- CLI remote targeting (`gordon routes --remote https://gordon.mydomain.com`)
191- Authentication endpoints (`/auth/*`)
192
193> **Warning:** If you are upgrading an older config, copy `server.registry_domain` to `server.gordon_domain` before restarting.
194
195For a staged rename, set `gordon_domain` to the new public host and add any old Gordon registry hosts that clients still use to `legacy_registry_domains` (including `host:port` forms). Gordon treats those entries as registry aliases during image matching and internal pulls, then writes canonical refs back to `gordon_domain`. Remote CLI and admin API traffic should use `gordon_domain`.
196
197Without this migration, a Host/remote-target mismatch can break routing or remote CLI token exchange.
198
199When requests arrive on an HTTP-capable edge entrypoint with this domain as the Host header, Gordon routes them to the backend services (registry and admin API).
200
201Security note:
202- Direct access to `/admin/*` on `registry_port` is blocked for non-loopback clients.
203- Admin API traffic should go through an HTTP-capable edge entrypoint such as `entrypoints.edge` with `protocol = "smart_tcp"`.
204
205> **Note:** `registry_domain` is a deprecated migration key; use `gordon_domain` for new and upgraded configs.
206
207## Data Directory
208
209The `data_dir` setting controls where Gordon stores data:
210
211```toml
212[server]
213data_dir = "~/.gordon"  # Default for user installations
214```
215
216### Directory Structure
217
218```
219~/.gordon/
220├── registry/           # Container images and manifests
221│   ├── blobs/
222│   └── manifests/
223├── env/                # Environment files per domain
224│   ├── app_mydomain_com.env
225│   └── api_mydomain_com.env
226├── logs/               # Application and container logs
227│   ├── gordon.log
228│   ├── proxy.log
229│   └── containers/
230└── secrets/            # Secrets (unsafe backend only)
231```
232
233### Permissions
234
235 Gordon creates directories with secure permissions:
236 - Directories: `0700` (owner only)
237 - Files: `0600` (owner only)
238
239 ## Maximum Proxy Body Size
240
241 The `max_proxy_body_size` setting limits the size of request bodies that Gordon will forward to backend containers:
242
243 ```toml
244 [server]
245 max_proxy_body_size = "512MB"  # Default
246 ```
247
248 **Purpose:** Prevents resource exhaustion attacks from extremely large uploads through the proxy.
249
250 **Supported units:** B, KB, MB, GB, TB (case-insensitive, decimal/1024-based)
251
252 **Examples:**
253 ```toml
254 max_proxy_body_size = "100MB"   # Stricter limit
255 max_proxy_body_size = "1GB"     # Allow larger uploads
256 max_proxy_body_size = "0"       # No limit (not recommended)
257 ```
258
259 **Behavior:**
260 - When a request exceeds the limit, Gordon returns `413 Request Entity Too Large`
261 - The limit is applied before the request reaches the backend container
262 - Uploads in progress are terminated when the limit is exceeded
263
264 **Use cases:**
265 - File upload services: increase to `1GB` or higher
266 - CI/CD artifact uploads: adjust based on your largest artifacts
267 - Tight security: reduce to `100MB` or lower
268 - Default (512MB): suitable for most applications
269
270 > **Warning:** Setting this to `0` (no limit) allows unlimited upload sizes, which can lead to disk exhaustion and DoS vulnerabilities. Always set a reasonable limit for production deployments.
271
272## Maximum Registry Blob Chunk Size
273
274The `max_blob_chunk_size` setting limits the size of a single blob upload request to the registry (`PATCH`/`PUT` under `/v2/*/blobs/uploads/*`):
275
276```toml
277[server]
278max_blob_chunk_size = "95MB"  # Default
279```
280
281**Purpose:** Prevents excessive memory usage during blob uploads while allowing large real-world image layers.
282
283**Supported units:** B, KB, MB, GB, TB (case-insensitive, decimal/1024-based)
284
285**Examples:**
286
287```toml
288max_blob_chunk_size = "256MB"  # Stricter limit
289max_blob_chunk_size = "1GB"    # Allow larger layers
290```
291
292**Behavior:**
293- When a blob chunk exceeds the limit, Gordon returns `413 Request Entity Too Large`
294- Gordon CLI uploads image layers in 50MB chunks by default, and this setting caps the maximum chunk accepted per request
295- Keep this below Cloudflare's 100MB per-request limit when operating behind Cloudflare; the default (`95MB`) is fine
296- Increase it only if you expect larger direct registry uploads from other clients
297
298## Maximum Registry Blob Size
299
300The `max_blob_size` setting limits the cumulative size of one blob/layer upload across all chunks:
301
302```toml
303[server]
304max_blob_size = "1GB"  # Default
305```
306
307**Purpose:** Prevents disk exhaustion from multi-chunk uploads where each individual chunk is below `max_blob_chunk_size` but the total blob grows without bound.
308
309**Behavior:**
310- Gordon tracks the current upload size and rejects appends that would exceed the limit.
311- Rejected uploads return an OCI-compatible `413` size error.
312- Failed uploads are cleaned up so temporary blob data does not accumulate indefinitely.
313
314## Registry IP Allowlist
315
316The `registry_allowed_ips` setting restricts registry access to specific IPs or IP ranges. Accepts both CIDR notation (`100.64.0.0/10`) and individual IPs (`203.0.113.50`). When set, only requests from listed addresses (plus localhost) can reach registry and auth endpoints. An empty list allows all traffic (default).
317
318```toml
319[server]
320registry_allowed_ips = [
321  "100.64.0.0/10",   # Tailscale CGNAT range
322  "203.0.113.50",    # single IP (treated as /32)
323]
324```
325
326**Behavior:**
327- Single IPs are automatically converted to `/32` (IPv4) or `/128` (IPv6)
328- Denied requests receive `403 Forbidden`
329- Localhost (`127.0.0.0/8`, `::1`) is always allowed so Gordon can pull from its own registry
330- Respects `trusted_proxies` for accurate client IP extraction behind reverse proxies
331- Applied before rate limiting and authentication
332- Changes require a Gordon server restart; not picked up by config hot-reload
333
334**Use cases:**
335- Restrict registry to Tailscale network: `["100.64.0.0/10"]`
336- Restrict to private subnets: `["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]`
337- Allow a specific CI server: `["100.64.0.0/10", "203.0.113.50"]`
338
339Via environment variable:
340
341```bash
342GORDON_SERVER_REGISTRY_ALLOWED_IPS=100.64.0.0/10
343```
344
345## Proxy Origin IP Allowlist
346
347The `proxy_allowed_ips` setting restricts which IPs can reach the proxy server. This prevents direct-to-origin attacks that bypass CDN protections (e.g. Cloudflare WAF, DDoS mitigation). When set, only connections from listed CIDRs (plus localhost) are accepted.
348
349```toml
350[server]
351# Only accept proxy traffic from Cloudflare edge IPs
352proxy_allowed_ips = [
353  "173.245.48.0/20", "103.21.244.0/22", "103.22.200.0/22",
354  "103.31.4.0/22", "141.101.64.0/18", "108.162.192.0/18",
355  "190.93.240.0/20", "188.114.96.0/20", "197.234.240.0/22",
356  "198.41.128.0/17", "162.158.0.0/15", "104.16.0.0/13",
357  "104.24.0.0/14", "172.64.0.0/13", "131.0.72.0/22",
358]
359```
360
361**Behavior:**
362- Checks the direct connection IP (`RemoteAddr`), not `X-Forwarded-For`
363- Localhost is always allowed
364- Denied requests receive `403 Forbidden`
365- An empty list allows all traffic (default)
366
367**Important:** Cloudflare publishes their IP ranges at [cloudflare.com/ips](https://www.cloudflare.com/ips/). Keep your allowlist updated when Cloudflare adds new ranges.
368
369## Registry Listen Address
370
371The `registry_listen_address` controls which interface the registry server binds to. By default it binds to all interfaces. Set to `127.0.0.1` to restrict registry access to localhost only, preventing containers from reaching the registry via the Docker bridge gateway.
372
373```toml
374[server]
375registry_listen_address = "127.0.0.1"  # Loopback only
376```
377
378## HSTS
379
380HSTS headers are sent automatically on TLS requests (when `r.TLS != nil`). When Gordon runs behind a TLS-terminating proxy (Cloudflare, Tailscale) and only receives plain HTTP, HSTS is not sent — the edge proxy is expected to handle it.
381
382## Examples
383
384### Development Configuration
385
386```toml
387[server]
388registry_port = 5000
389gordon_domain = "gordon.local"
390data_dir = "./dev-data"
391
392[entrypoints.edge]
393address = ":9000"
394protocol = "smart_tcp"
395```
396
397### Production Configuration
398
399```toml
400[server]
401registry_port = 5000
402gordon_domain = "gordon.company.com"
403data_dir = "/var/lib/gordon"
404
405[entrypoints.edge]
406address = ":443"
407protocol = "smart_tcp"
408```
409
410### Rootless Container Setup
411
412```toml
413[server]
414registry_port = 5000
415gordon_domain = "gordon.mydomain.com"
416
417[entrypoints.edge]
418address = ":9000"      # High port for rootless
419protocol = "smart_tcp"
420```
421
422With firewall port forwarding:
423
424```bash
425sudo firewall-cmd --permanent --add-forward-port=port=443:proto=tcp:toport=9000
426sudo firewall-cmd --reload
427```
428
429## Related
430
431- [Configuration Overview](./index.md)
432- [Installation Guide](../installation.md)
433- [Routes Configuration](./routes.md)
434- [Standalone Services](./services.md)
435- [Traffic Plane Configuration](./traffic.md)