index.md Raw History Folder

Configuration Overview

Gordon uses a single TOML configuration file located at ~/.config/gordon/gordon.toml.

Configuration File Location

Location	Purpose
`~/.config/gordon/gordon.toml`	Default configuration file
Custom path via `--config` flag	`gordon serve --config /path/to/config.toml`

Minimal Configuration

[server]
port = 8080
registry_port = 5000
gordon_domain = "gordon.mydomain.com"

[routes]
"app.mydomain.com" = "myapp:latest"

Full Configuration Reference

For a complete list of all configuration options with their default values, see the Configuration Reference.

Note: This example shows production-style paths. Default paths use ~/.gordon/ for user installations.

# Server settings
[server]
port = 8080                              # HTTP proxy port (default: 80)
registry_port = 5000                     # Registry port (default: 5000)
gordon_domain = "gordon.mydomain.com"    # Required: Gordon domain (registry + API)
# data_dir = "~/.gordon"                 # Default for user installations

# Authentication (includes secrets backend)
[auth]
enabled = true                           # Enable registry authentication (default: true)
secrets_backend = "pass"                 # "pass", "sops", or "unsafe"
token_secret = "gordon/auth/token_secret"  # Required: JWT signing secret
token_expiry = "30d"                     # Duration (1y, 30d, 2w) or 0 for never
# Optional: enable password authentication (for interactive login)
# username = "deploy"
# password_hash = "gordon/auth/password_hash"

# API rate limiting
[api.rate_limit]
enabled = true                           # Enable rate limiting (default: true)
global_rps = 500                         # Max requests/second globally
per_ip_rps = 50                          # Max requests/second per IP
burst = 100                              # Burst size
trusted_proxies = []                     # IPs/CIDRs trusted for X-Forwarded-For

# Deploy behavior
[deploy]
pull_policy = "if-tag-changed"           # always, if-not-present, if-tag-changed
readiness_mode = "auto"                  # auto, docker-health, delay
health_timeout = "90s"                   # Max wait for health-based readiness
readiness_delay = "5s"                   # Wait after running before ready
drain_mode = "auto"                      # auto, inflight, delay
drain_timeout = "30s"                    # Max wait for in-flight drain
drain_delay = "2s"                       # Wait after proxy invalidation before stopping the old container

# Logging
[logging]
level = "info"                           # trace, debug, info, warn, error
format = "console"                       # console or json

[logging.file]
enabled = true
path = "~/.gordon/logs/gordon.log"       # Default location
max_size = 100                           # MB before rotation
max_backups = 3                          # Old files to keep
max_age = 28                             # Days to keep

[logging.container_logs]
enabled = true
dir = "~/.gordon/logs/containers"        # Default location
max_size = 100
max_backups = 3
max_age = 28

# Environment variables
[env]
dir = "~/.gordon/env"                    # Default location

# Volume settings
[volumes]
auto_create = true                       # Auto-create from Dockerfile VOLUME
prefix = "gordon"                        # Volume name prefix
preserve = true                          # Keep volumes on container removal

# Network isolation
[network_isolation]
enabled = true                           # Per-app isolated networks
network_prefix = "gordon"                # Network name prefix
dns_suffix = ".internal"                 # DNS suffix for services

# Auto-route
[auto_route]
enabled = false                          # Auto-create routes from image names

# Routes (required)
[routes]
"app.mydomain.com" = "myapp:latest"
"api.mydomain.com" = "myapi:v2.1.0"

# Network groups
[network_groups]
"backend" = ["app.mydomain.com", "api.mydomain.com"]

# Attachments
[attachments]
"app.mydomain.com" = ["postgres:latest", "redis:latest"]
"backend" = ["rabbitmq:latest"]

# Backups
[backups]
enabled = true
storage_dir = "~/.gordon/backups"

[backups.retention]
hourly = 24
daily = 7
weekly = 4
monthly = 12

Configuration Sections

Section	Description	Documentation
`[server]`	Core server settings	Server
`[auth]`	Authentication and secrets backend	Auth
`[api.rate_limit]`	Rate limiting configuration	Rate Limiting
`[deploy]`	Deployment behavior	Deploy
`[logging]`	Logging configuration	Logging
`[env]`	Environment variable settings	Environment
`[volumes]`	Volume management	Volumes
`[network_isolation]`	Network isolation settings	Network Isolation
`[auto_route]`	Automatic route creation	Auto Route
`[routes]`	Domain to image mapping	Routes
`[external_routes]`	Non-containerized service proxying	External Routes
`[network_groups]`	Shared service networks	Network Groups
`[attachments]`	Service dependencies	Attachments
`[backups]`	Database backups	Backups

Default Values

