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
36## Port Configuration
37
38### Proxy Port
39
40The `port` setting controls where Gordon listens for HTTP traffic:
41
42```toml
43[server]
44port = 8080  # Use 8080 for rootless containers with port forwarding
45```
46
47For rootless containers, you'll typically use a high port and configure firewall port forwarding:
48
49```bash
50# Forward port 80 to 8080
51sudo firewall-cmd --permanent --add-forward-port=port=80:proto=tcp:toport=8080
52```
53
54### Native TLS Listener
55
56Enable native HTTPS directly in Gordon:
57
58```toml
59[server]
60tls_enabled = true
61tls_port = 443
62tls_cert_file = "/etc/gordon/certs/fullchain.pem"
63tls_key_file = "/etc/gordon/certs/privkey.pem"
64```
65
66With TLS enabled:
67- Gordon terminates HTTPS on `tls_port`
68- Host-based routing still works (apps, `/v2/*`, `/auth/*`, `/admin/*`)
69- `port` remains available for plain HTTP unless you restrict it externally
70- If `tls_cert_file`/`tls_key_file` are empty, Gordon auto-generates a self-signed pair in `{data_dir}/tls/`
71
72### Registry Port
73
74The `registry_port` setting controls where Gordon accepts image pushes:
75
76```toml
77[server]
78registry_port = 5000
79```
80
81Docker/Podman clients push to this port:
82
83```bash
84docker push registry.mydomain.com:5000/myapp:latest
85```
86
87If 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.
88
89## Gordon Domain
90
91The `gordon_domain` is required and must match your DNS configuration:
92
93```toml
94[server]
95gordon_domain = "gordon.mydomain.com"
96```
97
98This domain is used for:
99- Docker login and image push/pull operations
100- Admin API access (`/admin/*` endpoints)
101- CLI remote targeting (`gordon routes --remote https://gordon.mydomain.com`)
102- Authentication endpoints (`/auth/*`)
103
104When requests arrive on the proxy port with this domain as the Host header, Gordon routes them to the backend services (registry and admin API).
105
106> **Note:** `registry_domain` is supported as a deprecated alias for backwards compatibility.
107
108## Data Directory
109
110The `data_dir` setting controls where Gordon stores data:
111
112```toml
113[server]
114data_dir = "~/.gordon"  # Default for user installations
115```
116
117### Directory Structure
118
119```
120~/.gordon/
121├── registry/           # Container images and manifests
122│   ├── blobs/
123│   └── manifests/
124├── env/                # Environment files per domain
125│   ├── app_mydomain_com.env
126│   └── api_mydomain_com.env
127├── logs/               # Application and container logs
128│   ├── gordon.log
129│   ├── proxy.log
130│   └── containers/
131└── secrets/            # Secrets (unsafe backend only)
132```
133
134### Permissions
135
136 Gordon creates directories with secure permissions:
137 - Directories: `0700` (owner only)
138 - Files: `0600` (owner only)
139
140 ## Maximum Proxy Body Size
141
142 The `max_proxy_body_size` setting limits the size of request bodies that Gordon will forward to backend containers:
143
144 ```toml
145 [server]
146 max_proxy_body_size = "512MB"  # Default
147 ```
148
149 **Purpose:** Prevents resource exhaustion attacks from extremely large uploads through the proxy.
150
151 **Supported units:** B, KB, MB, GB, TB (case-insensitive, decimal/1024-based)
152
153 **Examples:**
154 ```toml
155 max_proxy_body_size = "100MB"   # Stricter limit
156 max_proxy_body_size = "1GB"     # Allow larger uploads
157 max_proxy_body_size = "0"       # No limit (not recommended)
158 ```
159
160 **Behavior:**
161 - When a request exceeds the limit, Gordon returns `413 Request Entity Too Large`
162 - The limit is applied before the request reaches the backend container
163 - Uploads in progress are terminated when the limit is exceeded
164
165 **Use cases:**
166 - File upload services: increase to `1GB` or higher
167 - CI/CD artifact uploads: adjust based on your largest artifacts
168 - Tight security: reduce to `100MB` or lower
169 - Default (512MB): suitable for most applications
170
171 > **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.
172
173## Maximum Registry Blob Chunk Size
174
175The `max_blob_chunk_size` setting limits the size of a single blob upload request to the registry (`PATCH`/`PUT` under `/v2/*/blobs/uploads/*`):
176
177```toml
178[server]
179max_blob_chunk_size = "95MB"  # Default
180```
181
182**Purpose:** Prevents excessive memory usage during blob uploads while allowing large real-world image layers.
183
184**Supported units:** B, KB, MB, GB, TB (case-insensitive, decimal/1024-based)
185
186**Examples:**
187
188```toml
189max_blob_chunk_size = "256MB"  # Stricter limit
190max_blob_chunk_size = "1GB"    # Allow larger layers
191```
192
193**Behavior:**
194- When a blob chunk exceeds the limit, Gordon returns `413 Request Entity Too Large`
195- Docker/Podman may send a full layer in one request, so set this high enough for your base images
196- Default (`95MB`) is compatible with Cloudflare and most CDN proxies; increase if pushing very large layers directly
197
198## Registry IP Allowlist
199
200The `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).
201
202```toml
203[server]
204registry_allowed_ips = [
205  "100.64.0.0/10",   # Tailscale CGNAT range
206  "203.0.113.50",    # single IP (treated as /32)
207]
208```
209
210**Behavior:**
211- Single IPs are automatically converted to `/32` (IPv4) or `/128` (IPv6)
212- Denied requests receive `403 Forbidden`
213- Localhost (`127.0.0.0/8`, `::1`) is always allowed so Gordon can pull from its own registry
214- Respects `trusted_proxies` for accurate client IP extraction behind reverse proxies
215- Applied before rate limiting and authentication
216- Changes require a Gordon server restart; not picked up by config hot-reload
217
218**Use cases:**
219- Restrict registry to Tailscale network: `["100.64.0.0/10"]`
220- Restrict to private subnets: `["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]`
221- Allow a specific CI server: `["100.64.0.0/10", "203.0.113.50"]`
222
223Via environment variable:
224
225```bash
226GORDON_SERVER_REGISTRY_ALLOWED_IPS=100.64.0.0/10
227```
228
229## Examples
230
231### Development Configuration
232
233```toml
234[server]
235port = 8080
236registry_port = 5000
237gordon_domain = "gordon.local"
238data_dir = "./dev-data"
239```
240
241### Production Configuration
242
243```toml
244[server]
245port = 8080
246registry_port = 5000
247gordon_domain = "gordon.company.com"
248data_dir = "/var/lib/gordon"
249```
250
251### Rootless Container Setup
252
253```toml
254[server]
255port = 8080      # High port for rootless
256registry_port = 5000
257gordon_domain = "gordon.mydomain.com"
258```
259
260With firewall port forwarding:
261```bash
262sudo firewall-cmd --permanent --add-forward-port=port=80:proto=tcp:toport=8080
263sudo firewall-cmd --reload
264```
265
266## Related
267
268- [Configuration Overview](./index.md)
269- [Installation Guide](../installation.md)
270- [Routes Configuration](./routes.md)