server.md Raw History Folder

Server Configuration

Core server settings for Gordon.

Configuration

[server]
port = 8088                              # HTTP proxy port
registry_port = 5000                     # Container registry port
tls_port = 8443                          # HTTPS listener port (0 = disabled)
# tls_cert_file = ""                       # Optional: PEM certificate for static TLS
# tls_key_file = ""                        # Optional: PEM key for static TLS
# force_https_redirect = false             # Redirect all HTTP traffic to HTTPS
gordon_domain = "gordon.mydomain.com"    # Gordon domain (required)
# data_dir = "~/.gordon"                 # Data storage directory (default)
max_blob_chunk_size = "95MB"             # Max registry blob upload chunk
max_blob_size = "1GB"                    # Max cumulative registry blob/layer upload

Options

Option	Type	Default	Description
`port`	int	`8088`	HTTP proxy port for routing traffic to containers
`registry_port`	int	`5000`	Docker registry port for image push/pull
`tls_port`	int	`8443`	HTTPS listener port with internal CA. Set to `0` to disable TLS entirely
`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
`tls_key_file`	string	`""`	Path to PEM private key file. Must be set together with `tls_cert_file`
`force_https_redirect`	bool	`false`	Redirect all HTTP requests to the HTTPS port. For direct-access setups without a TLS-terminating proxy
`gordon_domain`	string	required	Domain for Gordon (registry + admin API)
`registry_domain`	string	-	Deprecated migration key. Set `gordon_domain` instead.
`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
`max_blob_size`	string	`"1GB"`	Maximum cumulative size for one registry blob/layer upload
`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)

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

Internal CA and TLS

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

[server]
tls_port = 8443   # Default. Set to 0 to disable TLS entirely.

With TLS enabled:

Gordon runs an internal CA (root + intermediate) stored in {data_dir}/pki/
Leaf certificates are issued on-demand per domain (SNI-based) and cached in memory
The intermediate CA auto-renews before expiry
An onboarding page at https://<gordon-host>:<tls_port>/ca lets clients download the root CA certificate
The root CA is stable across restarts (generated once, persisted to disk)

Custom certificates

To use your own certificate (e.g. from Tailscale, Let's Encrypt, or a corporate CA) alongside the internal CA:

[server]
tls_cert_file = "/etc/gordon/tls/cert.pem"
tls_key_file = "/etc/gordon/tls/key.pem"

The static certificate is served for SNI-matching domains (including wildcards). All other domains get on-demand certs from the internal CA.

Direct HTTP Onboarding

When tls_port is non-zero, direct HTTP clients (those not arriving through a trusted proxy) are restricted to CA onboarding paths only:

/, /ca, /ca.crt, /ca.mobileconfig — serve the onboarding page and CA certificate downloads
/.well-known/acme-challenge/* — returns 404 Not Found (reserved for future ACME support)
All other paths return 403 Forbidden

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

The onboarding page is also available on HTTPS at /ca.

HTTP to HTTPS redirect

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

[server]
force_https_redirect = true

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

Disabling TLS

For setups where TLS is handled entirely by an external proxy (Cloudflare, nginx, etc.):

[server]
tls_port = 0   # No HTTPS listener, no internal CA generated

Firewall port forwarding

For rootless user services, forward 443 to the high port at the firewall:

# Forward 443 -> 8443
sudo firewall-cmd --permanent --add-forward-port=port=443:proto=tcp:toport=8443
sudo firewall-cmd --reload

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/*)

Warning: If you are upgrading an older config, copy server.registry_domain to server.gordon_domain before restarting.

Without this migration, a Host/remote-target mismatch can break routing or remote CLI token exchange.

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 a deprecated migration key; use gordon_domain for new and upgraded configs.

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

Maximum Registry Blob Size

The max_blob_size setting limits the cumulative size of one blob/layer upload across all chunks:

[server]
max_blob_size = "1GB"  # Default

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.

Behavior:

Gordon tracks the current upload size and rejects appends that would exceed the limit.
Rejected uploads return an OCI-compatible 413 size error.
Failed uploads are cleaned up so temporary blob data does not accumulate indefinitely.

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

HSTS

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

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 = 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#### Direct HTTP Onboarding
88
89When `tls_port` is non-zero, direct HTTP clients (those not arriving through a trusted proxy) are restricted to CA onboarding paths only:
90
91- `/`, `/ca`, `/ca.crt`, `/ca.mobileconfig` — serve the onboarding page and CA certificate downloads
92- `/.well-known/acme-challenge/*` — returns `404 Not Found` (reserved for future ACME support)
93- All other paths return `403 Forbidden`
94
95This 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.
96
97The onboarding page is also available on HTTPS at `/ca`.
98
99#### HTTP to HTTPS redirect
100
101When 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.
102
103```toml
104[server]
105force_https_redirect = true
106```
107
108When `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.
109
110#### Disabling TLS
111
112For setups where TLS is handled entirely by an external proxy (Cloudflare, nginx, etc.):
113
114```toml
115[server]
116tls_port = 0   # No HTTPS listener, no internal CA generated
117```
118
119#### Firewall port forwarding
120
121For rootless user services, forward 443 to the high port at the firewall:
122
123```bash
124# Forward 443 -> 8443
125sudo firewall-cmd --permanent --add-forward-port=port=443:proto=tcp:toport=8443
126sudo firewall-cmd --reload
127```
128
129With firewalld and Tailscale:
130
131```bash
132# Verify tailscale0 is in trusted zone
133sudo firewall-cmd --get-zone-of-interface=tailscale0
134
135# If needed, place tailscale0 in trusted
136sudo firewall-cmd --permanent --zone=trusted --add-interface=tailscale0
137sudo firewall-cmd --reload
138
139# Forward 443 -> 8443 permanently (IPv4 + IPv6)
140sudo firewall-cmd --permanent --zone=trusted --add-rich-rule='rule family=ipv4 forward-port port=443 protocol=tcp to-port=8443'
141sudo firewall-cmd --permanent --zone=trusted --add-rich-rule='rule family=ipv6 forward-port port=443 protocol=tcp to-port=8443'
142sudo firewall-cmd --reload
143```
144
145### Registry Port
146
147The `registry_port` setting controls where Gordon accepts image pushes:
148
149```toml
150[server]
151registry_port = 5000
152```
153
154Docker/Podman clients push to this port:
155
156```bash
157docker push registry.mydomain.com:5000/myapp:latest
158```
159
160If 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.
161
162## Gordon Domain
163
164The `gordon_domain` is required and must match your DNS configuration:
165
166```toml
167[server]
168gordon_domain = "gordon.mydomain.com"
169```
170
171This domain is used for:
172- Docker login and image push/pull operations
173- Admin API access (`/admin/*` endpoints)
174- CLI remote targeting (`gordon routes --remote https://gordon.mydomain.com`)
175- Authentication endpoints (`/auth/*`)
176
177> **Warning:** If you are upgrading an older config, copy `server.registry_domain` to `server.gordon_domain` before restarting.
178
179Without this migration, a Host/remote-target mismatch can break routing or remote CLI token exchange.
180
181When requests arrive on the proxy port with this domain as the Host header, Gordon routes them to the backend services (registry and admin API).
182
183Security note:
184- Direct access to `/admin/*` on `registry_port` is blocked for non-loopback clients.
185- Admin API traffic should go through the main proxy listener (`server.port`/`server.tls_port`).
186
187> **Note:** `registry_domain` is a deprecated migration key; use `gordon_domain` for new and upgraded configs.
188
189## Data Directory
190
191The `data_dir` setting controls where Gordon stores data:
192
193```toml
194[server]
195data_dir = "~/.gordon"  # Default for user installations
196```
197
198### Directory Structure
199
200```
201~/.gordon/
202├── registry/           # Container images and manifests
203│   ├── blobs/
204│   └── manifests/
205├── env/                # Environment files per domain
206│   ├── app_mydomain_com.env
207│   └── api_mydomain_com.env
208├── logs/               # Application and container logs
209│   ├── gordon.log
210│   ├── proxy.log
211│   └── containers/
212└── secrets/            # Secrets (unsafe backend only)
213```
214
215### Permissions
216
217 Gordon creates directories with secure permissions:
218 - Directories: `0700` (owner only)
219 - Files: `0600` (owner only)
220
221 ## Maximum Proxy Body Size
222
223 The `max_proxy_body_size` setting limits the size of request bodies that Gordon will forward to backend containers:
224
225 ```toml
226 [server]
227 max_proxy_body_size = "512MB"  # Default
228 ```
229
230 **Purpose:** Prevents resource exhaustion attacks from extremely large uploads through the proxy.
231
232 **Supported units:** B, KB, MB, GB, TB (case-insensitive, decimal/1024-based)
233
234 **Examples:**
235 ```toml
236 max_proxy_body_size = "100MB"   # Stricter limit
237 max_proxy_body_size = "1GB"     # Allow larger uploads
238 max_proxy_body_size = "0"       # No limit (not recommended)
239 ```
240
241 **Behavior:**
242 - When a request exceeds the limit, Gordon returns `413 Request Entity Too Large`
243 - The limit is applied before the request reaches the backend container
244 - Uploads in progress are terminated when the limit is exceeded
245
246 **Use cases:**
247 - File upload services: increase to `1GB` or higher
248 - CI/CD artifact uploads: adjust based on your largest artifacts
249 - Tight security: reduce to `100MB` or lower
250 - Default (512MB): suitable for most applications
251
252 > **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.
253
254## Maximum Registry Blob Chunk Size
255
256The `max_blob_chunk_size` setting limits the size of a single blob upload request to the registry (`PATCH`/`PUT` under `/v2/*/blobs/uploads/*`):
257
258```toml
259[server]
260max_blob_chunk_size = "95MB"  # Default
261```
262
263**Purpose:** Prevents excessive memory usage during blob uploads while allowing large real-world image layers.
264
265**Supported units:** B, KB, MB, GB, TB (case-insensitive, decimal/1024-based)
266
267**Examples:**
268
269```toml
270max_blob_chunk_size = "256MB"  # Stricter limit
271max_blob_chunk_size = "1GB"    # Allow larger layers
272```
273
274**Behavior:**
275- When a blob chunk exceeds the limit, Gordon returns `413 Request Entity Too Large`
276- Gordon CLI uploads image layers in 50MB chunks by default, and this setting caps the maximum chunk accepted per request
277- Keep this below Cloudflare's 100MB per-request limit when operating behind Cloudflare; the default (`95MB`) is fine
278- Increase it only if you expect larger direct registry uploads from other clients
279
280## Maximum Registry Blob Size
281
282The `max_blob_size` setting limits the cumulative size of one blob/layer upload across all chunks:
283
284```toml
285[server]
286max_blob_size = "1GB"  # Default
287```
288
289**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.
290
291**Behavior:**
292- Gordon tracks the current upload size and rejects appends that would exceed the limit.
293- Rejected uploads return an OCI-compatible `413` size error.
294- Failed uploads are cleaned up so temporary blob data does not accumulate indefinitely.
295
296## Registry IP Allowlist
297
298The `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).
299
300```toml
301[server]
302registry_allowed_ips = [
303  "100.64.0.0/10",   # Tailscale CGNAT range
304  "203.0.113.50",    # single IP (treated as /32)
305]
306```
307
308**Behavior:**
309- Single IPs are automatically converted to `/32` (IPv4) or `/128` (IPv6)
310- Denied requests receive `403 Forbidden`
311- Localhost (`127.0.0.0/8`, `::1`) is always allowed so Gordon can pull from its own registry
312- Respects `trusted_proxies` for accurate client IP extraction behind reverse proxies
313- Applied before rate limiting and authentication
314- Changes require a Gordon server restart; not picked up by config hot-reload
315
316**Use cases:**
317- Restrict registry to Tailscale network: `["100.64.0.0/10"]`
318- Restrict to private subnets: `["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]`
319- Allow a specific CI server: `["100.64.0.0/10", "203.0.113.50"]`
320
321Via environment variable:
322
323```bash
324GORDON_SERVER_REGISTRY_ALLOWED_IPS=100.64.0.0/10
325```
326
327## Proxy Origin IP Allowlist
328
329The `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.
330
331```toml
332[server]
333# Only accept proxy traffic from Cloudflare edge IPs
334proxy_allowed_ips = [
335  "173.245.48.0/20", "103.21.244.0/22", "103.22.200.0/22",
336  "103.31.4.0/22", "141.101.64.0/18", "108.162.192.0/18",
337  "190.93.240.0/20", "188.114.96.0/20", "197.234.240.0/22",
338  "198.41.128.0/17", "162.158.0.0/15", "104.16.0.0/13",
339  "104.24.0.0/14", "172.64.0.0/13", "131.0.72.0/22",
340]
341```
342
343**Behavior:**
344- Checks the direct connection IP (`RemoteAddr`), not `X-Forwarded-For`
345- Localhost is always allowed
346- Denied requests receive `403 Forbidden`
347- An empty list allows all traffic (default)
348
349**Important:** Cloudflare publishes their IP ranges at [cloudflare.com/ips](https://www.cloudflare.com/ips/). Keep your allowlist updated when Cloudflare adds new ranges.
350
351## Registry Listen Address
352
353The `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.
354
355```toml
356[server]
357registry_listen_address = "127.0.0.1"  # Loopback only
358```
359
360## HSTS
361
362HSTS 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.
363
364## Examples
365
366### Development Configuration
367
368```toml
369[server]
370port = 8080
371registry_port = 5000
372gordon_domain = "gordon.local"
373data_dir = "./dev-data"
374```
375
376### Production Configuration
377
378```toml
379[server]
380port = 8080
381registry_port = 5000
382gordon_domain = "gordon.company.com"
383data_dir = "/var/lib/gordon"
384```
385
386### Rootless Container Setup
387
388```toml
389[server]
390port = 8080      # High port for rootless
391registry_port = 5000
392gordon_domain = "gordon.mydomain.com"
393```
394
395With firewall port forwarding:
396```bash
397sudo firewall-cmd --permanent --add-forward-port=port=80:proto=tcp:toport=8080
398sudo firewall-cmd --reload
399```
400
401## Related
402
403- [Configuration Overview](./index.md)
404- [Installation Guide](../installation.md)
405- [Routes Configuration](./routes.md)

server.md RawHistoryFolder

Server Configuration

Configuration

Options

Port Configuration

Proxy Port

Internal CA and TLS

Custom certificates

Direct HTTP Onboarding

HTTP to HTTPS redirect

Disabling TLS

Firewall port forwarding

Registry Port

Gordon Domain

Data Directory

Directory Structure

Permissions

Maximum Proxy Body Size

Maximum Registry Blob Chunk Size

Maximum Registry Blob Size

Registry IP Allowlist

Proxy Origin IP Allowlist

Registry Listen Address

HSTS

Examples

Development Configuration

Production Configuration

Rootless Container Setup

Related

server.md Raw History Folder