Setting	Default
`server.port`	`80`
`server.registry_port`	`5000`
`server.data_dir`	`~/.gordon`
`auth.enabled`	`true`
`auth.secrets_backend`	`"unsafe"`
`auth.token_expiry`	`"30d"`
`api.rate_limit.enabled`	`true`
`api.rate_limit.global_rps`	`500`
`api.rate_limit.per_ip_rps`	`50`
`api.rate_limit.burst`	`100`
`api.rate_limit.trusted_proxies`	`[]`
`deploy.pull_policy`	`"if-tag-changed"`
`deploy.readiness_mode`	`"auto"`
`deploy.health_timeout`	`"90s"`
`deploy.readiness_delay`	`"5s"`
`deploy.drain_mode`	`"auto"`
`deploy.drain_timeout`	`"30s"`
`deploy.drain_delay`	`"2s"`
`logging.level`	`"info"`
`logging.format`	`"console"`
`logging.file.enabled`	`false`
`logging.file.max_size`	`100`
`logging.file.max_backups`	`3`
`logging.file.max_age`	`28`
`logging.container_logs.enabled`	`true`
`volumes.auto_create`	`true`
`volumes.prefix`	`"gordon"`
`volumes.preserve`	`true`
`network_isolation.enabled`	`false`
`auto_route.enabled`	`false`
`backups.enabled`	`false`

Hot Reload

Gordon watches the configuration file and reloads automatically when changes are detected. You can also trigger a manual reload:

gordon reload

The following settings require a restart to take effect:

server.port
server.registry_port
server.data_dir
auth settings
deploy.pull_policy
deploy.readiness_mode
deploy.health_timeout
deploy.readiness_delay
deploy.drain_mode
deploy.drain_timeout
deploy.drain_delay

Environment Variable Override

Configuration values can be overridden with environment variables:

GORDON_SERVER_PORT=8080 gordon serve
GORDON_LOGGING_LEVEL=debug gordon serve

Pattern: GORDON_SECTION_KEY (uppercase, underscores instead of dots)

source

