1# Configuration Reference
2
3Complete configuration reference with all options and their default values.
4
5## Full Configuration Example
6
7```toml
8# =============================================================================
9# SERVER
10# =============================================================================
11[server]
12port = 80                                    # HTTP proxy port
13registry_port = 5000                         # Container registry port
14tls_enabled = false                          # Enable native HTTPS listener
15tls_port = 443                               # HTTPS proxy port when enabled
16tls_cert_file = ""                           # PEM cert path (auto-generated if empty and TLS enabled)
17tls_key_file = ""                            # PEM key path (auto-generated if empty and TLS enabled)
18gordon_domain = ""                           # Required: Gordon domain (registry + API)
19data_dir = "~/.gordon"                       # Data directory (varies by install type)
20max_blob_chunk_size = "512MB"                # Max size per registry blob upload chunk
21registry_allowed_ips = []                    # IPs or CIDR ranges allowed to access the registry (empty = allow all)
22
23# =============================================================================
24# AUTHENTICATION (required - Gordon won't start without credentials configured)
25# =============================================================================
26[auth]
27enabled = true                               # Enable registry authentication (default: true)
28secrets_backend = "unsafe"                   # "pass", "sops", or "unsafe"
29token_secret = ""                            # Path in secrets backend to JWT signing key (REQUIRED)
30token_expiry = "720h"                        # Token expiry duration (720h = 30 days)
31# Optional: enable password authentication (for interactive login)
32# username = ""                              # Username for password auth
33# password_hash = ""                         # Path in secrets backend to bcrypt hash
34
35# =============================================================================
36# API (applies to both Registry and Admin endpoints)
37# =============================================================================
38[api.rate_limit]
39enabled = true                               # Enable rate limiting (default: true)
40global_rps = 500                             # Max requests/second globally
41per_ip_rps = 50                              # Max requests/second per client IP
42burst = 100                                  # Burst size for rate limiters
43trusted_proxies = []                         # IPs/CIDRs trusted to set X-Forwarded-For
44
45# =============================================================================
46# LOGGING
47# =============================================================================
48[logging]
49level = "info"                               # "debug", "info", "warn", "error"
50format = "console"                           # "console" or "json"
51
52[logging.file]
53enabled = false                              # Enable file logging
54path = ""                                    # Log file path (default: {data_dir}/logs/gordon.log)
55max_size = 100                               # Max size in MB before rotation
56max_backups = 3                              # Number of old files to keep
57max_age = 28                                 # Days to keep old files
58
59[logging.container_logs]
60enabled = true                               # Enable container log collection
61dir = ""                                     # Log directory (default: {data_dir}/container-logs)
62max_size = 100                               # Max size in MB before rotation
63max_backups = 3                              # Number of old files to keep
64max_age = 28                                 # Days to keep old files
65
66# =============================================================================
67# ENVIRONMENT
68# =============================================================================
69[env]
70dir = ""                                     # Env files directory (default: {data_dir}/env)
71
72# =============================================================================
73# DEPLOYMENT
74# =============================================================================
75[deploy]
76pull_policy = "if-tag-changed"               # "always", "if-tag-changed", "never"
77readiness_mode = "auto"                      # "auto", "docker-health", "delay"
78health_timeout = "90s"                       # Max wait for health-based readiness
79readiness_delay = "5s"                       # Wait after running before considered ready
80drain_mode = "auto"                          # "auto", "inflight", "delay"
81drain_timeout = "30s"                        # Max wait for in-flight request drain
82drain_delay = "2s"                           # Wait after cache invalidation before old stop
83
84# =============================================================================
85# AUTO-ROUTE
86# =============================================================================
87[auto_route]
88enabled = false                              # Create routes from image labels automatically
89
90# =============================================================================
91# NETWORK ISOLATION
92# =============================================================================
93[network_isolation]
94enabled = false                              # Enable per-app Docker networks
95network_prefix = "gordon"                    # Prefix for created networks
96dns_suffix = ".internal"                     # DNS suffix for internal resolution
97
98# =============================================================================
99# VOLUMES
100# =============================================================================
101[volumes]
102auto_create = true                           # Auto-create volumes from Dockerfile VOLUME
103prefix = "gordon"                            # Volume name prefix
104preserve = true                              # Keep volumes when containers are removed
105
106# =============================================================================
107# ROUTES
108# =============================================================================
109[routes]
110# "domain.com" = "image:tag"
111# "http://insecure.domain.com" = "image:tag"   # HTTP-only (no HTTPS redirect)
112
113# =============================================================================
114# EXTERNAL ROUTES
115# =============================================================================
116[external_routes]
117# "domain.com" = "host:port"                 # Proxy to non-container services
118
119# =============================================================================
120# NETWORK GROUPS
121# =============================================================================
122[network_groups]
123# "group-name" = ["domain1.com", "domain2.com"]
124
125# =============================================================================
126# ATTACHMENTS
127# =============================================================================
128[attachments]
129# "domain-or-group" = ["image1:tag", "image2:tag"]
130
131# =============================================================================
132# BACKUPS
133# =============================================================================
134[backups]
135enabled = false                              # Enable backup service
136storage_dir = ""                            # Backup root (default: {data_dir}/backups)
137
138[backups.retention]
139hourly = 0                                   # Keep N hourly backups per DB
140daily = 0                                    # Keep N daily backups per DB
141weekly = 0                                   # Keep N weekly backups per DB
142monthly = 0                                  # Keep N monthly backups per DB
143
144# Note: retention values set to 0 keep no backups for that tier.
145# For practical defaults, consider setting daily = 7.
146```
147
148## Default Values Summary
149
150| Setting | Default | Description |
151|---------|---------|-------------|
152| `server.port` | `80` | HTTP proxy port |
153| `server.registry_port` | `5000` | Container registry port |
154| `server.tls_enabled` | `false` | Enable native HTTPS listener |
155| `server.tls_port` | `443` | HTTPS listener port |
156| `server.tls_cert_file` | `""` | TLS cert path (auto-generated when empty) |
157| `server.tls_key_file` | `""` | TLS key path (auto-generated when empty) |
158| `server.gordon_domain` | `""` | **Required** - Gordon domain |
159| `server.data_dir` | `~/.gordon` | Data directory |
160| `server.max_blob_chunk_size` | `"512MB"` | Max size per registry blob upload chunk |
161| `server.registry_allowed_ips` | `[]` | IPs or CIDR ranges allowed to access the registry (empty = allow all) |
162| `auth.enabled` | `true` | Enable authentication |
163| `auth.secrets_backend` | `"unsafe"` | Secrets storage |
164| `auth.token_expiry` | `"720h"` | 30 days |
165| `api.rate_limit.enabled` | `true` | Enable rate limiting |
166| `api.rate_limit.global_rps` | `500` | Global requests/second |
167| `api.rate_limit.per_ip_rps` | `50` | Per-IP requests/second |
168| `api.rate_limit.burst` | `100` | Burst size |
169| `api.rate_limit.trusted_proxies` | `[]` | IPs/CIDRs trusted for X-Forwarded-For |
170| `logging.level` | `"info"` | Log level |
171| `logging.format` | `"console"` | Log format |
172| `logging.file.enabled` | `false` | File logging disabled |
173| `logging.file.max_size` | `100` | 100 MB |
174| `logging.file.max_backups` | `3` | Keep 3 old files |
175| `logging.file.max_age` | `28` | 28 days |
176| `logging.container_logs.enabled` | `true` | Container logs enabled |
177| `logging.container_logs.max_size` | `100` | 100 MB |
178| `logging.container_logs.max_backups` | `3` | Keep 3 old files |
179| `logging.container_logs.max_age` | `28` | 28 days |
180| `deploy.pull_policy` | `"if-tag-changed"` | Pull on tag change |
181| `deploy.readiness_mode` | `"auto"` | Readiness strategy (`auto`, `docker-health`, `delay`) |
182| `deploy.health_timeout` | `"90s"` | Max wait for health-based readiness before deploy fails |
183| `deploy.readiness_delay` | `"5s"` | Delay before container is considered ready |
184| `deploy.drain_mode` | `"auto"` | Drain strategy (`auto`, `inflight`, `delay`) |
185| `deploy.drain_timeout` | `"30s"` | Max wait for in-flight request drain before old stop |
186| `deploy.drain_delay` | `"2s"` | Delay before stopping previous container after cache invalidation |
187| `auto_route.enabled` | `false` | Auto-route disabled |
188| `network_isolation.enabled` | `false` | Isolation disabled |
189| `network_isolation.network_prefix` | `"gordon"` | Network prefix |
190| `network_isolation.dns_suffix` | `".internal"` | DNS suffix |
191| `volumes.auto_create` | `true` | Auto-create volumes |
192| `volumes.prefix` | `"gordon"` | Volume prefix |
193| `volumes.preserve` | `true` | Keep volumes |
194| `backups.enabled` | `false` | Backup service disabled |
195| `backups.storage_dir` | `""` | Uses `{server.data_dir}/backups` when empty |
196| `backups.retention.hourly` | `0` | Keep no hourly backups by default |
197| `backups.retention.daily` | `0` | Keep no daily backups by default (recommend `7`) |
198| `backups.retention.weekly` | `0` | Keep no weekly backups by default |
199| `backups.retention.monthly` | `0` | Keep no monthly backups by default |
200
201Note: for all `backups.retention.*` keys, `0` means keep no backups for that retention tier.
202
203## Environment Variables
204
205All configuration options can be set via environment variables using the pattern:
206
207```
208GORDON_<SECTION>_<KEY>=value
209```
210
211Examples:
212```bash
213GORDON_SERVER_PORT=8080
214GORDON_SERVER_GORDON_DOMAIN=gordon.example.com
215GORDON_AUTH_ENABLED=true
216GORDON_LOGGING_LEVEL=debug
217GORDON_NETWORK_ISOLATION_ENABLED=true
218```
219
220Nested keys use underscores:
221```bash
222GORDON_LOGGING_FILE_ENABLED=true
223GORDON_LOGGING_FILE_MAX_SIZE=200
224GORDON_LOGGING_CONTAINER_LOGS_ENABLED=false
225```
226
227### Security Environment Variables
228
229These special environment variables take priority over config file values:
230
231| Variable | Description |
232|----------|-------------|
233| `GORDON_AUTH_TOKEN_SECRET` | JWT signing secret (avoids storing secret on disk) |
234
235Example:
236```bash
237export GORDON_AUTH_TOKEN_SECRET="your-secure-32-char-secret-here"
238gordon serve
239```
240
241## Pull Policy Options
242
243| Value | Behavior |
244|-------|----------|
245| `"always"` | Always pull image before deploying |
246| `"if-tag-changed"` | Pull only if image tag differs from running container |
247| `"never"` | Never pull, use local image only |
248
249## Secrets Backend Options
250
251| Value | Description |
252|-------|-------------|
253| `"pass"` | Unix password manager (recommended for production) |
254| `"sops"` | Mozilla SOPS encrypted files |
255| `"unsafe"` | Plain text files (development only) |
256
257## Log Level Options
258
259| Value | Description |
260|-------|-------------|
261| `"debug"` | Verbose debugging information |
262| `"info"` | General operational information |
263| `"warn"` | Warning conditions |
264| `"error"` | Error conditions only |
265
266## Related
267
268- [Configuration Overview](./index.md)
269- [Authentication](./auth.md)
270- [Network Isolation](./network-isolation.md)
271- [Volumes](./volumes.md)