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
11gordon_domain = "gordon.mydomain.com"    # Gordon domain (required)
12# data_dir = "~/.gordon"                 # Data storage directory (default)
13```
14
15## Options
16
17| Option | Type | Default | Description |
18|--------|------|---------|-------------|
19| `port` | int | `80` | HTTP proxy port for routing traffic to containers |
20| `registry_port` | int | `5000` | Docker registry port for image push/pull |
21| `gordon_domain` | string | **required** | Domain for Gordon (registry + admin API) |
22| `registry_domain` | string | - | Deprecated alias for `gordon_domain` |
23| `data_dir` | string | `~/.gordon` | Directory for registry data, logs, and env files |
24| `max_proxy_body_size` | string | `"512MB"` | Maximum request body size for proxied requests |
25
26## Port Configuration
27
28### Proxy Port
29
30The `port` setting controls where Gordon listens for HTTP traffic:
31
32```toml
33[server]
34port = 8080  # Use 8080 for rootless containers with port forwarding
35```
36
37For rootless containers, you'll typically use a high port and configure firewall port forwarding:
38
39```bash
40# Forward port 80 to 8080
41sudo firewall-cmd --permanent --add-forward-port=port=80:proto=tcp:toport=8080
42```
43
44### Registry Port
45
46The `registry_port` setting controls where Gordon accepts image pushes:
47
48```toml
49[server]
50registry_port = 5000
51```
52
53Docker/Podman clients push to this port:
54
55```bash
56docker push registry.mydomain.com:5000/myapp:latest
57```
58
59## Gordon Domain
60
61The `gordon_domain` is required and must match your DNS configuration:
62
63```toml
64[server]
65gordon_domain = "gordon.mydomain.com"
66```
67
68This domain is used for:
69- Docker login and image push/pull operations
70- Admin API access (`/admin/*` endpoints)
71- CLI remote targeting (`gordon routes --remote https://gordon.mydomain.com`)
72- Authentication endpoints (`/auth/*`)
73
74When requests arrive on the proxy port with this domain as the Host header, Gordon routes them to the backend services (registry and admin API).
75
76> **Note:** `registry_domain` is supported as a deprecated alias for backwards compatibility.
77
78## Data Directory
79
80The `data_dir` setting controls where Gordon stores data:
81
82```toml
83[server]
84data_dir = "~/.gordon"  # Default for user installations
85```
86
87### Directory Structure
88
89```
90~/.gordon/
91├── registry/           # Container images and manifests
92│   ├── blobs/
93│   └── manifests/
94├── env/                # Environment files per domain
95│   ├── app_mydomain_com.env
96│   └── api_mydomain_com.env
97├── logs/               # Application and container logs
98│   ├── gordon.log
99│   ├── proxy.log
100│   └── containers/
101└── secrets/            # Secrets (unsafe backend only)
102```
103
104### Permissions
105
106 Gordon creates directories with secure permissions:
107 - Directories: `0700` (owner only)
108 - Files: `0600` (owner only)
109
110 ## Maximum Proxy Body Size
111
112 The `max_proxy_body_size` setting limits the size of request bodies that Gordon will forward to backend containers:
113
114 ```toml
115 [server]
116 max_proxy_body_size = "512MB"  # Default
117 ```
118
119 **Purpose:** Prevents resource exhaustion attacks from extremely large uploads through the proxy.
120
121 **Supported units:** B, KB, MB, GB, TB (case-insensitive, decimal/1024-based)
122
123 **Examples:**
124 ```toml
125 max_proxy_body_size = "100MB"   # Stricter limit
126 max_proxy_body_size = "1GB"     # Allow larger uploads
127 max_proxy_body_size = "0"       # No limit (not recommended)
128 ```
129
130 **Behavior:**
131 - When a request exceeds the limit, Gordon returns `413 Request Entity Too Large`
132 - The limit is applied before the request reaches the backend container
133 - Uploads in progress are terminated when the limit is exceeded
134
135 **Use cases:**
136 - File upload services: increase to `1GB` or higher
137 - CI/CD artifact uploads: adjust based on your largest artifacts
138 - Tight security: reduce to `100MB` or lower
139 - Default (512MB): suitable for most applications
140
141 > **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.
142
143 ## Examples
144
145### Development Configuration
146
147```toml
148[server]
149port = 8080
150registry_port = 5000
151gordon_domain = "gordon.local"
152data_dir = "./dev-data"
153```
154
155### Production Configuration
156
157```toml
158[server]
159port = 8080
160registry_port = 5000
161gordon_domain = "gordon.company.com"
162data_dir = "/var/lib/gordon"
163```
164
165### Rootless Container Setup
166
167```toml
168[server]
169port = 8080      # High port for rootless
170registry_port = 5000
171gordon_domain = "gordon.mydomain.com"
172```
173
174With firewall port forwarding:
175```bash
176sudo firewall-cmd --permanent --add-forward-port=port=80:proto=tcp:toport=8080
177sudo firewall-cmd --reload
178```
179
180## Related
181
182- [Configuration Overview](./index.md)
183- [Installation Guide](../installation.md)
184- [Routes Configuration](./routes.md)