1# Configuration Overview
2
3Gordon uses a single TOML configuration file located at `~/.config/gordon/gordon.toml`.
4
5## Configuration File Location
6
7| Location | Purpose |
8|----------|---------|
9| `~/.config/gordon/gordon.toml` | Default configuration file |
10| Custom path via `--config` flag | `gordon serve --config /path/to/config.toml` |
11
12## Minimal Configuration
13
14```toml
15[server]
16port = 8080
17registry_port = 5000
18gordon_domain = "gordon.mydomain.com"
19
20[routes]
21"app.mydomain.com" = "myapp:latest"
22```
23
24## Full Configuration Reference
25
26For a complete list of all configuration options with their default values, see the [Configuration Reference](./reference.md).
27
28> **Note:** This example shows production-style paths. Default paths use `~/.gordon/` for user installations.
29
30```toml
31# Server settings
32[server]
33port = 8080                              # HTTP proxy port (default: 80)
34registry_port = 5000                     # Registry port (default: 5000)
35gordon_domain = "gordon.mydomain.com"    # Required: Gordon domain (registry + API)
36# data_dir = "~/.gordon"                 # Default for user installations
37
38# Authentication (includes secrets backend)
39[auth]
40enabled = true                           # Enable registry authentication (default: true)
41secrets_backend = "pass"                 # "pass", "sops", or "unsafe"
42token_secret = "gordon/auth/token_secret"  # Required: JWT signing secret
43token_expiry = "30d"                     # Duration (1y, 30d, 2w) or 0 for never
44# Optional: enable password authentication (for interactive login)
45# username = "deploy"
46# password_hash = "gordon/auth/password_hash"
47
48# API rate limiting
49[api.rate_limit]
50enabled = true                           # Enable rate limiting (default: true)
51global_rps = 500                         # Max requests/second globally
52per_ip_rps = 50                          # Max requests/second per IP
53burst = 100                              # Burst size
54trusted_proxies = []                     # IPs/CIDRs trusted for X-Forwarded-For
55
56# Deploy behavior
57[deploy]
58pull_policy = "if-tag-changed"           # always, if-not-present, if-tag-changed
59readiness_mode = "auto"                  # auto, docker-health, delay
60health_timeout = "90s"                   # Max wait for health-based readiness
61readiness_delay = "5s"                   # Wait after running before ready
62drain_mode = "auto"                      # auto, inflight, delay
63drain_timeout = "30s"                    # Max wait for in-flight drain
64drain_delay = "2s"                       # Wait after proxy invalidation before stopping the old container
65
66# Logging
67[logging]
68level = "info"                           # trace, debug, info, warn, error
69format = "console"                       # console or json
70
71[logging.file]
72enabled = true
73path = "~/.gordon/logs/gordon.log"       # Default location
74max_size = 100                           # MB before rotation
75max_backups = 3                          # Old files to keep
76max_age = 28                             # Days to keep
77
78[logging.container_logs]
79enabled = true
80dir = "~/.gordon/logs/containers"        # Default location
81max_size = 100
82max_backups = 3
83max_age = 28
84
85# Environment variables
86[env]
87dir = "~/.gordon/env"                    # Default location
88
89# Volume settings
90[volumes]
91auto_create = true                       # Auto-create from Dockerfile VOLUME
92prefix = "gordon"                        # Volume name prefix
93preserve = true                          # Keep volumes on container removal
94
95# Network isolation
96[network_isolation]
97enabled = true                           # Per-app isolated networks
98network_prefix = "gordon"                # Network name prefix
99dns_suffix = ".internal"                 # DNS suffix for services
100
101# Auto-route
102[auto_route]
103enabled = false                          # Auto-create routes from image names
104
105# Routes (required)
106[routes]
107"app.mydomain.com" = "myapp:latest"
108"api.mydomain.com" = "myapi:v2.1.0"
109
110# Network groups
111[network_groups]
112"backend" = ["app.mydomain.com", "api.mydomain.com"]
113
114# Attachments
115[attachments]
116"app.mydomain.com" = ["postgres:latest", "redis:latest"]
117"backend" = ["rabbitmq:latest"]
118
119# Backups
120[backups]
121enabled = true
122storage_dir = "~/.gordon/backups"
123
124[backups.retention]
125hourly = 24
126daily = 7
127weekly = 4
128monthly = 12
129```
130
131## Configuration Sections
132
133| Section | Description | Documentation |
134|---------|-------------|---------------|
135| `[server]` | Core server settings | [Server](./server.md) |
136| `[auth]` | Authentication and secrets backend | [Auth](./auth.md) |
137| `[api.rate_limit]` | Rate limiting configuration | [Rate Limiting](./rate-limiting.md) |
138| `[deploy]` | Deployment behavior | [Deploy](./deploy.md) |
139| `[logging]` | Logging configuration | [Logging](./logging.md) |
140| `[env]` | Environment variable settings | [Environment](./env.md) |
141| `[volumes]` | Volume management | [Volumes](./volumes.md) |
142| `[network_isolation]` | Network isolation settings | [Network Isolation](./network-isolation.md) |
143| `[auto_route]` | Automatic route creation | [Auto Route](./auto-route.md) |
144| `[routes]` | Domain to image mapping | [Routes](./routes.md) |
145| `[external_routes]` | Non-containerized service proxying | [External Routes](./external-routes.md) |
146| `[network_groups]` | Shared service networks | [Network Groups](./network-groups.md) |
147| `[attachments]` | Service dependencies | [Attachments](./attachments.md) |
148| `[backups]` | Database backups | [Backups](./backups.md) |
149
150## Default Values
151
152| Setting | Default |
153|---------|---------|
154| `server.port` | `80` |
155| `server.registry_port` | `5000` |
156| `server.data_dir` | `~/.gordon` |
157| `auth.enabled` | `true` |
158| `auth.secrets_backend` | `"unsafe"` |
159| `auth.token_expiry` | `"30d"` |
160| `api.rate_limit.enabled` | `true` |
161| `api.rate_limit.global_rps` | `500` |
162| `api.rate_limit.per_ip_rps` | `50` |
163| `api.rate_limit.burst` | `100` |
164| `api.rate_limit.trusted_proxies` | `[]` |
165| `deploy.pull_policy` | `"if-tag-changed"` |
166| `deploy.readiness_mode` | `"auto"` |
167| `deploy.health_timeout` | `"90s"` |
168| `deploy.readiness_delay` | `"5s"` |
169| `deploy.drain_mode` | `"auto"` |
170| `deploy.drain_timeout` | `"30s"` |
171| `deploy.drain_delay` | `"2s"` |
172| `logging.level` | `"info"` |
173| `logging.format` | `"console"` |
174| `logging.file.enabled` | `false` |
175| `logging.file.max_size` | `100` |
176| `logging.file.max_backups` | `3` |
177| `logging.file.max_age` | `28` |
178| `logging.container_logs.enabled` | `true` |
179| `volumes.auto_create` | `true` |
180| `volumes.prefix` | `"gordon"` |
181| `volumes.preserve` | `true` |
182| `network_isolation.enabled` | `false` |
183| `auto_route.enabled` | `false` |
184| `backups.enabled` | `false` |
185
186## Hot Reload
187
188Gordon watches the configuration file and reloads automatically when changes are detected. You can also trigger a manual reload:
189
190```bash
191gordon reload
192```
193
194The following settings require a restart to take effect:
195
196- `server.port`
197- `server.registry_port`
198- `server.data_dir`
199- `auth` settings
200- `deploy.pull_policy`
201- `deploy.readiness_mode`
202- `deploy.health_timeout`
203- `deploy.readiness_delay`
204- `deploy.drain_mode`
205- `deploy.drain_timeout`
206- `deploy.drain_delay`
207
208## Environment Variable Override
209
210Configuration values can be overridden with environment variables:
211
212```bash
213GORDON_SERVER_PORT=8080 gordon serve
214GORDON_LOGGING_LEVEL=debug gordon serve
215```
216
217Pattern: `GORDON_SECTION_KEY` (uppercase, underscores instead of dots)
218
219## Related
220
221- [Server Configuration](./server.md)
222- [Routes Configuration](./routes.md)
223- [External Routes](./external-routes.md)
224- [Authentication](./auth.md)
225- [Backups](./backups.md)

index.md RawHistoryFolder