server.md Raw History Folder

Server Configuration

Core server settings for Gordon.

Configuration

[server]
port = 8080                              # HTTP proxy port
registry_port = 5000                     # Container registry port
tls_enabled = false                      # Enable native TLS listener
tls_port = 443                           # HTTPS listener port
tls_cert_file = ""                       # PEM certificate file (required when TLS enabled)
tls_key_file = ""                        # PEM key file (required when TLS enabled)
gordon_domain = "gordon.mydomain.com"    # Gordon domain (required)
# data_dir = "~/.gordon"                 # Data storage directory (default)

Options

Option	Type	Default	Description
`port`	int	`80`	HTTP proxy port for routing traffic to containers
`registry_port`	int	`5000`	Docker registry port for image push/pull
`tls_enabled`	bool	`false`	Enable native HTTPS listener for proxy traffic
`tls_port`	int	`443`	HTTPS listener port when `tls_enabled` is true
`tls_cert_file`	string	`""`	Path to PEM certificate file
`tls_key_file`	string	`""`	Path to PEM private key file
`gordon_domain`	string	required	Domain for Gordon (registry + admin API)
`registry_domain`	string	-	Deprecated alias for `gordon_domain`
`data_dir`	string	`~/.gordon`	Directory for registry data, logs, and env files
`max_proxy_body_size`	string	`"512MB"`	Maximum request body size for proxied requests
`max_blob_chunk_size`	string	`"95MB"`	Maximum request body size for a single registry blob upload chunk
`registry_allowed_ips`	[]string	`[]`	IPs or CIDR ranges allowed to access the registry (empty = allow all)
`proxy_allowed_ips`	[]string	`[]`	IPs or CIDR ranges allowed to reach the proxy (empty = allow all)
`registry_listen_address`	string	`""`	Bind address for registry (empty = all interfaces)
`force_hsts`	bool	`false`	Always send HSTS header (for TLS-terminating proxy setups)

Port Configuration

Proxy Port

The port setting controls where Gordon listens for HTTP traffic:

[server]
port = 8080  # Use 8080 for rootless containers with port forwarding

For rootless containers, you'll typically use a high port and configure firewall port forwarding:

# Forward port 80 to 8080
sudo firewall-cmd --permanent --add-forward-port=port=80:proto=tcp:toport=8080

Native TLS Listener

Enable native HTTPS directly in Gordon:

[server]
tls_enabled = true
tls_port = 443
tls_cert_file = "/etc/gordon/certs/fullchain.pem"
tls_key_file = "/etc/gordon/certs/privkey.pem"

With TLS enabled:

