1# Server Configuration
2
3Core server settings for Gordon.
4
5## Configuration
6
7```toml
8[server]
9port = 8088                              # HTTP proxy port
10registry_port = 5000                     # Container registry port
11tls_port = 8443                          # HTTPS listener port (0 = disabled)
12# tls_cert_file = ""                       # Optional: PEM certificate for static TLS
13# tls_key_file = ""                        # Optional: PEM key for static TLS
14# force_https_redirect = false             # Redirect all HTTP traffic to HTTPS
15gordon_domain = "gordon.mydomain.com"    # Gordon domain (required)
16# data_dir = "~/.gordon"                 # Data storage directory (default)
17max_blob_chunk_size = "95MB"             # Max registry blob upload chunk
18max_blob_size = "1GB"                    # Max cumulative registry blob/layer upload
19```
20
21## Options
22
23| Option | Type | Default | Description |
24|--------|------|---------|-------------|
25| `port` | int | `8088` | HTTP proxy port for routing traffic to containers |
26| `registry_port` | int | `5000` | Docker registry port for image push/pull |
27| `tls_port` | int | `8443` | HTTPS listener port with internal CA. Set to `0` to disable TLS entirely |
28| `tls_cert_file` | string | `""` | Path to PEM certificate file. When set (with `tls_key_file`), this cert is served for matching SNI domains; unmatched domains fall through to the internal CA |
29| `tls_key_file` | string | `""` | Path to PEM private key file. Must be set together with `tls_cert_file` |
30| `force_https_redirect` | bool | `false` | Redirect all HTTP requests to the HTTPS port. For direct-access setups without a TLS-terminating proxy |
31| `gordon_domain` | string | **required** | Domain for Gordon (registry + admin API) |
32| `registry_domain` | string | - | Deprecated migration key. Set `gordon_domain` instead. |
33| `data_dir` | string | `~/.gordon` | Directory for registry data, logs, and env files |
34| `max_proxy_body_size` | string | `"512MB"` | Maximum request body size for proxied requests |
35| `max_blob_chunk_size` | string | `"95MB"` | Maximum request body size for a single registry blob upload chunk |
36| `max_blob_size` | string | `"1GB"` | Maximum cumulative size for one registry blob/layer upload |
37| `registry_allowed_ips` | []string | `[]` | IPs or CIDR ranges allowed to access the registry (empty = allow all) |
38| `proxy_allowed_ips` | []string | `[]` | IPs or CIDR ranges allowed to reach the proxy (empty = allow all) |
39| `registry_listen_address` | string | `""` | Bind address for registry (empty = all interfaces) |
40
41## Port Configuration
42
43### Proxy Port
44
45The `port` setting controls where Gordon listens for HTTP traffic:
46
47```toml
48[server]
49port = 8080  # Use 8080 for rootless containers with port forwarding
50```
51
52For rootless containers, you'll typically use a high port and configure firewall port forwarding:
53
54```bash
55# Forward port 80 to 8080
56sudo firewall-cmd --permanent --add-forward-port=port=80:proto=tcp:toport=8080
57```
58
59### Internal CA and TLS
60
61Gordon includes an internal certificate authority that issues on-demand TLS certificates for proxied domains. The HTTPS listener is enabled by default on `tls_port` (8443).
62
63```toml
64[server]
65tls_port = 8443   # Default. Set to 0 to disable TLS entirely.
66```
67
68With TLS enabled:
69- Gordon runs an internal CA (root + intermediate) stored in `{data_dir}/pki/`
70- Leaf certificates are issued on-demand per domain (SNI-based) and cached in memory
71- The intermediate CA auto-renews before expiry
72- An onboarding page at `https://<gordon-host>:<tls_port>/ca` lets clients download the root CA certificate
73- The root CA is stable across restarts (generated once, persisted to disk)
74
75#### Custom certificates
76
77To use your own certificate (e.g. from Tailscale, Let's Encrypt, or a corporate CA) alongside the internal CA:
78
79```toml
80[server]
81tls_cert_file = "/etc/gordon/tls/cert.pem"
82tls_key_file = "/etc/gordon/tls/key.pem"
83```
84
85The static certificate is served for SNI-matching domains (including wildcards). All other domains get on-demand certs from the internal CA.
86
87#### Public ACME certificates
88
89Gordon can obtain public certificates through Let's Encrypt-compatible ACME when `[tls.acme]` is enabled. The HTTPS listener must also be enabled (`server.tls_port > 0`).
90
91```toml
92[server]
93tls_port = 8443
94
95[tls.acme]
96enabled = true
97email = "admin@example.com"
98challenge = "auto" # auto, http-01, or cloudflare-dns-01
99```
100
101Challenge behavior:
102- `http-01` serves `/.well-known/acme-challenge/<token>` on the HTTP proxy port.
103- `cloudflare-dns-01` uses a Cloudflare API token from `pass`, `GORDON_CLOUDFLARE_API_TOKEN_FILE`, or `GORDON_CLOUDFLARE_API_TOKEN`.
104- `auto` selects Cloudflare DNS-01 when a token is available, otherwise falls back to HTTP-01.
105
106Static 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.
107
108#### Direct HTTP Onboarding
109
110When `tls_port` is non-zero, direct HTTP clients (those not arriving through a trusted proxy) are restricted to CA onboarding paths only:
111
112- `/`, `/ca`, `/ca.crt`, `/ca.mobileconfig` — serve the onboarding page and CA certificate downloads
113- `/.well-known/acme-challenge/*` — serves ACME HTTP-01 challenges when public ACME HTTP-01 is enabled, otherwise returns `404 Not Found`
114- All other paths return `403 Forbidden`
115
116This 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.
117
118The onboarding page is also available on HTTPS at `/ca`.
119
120#### HTTP to HTTPS redirect
121
122When clients connect directly (no Cloudflare or reverse proxy in front), enable `force_https_redirect` to redirect all HTTP traffic to the HTTPS port. Direct HTTP onboarding paths are still served even with this flag enabled.
123
124```toml
125[server]
126force_https_redirect = true
127```
128
129When `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.
130
131#### Disabling TLS
132
133For setups where TLS is handled entirely by an external proxy (Cloudflare, nginx, etc.):
134
135```toml
136[server]
137tls_port = 0   # No HTTPS listener, no internal CA generated
138```
139
140#### Firewall port forwarding
141
142For rootless user services, forward 443 to the high port at the firewall:
143
144```bash
145# Forward 443 -> 8443
146sudo firewall-cmd --permanent --add-forward-port=port=443:proto=tcp:toport=8443
147sudo firewall-cmd --reload
148```
149
150With firewalld and Tailscale:
151
152```bash
153# Verify tailscale0 is in trusted zone
154sudo firewall-cmd --get-zone-of-interface=tailscale0
155
156# If needed, place tailscale0 in trusted
157sudo firewall-cmd --permanent --zone=trusted --add-interface=tailscale0
158sudo firewall-cmd --reload
159
160# Forward 443 -> 8443 permanently (IPv4 + IPv6)
161sudo firewall-cmd --permanent --zone=trusted --add-rich-rule='rule family=ipv4 forward-port port=443 protocol=tcp to-port=8443'
162sudo firewall-cmd --permanent --zone=trusted --add-rich-rule='rule family=ipv6 forward-port port=443 protocol=tcp to-port=8443'
163sudo firewall-cmd --reload
164```
165
166### Registry Port
167
168The `registry_port` setting controls where Gordon accepts image pushes:
169
170```toml
171[server]
172registry_port = 5000
173```
174
175Docker/Podman clients push to this port:
176
177```bash
178docker push registry.mydomain.com:5000/myapp:latest
179```
180
181If 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.
182
183## Gordon Domain
184
185The `gordon_domain` is required and must match your DNS configuration:
186
187```toml
188[server]
189gordon_domain = "gordon.mydomain.com"
190```
191
192This domain is used for:
193- Docker login and image push/pull operations
194- Admin API access (`/admin/*` endpoints)
195- CLI remote targeting (`gordon routes --remote https://gordon.mydomain.com`)
196- Authentication endpoints (`/auth/*`)
197
198> **Warning:** If you are upgrading an older config, copy `server.registry_domain` to `server.gordon_domain` before restarting.
199
200Without this migration, a Host/remote-target mismatch can break routing or remote CLI token exchange.
201
202When requests arrive on the proxy port with this domain as the Host header, Gordon routes them to the backend services (registry and admin API).
203
204Security note:
205- Direct access to `/admin/*` on `registry_port` is blocked for non-loopback clients.
206- Admin API traffic should go through the main proxy listener (`server.port`/`server.tls_port`).
207
208> **Note:** `registry_domain` is a deprecated migration key; use `gordon_domain` for new and upgraded configs.
209
210## Data Directory
211
212The `data_dir` setting controls where Gordon stores data:
213
214```toml
215[server]
216data_dir = "~/.gordon"  # Default for user installations
217```
218
219### Directory Structure
220
221```
222~/.gordon/
223├── registry/           # Container images and manifests
224│   ├── blobs/
225│   └── manifests/
226├── env/                # Environment files per domain
227│   ├── app_mydomain_com.env
228│   └── api_mydomain_com.env
229├── logs/               # Application and container logs
230│   ├── gordon.log
231│   ├── proxy.log
232│   └── containers/
233└── secrets/            # Secrets (unsafe backend only)
234```
235
236### Permissions
237
238 Gordon creates directories with secure permissions:
239 - Directories: `0700` (owner only)
240 - Files: `0600` (owner only)
241
242 ## Maximum Proxy Body Size
243
244 The `max_proxy_body_size` setting limits the size of request bodies that Gordon will forward to backend containers:
245
246 ```toml
247 [server]
248 max_proxy_body_size = "512MB"  # Default
249 ```
250
251 **Purpose:** Prevents resource exhaustion attacks from extremely large uploads through the proxy.
252
253 **Supported units:** B, KB, MB, GB, TB (case-insensitive, decimal/1024-based)
254
255 **Examples:**
256 ```toml
257 max_proxy_body_size = "100MB"   # Stricter limit
258 max_proxy_body_size = "1GB"     # Allow larger uploads
259 max_proxy_body_size = "0"       # No limit (not recommended)
260 ```
261
262 **Behavior:**
263 - When a request exceeds the limit, Gordon returns `413 Request Entity Too Large`
264 - The limit is applied before the request reaches the backend container
265 - Uploads in progress are terminated when the limit is exceeded
266
267 **Use cases:**
268 - File upload services: increase to `1GB` or higher
269 - CI/CD artifact uploads: adjust based on your largest artifacts
270 - Tight security: reduce to `100MB` or lower
271 - Default (512MB): suitable for most applications
272
273 > **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.
274
275## Maximum Registry Blob Chunk Size
276
277The `max_blob_chunk_size` setting limits the size of a single blob upload request to the registry (`PATCH`/`PUT` under `/v2/*/blobs/uploads/*`):
278
279```toml
280[server]
281max_blob_chunk_size = "95MB"  # Default
282```
283
284**Purpose:** Prevents excessive memory usage during blob uploads while allowing large real-world image layers.
285
286**Supported units:** B, KB, MB, GB, TB (case-insensitive, decimal/1024-based)
287
288**Examples:**
289
290```toml
291max_blob_chunk_size = "256MB"  # Stricter limit
292max_blob_chunk_size = "1GB"    # Allow larger layers
293```
294
295**Behavior:**
296- When a blob chunk exceeds the limit, Gordon returns `413 Request Entity Too Large`
297- Gordon CLI uploads image layers in 50MB chunks by default, and this setting caps the maximum chunk accepted per request
298- Keep this below Cloudflare's 100MB per-request limit when operating behind Cloudflare; the default (`95MB`) is fine
299- Increase it only if you expect larger direct registry uploads from other clients
300
301## Maximum Registry Blob Size
302
303The `max_blob_size` setting limits the cumulative size of one blob/layer upload across all chunks:
304
305```toml
306[server]
307max_blob_size = "1GB"  # Default
308```
309
310**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.
311
312**Behavior:**
313- Gordon tracks the current upload size and rejects appends that would exceed the limit.
314- Rejected uploads return an OCI-compatible `413` size error.
315- Failed uploads are cleaned up so temporary blob data does not accumulate indefinitely.
316
317## Registry IP Allowlist
318
319The `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).
320
321```toml
322[server]
323registry_allowed_ips = [
324  "100.64.0.0/10",   # Tailscale CGNAT range
325  "203.0.113.50",    # single IP (treated as /32)
326]
327```
328
329**Behavior:**
330- Single IPs are automatically converted to `/32` (IPv4) or `/128` (IPv6)
331- Denied requests receive `403 Forbidden`
332- Localhost (`127.0.0.0/8`, `::1`) is always allowed so Gordon can pull from its own registry
333- Respects `trusted_proxies` for accurate client IP extraction behind reverse proxies
334- Applied before rate limiting and authentication
335- Changes require a Gordon server restart; not picked up by config hot-reload
336
337**Use cases:**
338- Restrict registry to Tailscale network: `["100.64.0.0/10"]`
339- Restrict to private subnets: `["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]`
340- Allow a specific CI server: `["100.64.0.0/10", "203.0.113.50"]`
341
342Via environment variable:
343
344```bash
345GORDON_SERVER_REGISTRY_ALLOWED_IPS=100.64.0.0/10
346```
347
348## Proxy Origin IP Allowlist
349
350The `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.
351
352```toml
353[server]
354# Only accept proxy traffic from Cloudflare edge IPs
355proxy_allowed_ips = [
356  "173.245.48.0/20", "103.21.244.0/22", "103.22.200.0/22",
357  "103.31.4.0/22", "141.101.64.0/18", "108.162.192.0/18",
358  "190.93.240.0/20", "188.114.96.0/20", "197.234.240.0/22",
359  "198.41.128.0/17", "162.158.0.0/15", "104.16.0.0/13",
360  "104.24.0.0/14", "172.64.0.0/13", "131.0.72.0/22",
361]
362```
363
364**Behavior:**
365- Checks the direct connection IP (`RemoteAddr`), not `X-Forwarded-For`
366- Localhost is always allowed
367- Denied requests receive `403 Forbidden`
368- An empty list allows all traffic (default)
369
370**Important:** Cloudflare publishes their IP ranges at [cloudflare.com/ips](https://www.cloudflare.com/ips/). Keep your allowlist updated when Cloudflare adds new ranges.
371
372## Registry Listen Address
373
374The `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.
375
376```toml
377[server]
378registry_listen_address = "127.0.0.1"  # Loopback only
379```
380
381## HSTS
382
383HSTS headers are sent automatically on the HTTPS listener (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.
384
385## Examples
386
387### Development Configuration
388
389```toml
390[server]
391port = 8080
392registry_port = 5000
393gordon_domain = "gordon.local"
394data_dir = "./dev-data"
395```
396
397### Production Configuration
398
399```toml
400[server]
401port = 8080
402registry_port = 5000
403gordon_domain = "gordon.company.com"
404data_dir = "/var/lib/gordon"
405```
406
407### Rootless Container Setup
408
409```toml
410[server]
411port = 8080      # High port for rootless
412registry_port = 5000
413gordon_domain = "gordon.mydomain.com"
414```
415
416With firewall port forwarding:
417```bash
418sudo firewall-cmd --permanent --add-forward-port=port=80:proto=tcp:toport=8080
419sudo firewall-cmd --reload
420```
421
422## Related
423
424- [Configuration Overview](./index.md)
425- [Installation Guide](../installation.md)
426- [Routes Configuration](./routes.md)