Gordon terminates HTTPS on tls_port
Host-based routing still works (apps, /v2/*, /auth/*, /admin/*)
port remains available for plain HTTP unless you restrict it externally
If tls_cert_file/tls_key_file are empty, Gordon auto-generates a self-signed pair in {data_dir}/tls/

For rootless user services, do not bind directly to 443. Use an unprivileged TLS port (for example 8443) and forward 443 to it at the firewall or edge proxy.

[server]
tls_enabled = true
tls_port = 8443

With firewalld and Tailscale:

# Verify tailscale0 is in trusted zone
sudo firewall-cmd --get-zone-of-interface=tailscale0

# If needed, place tailscale0 in trusted
sudo firewall-cmd --permanent --zone=trusted --add-interface=tailscale0
sudo firewall-cmd --reload

# Forward 443 -> 8443 permanently (IPv4 + IPv6)
sudo firewall-cmd --permanent --zone=trusted --add-rich-rule='rule family=ipv4 forward-port port=443 protocol=tcp to-port=8443'
sudo firewall-cmd --permanent --zone=trusted --add-rich-rule='rule family=ipv6 forward-port port=443 protocol=tcp to-port=8443'
sudo firewall-cmd --reload

Registry Port

The registry_port setting controls where Gordon accepts image pushes:

[server]
registry_port = 5000

Docker/Podman clients push to this port:

docker push registry.mydomain.com:5000/myapp:latest

If the registry is served over plain HTTP (no TLS), clients must be configured to allow insecure access. See Troubleshooting: insecure registry for Docker and Podman instructions.

Gordon Domain

The gordon_domain is required and must match your DNS configuration:

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

This domain is used for:

Docker login and image push/pull operations
Admin API access (/admin/* endpoints)
CLI remote targeting (gordon routes --remote https://gordon.mydomain.com)
Authentication endpoints (/auth/*)

When requests arrive on the proxy port with this domain as the Host header, Gordon routes them to the backend services (registry and admin API).

Security note:

Direct access to /admin/* on registry_port is blocked for non-loopback clients.
Admin API traffic should go through the main proxy listener (server.port/server.tls_port).

Note: registry_domain is supported as a deprecated alias for backwards compatibility.

Data Directory

The data_dir setting controls where Gordon stores data:

[server]
data_dir = "~/.gordon"  # Default for user installations

Directory Structure

~/.gordon/
├── registry/           # Container images and manifests
│   ├── blobs/
│   └── manifests/
├── env/                # Environment files per domain
│   ├── app_mydomain_com.env
│   └── api_mydomain_com.env
├── logs/               # Application and container logs
│   ├── gordon.log
│   ├── proxy.log
│   └── containers/
└── secrets/            # Secrets (unsafe backend only)

Permissions

Gordon creates directories with secure permissions:

Directories: 0700 (owner only)
Files: 0600 (owner only)

Maximum Proxy Body Size

The max_proxy_body_size setting limits the size of request bodies that Gordon will forward to backend containers:

[server]
max_proxy_body_size = "512MB"  # Default

Purpose: Prevents resource exhaustion attacks from extremely large uploads through the proxy.

Supported units: B, KB, MB, GB, TB (case-insensitive, decimal/1024-based)

Examples:

max_proxy_body_size = "100MB"   # Stricter limit
max_proxy_body_size = "1GB"     # Allow larger uploads
max_proxy_body_size = "0"       # No limit (not recommended)

Behavior:

When a request exceeds the limit, Gordon returns 413 Request Entity Too Large
The limit is applied before the request reaches the backend container
Uploads in progress are terminated when the limit is exceeded

Use cases:

File upload services: increase to 1GB or higher
CI/CD artifact uploads: adjust based on your largest artifacts
Tight security: reduce to 100MB or lower
Default (512MB): suitable for most applications

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.

Maximum Registry Blob Chunk Size

The max_blob_chunk_size setting limits the size of a single blob upload request to the registry (PATCH/PUT under /v2/*/blobs/uploads/*):

[server]
max_blob_chunk_size = "95MB"  # Default

Purpose: Prevents excessive memory usage during blob uploads while allowing large real-world image layers.

Supported units: B, KB, MB, GB, TB (case-insensitive, decimal/1024-based)

Examples:

max_blob_chunk_size = "256MB"  # Stricter limit
max_blob_chunk_size = "1GB"    # Allow larger layers

Behavior:

When a blob chunk exceeds the limit, Gordon returns 413 Request Entity Too Large
Gordon CLI uploads image layers in 50MB chunks by default, and this setting caps the maximum chunk accepted per request
Keep this below Cloudflare's 100MB per-request limit when operating behind Cloudflare; the default (95MB) is fine
Increase it only if you expect larger direct registry uploads from other clients

Registry IP Allowlist

The 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).

[server]
registry_allowed_ips = [
  "100.64.0.0/10",   # Tailscale CGNAT range
  "203.0.113.50",    # single IP (treated as /32)
]

Behavior:

Single IPs are automatically converted to /32 (IPv4) or /128 (IPv6)
Denied requests receive 403 Forbidden
Localhost (127.0.0.0/8, ::1) is always allowed so Gordon can pull from its own registry
Respects trusted_proxies for accurate client IP extraction behind reverse proxies
Applied before rate limiting and authentication
Changes require a Gordon server restart; not picked up by config hot-reload

Use cases:

Restrict registry to Tailscale network: ["100.64.0.0/10"]
Restrict to private subnets: ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]
Allow a specific CI server: ["100.64.0.0/10", "203.0.113.50"]

Via environment variable:

GORDON_SERVER_REGISTRY_ALLOWED_IPS=100.64.0.0/10

Proxy Origin IP Allowlist

The 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.

[server]
# Only accept proxy traffic from Cloudflare edge IPs
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",
]

Behavior:

Checks the direct connection IP (RemoteAddr), not X-Forwarded-For
Localhost is always allowed
Denied requests receive 403 Forbidden
An empty list allows all traffic (default)

Important: Cloudflare publishes their IP ranges at cloudflare.com/ips. Keep your allowlist updated when Cloudflare adds new ranges.

Registry Listen Address

The 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.

[server]
registry_listen_address = "127.0.0.1"  # Loopback only

Force HSTS

When Gordon runs behind a TLS-terminating proxy (e.g. Cloudflare), r.TLS is nil so the HSTS header is not sent by default. Enable force_hsts to always include the Strict-Transport-Security header.

[server]
force_hsts = true

Examples

Development Configuration

[server]
port = 8080
registry_port = 5000
gordon_domain = "gordon.local"
data_dir = "./dev-data"

Production Configuration

[server]
port = 8080
registry_port = 5000
gordon_domain = "gordon.company.com"
data_dir = "/var/lib/gordon"

Rootless Container Setup

[server]
port = 8080      # High port for rootless
registry_port = 5000
gordon_domain = "gordon.mydomain.com"

With firewall port forwarding:

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

source

1# Server Configuration
2
3Core server settings for Gordon.
4
5## Configuration
6
7```toml
8[server]
9port = 8080                              # HTTP proxy port
10registry_port = 5000                     # Container registry port
11tls_enabled = false                      # Enable native TLS listener
12tls_port = 443                           # HTTPS listener port
13tls_cert_file = ""                       # PEM certificate file (required when TLS enabled)
14tls_key_file = ""                        # PEM key file (required when TLS enabled)
15gordon_domain = "gordon.mydomain.com"    # Gordon domain (required)
16# data_dir = "~/.gordon"                 # Data storage directory (default)
17```
18
19## Options
20
21| Option | Type | Default | Description |
22|--------|------|---------|-------------|
23| `port` | int | `80` | HTTP proxy port for routing traffic to containers |
24| `registry_port` | int | `5000` | Docker registry port for image push/pull |
25| `tls_enabled` | bool | `false` | Enable native HTTPS listener for proxy traffic |
26| `tls_port` | int | `443` | HTTPS listener port when `tls_enabled` is true |
27| `tls_cert_file` | string | `""` | Path to PEM certificate file |
28| `tls_key_file` | string | `""` | Path to PEM private key file |
29| `gordon_domain` | string | **required** | Domain for Gordon (registry + admin API) |
30| `registry_domain` | string | - | Deprecated alias for `gordon_domain` |
31| `data_dir` | string | `~/.gordon` | Directory for registry data, logs, and env files |
32| `max_proxy_body_size` | string | `"512MB"` | Maximum request body size for proxied requests |
33| `max_blob_chunk_size` | string | `"95MB"` | Maximum request body size for a single registry blob upload chunk |
34| `registry_allowed_ips` | []string | `[]` | IPs or CIDR ranges allowed to access the registry (empty = allow all) |
35| `proxy_allowed_ips` | []string | `[]` | IPs or CIDR ranges allowed to reach the proxy (empty = allow all) |
36| `registry_listen_address` | string | `""` | Bind address for registry (empty = all interfaces) |
37| `force_hsts` | bool | `false` | Always send HSTS header (for TLS-terminating proxy setups) |
38
39## Port Configuration
40
41### Proxy Port
42
43The `port` setting controls where Gordon listens for HTTP traffic:
44
45```toml
46[server]
47port = 8080  # Use 8080 for rootless containers with port forwarding
48```
49
50For rootless containers, you'll typically use a high port and configure firewall port forwarding:
51
52```bash
53# Forward port 80 to 8080
54sudo firewall-cmd --permanent --add-forward-port=port=80:proto=tcp:toport=8080
55```
56
57### Native TLS Listener
58
59Enable native HTTPS directly in Gordon:
60
61```toml
62[server]
63tls_enabled = true
64tls_port = 443
65tls_cert_file = "/etc/gordon/certs/fullchain.pem"
66tls_key_file = "/etc/gordon/certs/privkey.pem"
67```
68
69With TLS enabled:
70- Gordon terminates HTTPS on `tls_port`
71- Host-based routing still works (apps, `/v2/*`, `/auth/*`, `/admin/*`)
72- `port` remains available for plain HTTP unless you restrict it externally
73- If `tls_cert_file`/`tls_key_file` are empty, Gordon auto-generates a self-signed pair in `{data_dir}/tls/`
74
75For rootless user services, do not bind directly to `443`. Use an unprivileged TLS port (for example `8443`) and forward `443` to it at the firewall or edge proxy.
76
77```toml
78[server]
79tls_enabled = true
80tls_port = 8443
81```
82
83With firewalld and Tailscale:
84
85```bash
86# Verify tailscale0 is in trusted zone
87sudo firewall-cmd --get-zone-of-interface=tailscale0
88
89# If needed, place tailscale0 in trusted
90sudo firewall-cmd --permanent --zone=trusted --add-interface=tailscale0
91sudo firewall-cmd --reload
92
93# Forward 443 -> 8443 permanently (IPv4 + IPv6)
94sudo firewall-cmd --permanent --zone=trusted --add-rich-rule='rule family=ipv4 forward-port port=443 protocol=tcp to-port=8443'
95sudo firewall-cmd --permanent --zone=trusted --add-rich-rule='rule family=ipv6 forward-port port=443 protocol=tcp to-port=8443'
96sudo firewall-cmd --reload
97```
98
99### Registry Port
100
101The `registry_port` setting controls where Gordon accepts image pushes:
102
103```toml
104[server]
105registry_port = 5000
106```
107
108Docker/Podman clients push to this port:
109
110```bash
111docker push registry.mydomain.com:5000/myapp:latest
112```
113
114If 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.
115
116## Gordon Domain
117
118The `gordon_domain` is required and must match your DNS configuration:
119
120```toml
121[server]
122gordon_domain = "gordon.mydomain.com"
123```
124
125This domain is used for:
126- Docker login and image push/pull operations
127- Admin API access (`/admin/*` endpoints)
128- CLI remote targeting (`gordon routes --remote https://gordon.mydomain.com`)
129- Authentication endpoints (`/auth/*`)
130
131When requests arrive on the proxy port with this domain as the Host header, Gordon routes them to the backend services (registry and admin API).
132
133Security note:
134- Direct access to `/admin/*` on `registry_port` is blocked for non-loopback clients.
135- Admin API traffic should go through the main proxy listener (`server.port`/`server.tls_port`).
136
137> **Note:** `registry_domain` is supported as a deprecated alias for backwards compatibility.
138
139## Data Directory
140
141The `data_dir` setting controls where Gordon stores data:
142
143```toml
144[server]
145data_dir = "~/.gordon"  # Default for user installations
146```
147
148### Directory Structure
149
150```
151~/.gordon/
152├── registry/           # Container images and manifests
153│   ├── blobs/
154│   └── manifests/
155├── env/                # Environment files per domain
156│   ├── app_mydomain_com.env
157│   └── api_mydomain_com.env
158├── logs/               # Application and container logs
159│   ├── gordon.log
160│   ├── proxy.log
161│   └── containers/
162└── secrets/            # Secrets (unsafe backend only)
163```
164
165### Permissions
166
167 Gordon creates directories with secure permissions:
168 - Directories: `0700` (owner only)
169 - Files: `0600` (owner only)
170
171 ## Maximum Proxy Body Size
172
173 The `max_proxy_body_size` setting limits the size of request bodies that Gordon will forward to backend containers:
174
175 ```toml
176 [server]
177 max_proxy_body_size = "512MB"  # Default
178 ```
179
180 **Purpose:** Prevents resource exhaustion attacks from extremely large uploads through the proxy.
181
182 **Supported units:** B, KB, MB, GB, TB (case-insensitive, decimal/1024-based)
183
184 **Examples:**
185 ```toml
186 max_proxy_body_size = "100MB"   # Stricter limit
187 max_proxy_body_size = "1GB"     # Allow larger uploads
188 max_proxy_body_size = "0"       # No limit (not recommended)
189 ```
190
191 **Behavior:**
192 - When a request exceeds the limit, Gordon returns `413 Request Entity Too Large`
193 - The limit is applied before the request reaches the backend container
194 - Uploads in progress are terminated when the limit is exceeded
195
196 **Use cases:**
197 - File upload services: increase to `1GB` or higher
198 - CI/CD artifact uploads: adjust based on your largest artifacts
199 - Tight security: reduce to `100MB` or lower
200 - Default (512MB): suitable for most applications
201
202 > **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.
203
204## Maximum Registry Blob Chunk Size
205
206The `max_blob_chunk_size` setting limits the size of a single blob upload request to the registry (`PATCH`/`PUT` under `/v2/*/blobs/uploads/*`):
207
208```toml
209[server]
210max_blob_chunk_size = "95MB"  # Default
211```
212
213**Purpose:** Prevents excessive memory usage during blob uploads while allowing large real-world image layers.
214
215**Supported units:** B, KB, MB, GB, TB (case-insensitive, decimal/1024-based)
216
217**Examples:**
218
219```toml
220max_blob_chunk_size = "256MB"  # Stricter limit
221max_blob_chunk_size = "1GB"    # Allow larger layers
222```
223
224**Behavior:**
225- When a blob chunk exceeds the limit, Gordon returns `413 Request Entity Too Large`
226- Gordon CLI uploads image layers in 50MB chunks by default, and this setting caps the maximum chunk accepted per request
227- Keep this below Cloudflare's 100MB per-request limit when operating behind Cloudflare; the default (`95MB`) is fine
228- Increase it only if you expect larger direct registry uploads from other clients
229
230## Registry IP Allowlist
231
232The `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).
233
234```toml
235[server]
236registry_allowed_ips = [
237  "100.64.0.0/10",   # Tailscale CGNAT range
238  "203.0.113.50",    # single IP (treated as /32)
239]
240```
241
242**Behavior:**
243- Single IPs are automatically converted to `/32` (IPv4) or `/128` (IPv6)
244- Denied requests receive `403 Forbidden`
245- Localhost (`127.0.0.0/8`, `::1`) is always allowed so Gordon can pull from its own registry
246- Respects `trusted_proxies` for accurate client IP extraction behind reverse proxies
247- Applied before rate limiting and authentication
248- Changes require a Gordon server restart; not picked up by config hot-reload
249
250**Use cases:**
251- Restrict registry to Tailscale network: `["100.64.0.0/10"]`
252- Restrict to private subnets: `["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]`
253- Allow a specific CI server: `["100.64.0.0/10", "203.0.113.50"]`
254
255Via environment variable:
256
257```bash
258GORDON_SERVER_REGISTRY_ALLOWED_IPS=100.64.0.0/10
259```
260
261## Proxy Origin IP Allowlist
262
263The `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.
264
265```toml
266[server]
267# Only accept proxy traffic from Cloudflare edge IPs
268proxy_allowed_ips = [
269  "173.245.48.0/20", "103.21.244.0/22", "103.22.200.0/22",
270  "103.31.4.0/22", "141.101.64.0/18", "108.162.192.0/18",
271  "190.93.240.0/20", "188.114.96.0/20", "197.234.240.0/22",
272  "198.41.128.0/17", "162.158.0.0/15", "104.16.0.0/13",
273  "104.24.0.0/14", "172.64.0.0/13", "131.0.72.0/22",
274]
275```
276
277**Behavior:**
278- Checks the direct connection IP (`RemoteAddr`), not `X-Forwarded-For`
279- Localhost is always allowed
280- Denied requests receive `403 Forbidden`
281- An empty list allows all traffic (default)
282
283**Important:** Cloudflare publishes their IP ranges at [cloudflare.com/ips](https://www.cloudflare.com/ips/). Keep your allowlist updated when Cloudflare adds new ranges.
284
285## Registry Listen Address
286
287The `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.
288
289```toml
290[server]
291registry_listen_address = "127.0.0.1"  # Loopback only
292```
293
294## Force HSTS
295
296When Gordon runs behind a TLS-terminating proxy (e.g. Cloudflare), `r.TLS` is nil so the HSTS header is not sent by default. Enable `force_hsts` to always include the `Strict-Transport-Security` header.
297
298```toml
299[server]
300force_hsts = true
301```
302
303## Examples
304
305### Development Configuration
306
307```toml
308[server]
309port = 8080
310registry_port = 5000
311gordon_domain = "gordon.local"
312data_dir = "./dev-data"
313```
314
315### Production Configuration
316
317```toml
318[server]
319port = 8080
320registry_port = 5000
321gordon_domain = "gordon.company.com"
322data_dir = "/var/lib/gordon"
323```
324
325### Rootless Container Setup
326
327```toml
328[server]
329port = 8080      # High port for rootless
330registry_port = 5000
331gordon_domain = "gordon.mydomain.com"
332```
333
334With firewall port forwarding:
335```bash
336sudo firewall-cmd --permanent --add-forward-port=port=80:proto=tcp:toport=8080
337sudo firewall-cmd --reload
338```
339
340## Related
341
342- [Configuration Overview](./index.md)
343- [Installation Guide](../installation.md)
344- [Routes Configuration](./routes.md)

server.md RawHistoryFolder

Server Configuration

Configuration

Options

Port Configuration

Proxy Port

Native TLS Listener

Registry Port

Gordon Domain

Data Directory

Directory Structure

Permissions

Maximum Proxy Body Size

Maximum Registry Blob Chunk Size

Registry IP Allowlist

Proxy Origin IP Allowlist

Registry Listen Address

Force HSTS

Examples

Development Configuration

Production Configuration

Rootless Container Setup

Related

server.md Raw History Folder