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

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

# Secrets backend
[secrets]
backend = "pass"                         # "pass", "sops", or "unsafe"

# Registry authentication
[registry_auth]
enabled = true
type = "token"                           # "password" or "token"
# Password auth:
# username = "deploy"
# password_hash = "gordon/registry/password_hash"
# Token auth:
token_secret = "gordon/registry/token_secret"
token_expiry = "30d"                     # Duration (1y, 30d, 2w) or 0 for never

# Deploy behavior
[deploy]
pull_policy = "if-tag-changed"           # always, if-not-present, if-tag-changed

# 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"]

Configuration Sections

Section	Description	Documentation
`[server]`	Core server settings	Server
`[secrets]`	Secrets backend configuration	Secrets
`[registry_auth]`	Registry authentication	Registry Auth
`[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

Default Values

Setting	Default
`server.port`	`80`
`server.registry_port`	`5000`
`server.data_dir`	`~/.gordon`
`secrets.backend`	`"unsafe"`
`registry_auth.enabled`	`false`
`registry_auth.type`	`"password"`
`registry_auth.token_expiry`	`"30d"`
`deploy.pull_policy`	`"if-tag-changed"`
`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`

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
secrets.backend
registry_auth settings
deploy.pull_policy

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
26> **Note:** This example shows production-style paths. Default paths use `~/.gordon/` for user installations.
27
28```toml
29# Server settings
30[server]
31port = 8080                              # HTTP proxy port (default: 80)
32registry_port = 5000                     # Registry port (default: 5000)
33gordon_domain = "gordon.mydomain.com"    # Required: Gordon domain (registry + API)
34# data_dir = "~/.gordon"                 # Default for user installations
35
36# Secrets backend
37[secrets]
38backend = "pass"                         # "pass", "sops", or "unsafe"
39
40# Registry authentication
41[registry_auth]
42enabled = true
43type = "token"                           # "password" or "token"
44# Password auth:
45# username = "deploy"
46# password_hash = "gordon/registry/password_hash"
47# Token auth:
48token_secret = "gordon/registry/token_secret"
49token_expiry = "30d"                     # Duration (1y, 30d, 2w) or 0 for never
50
51# Deploy behavior
52[deploy]
53pull_policy = "if-tag-changed"           # always, if-not-present, if-tag-changed
54
55# Logging
56[logging]
57level = "info"                           # trace, debug, info, warn, error
58format = "console"                       # console or json
59
60[logging.file]
61enabled = true
62path = "~/.gordon/logs/gordon.log"       # Default location
63max_size = 100                           # MB before rotation
64max_backups = 3                          # Old files to keep
65max_age = 28                             # Days to keep
66
67[logging.container_logs]
68enabled = true
69dir = "~/.gordon/logs/containers"        # Default location
70max_size = 100
71max_backups = 3
72max_age = 28
73
74# Environment variables
75[env]
76dir = "~/.gordon/env"                    # Default location
77
78# Volume settings
79[volumes]
80auto_create = true                       # Auto-create from Dockerfile VOLUME
81prefix = "gordon"                        # Volume name prefix
82preserve = true                          # Keep volumes on container removal
83
84# Network isolation
85[network_isolation]
86enabled = true                           # Per-app isolated networks
87network_prefix = "gordon"                # Network name prefix
88dns_suffix = ".internal"                 # DNS suffix for services
89
90# Auto-route
91[auto_route]
92enabled = false                          # Auto-create routes from image names
93
94# Routes (required)
95[routes]
96"app.mydomain.com" = "myapp:latest"
97"api.mydomain.com" = "myapi:v2.1.0"
98
99# Network groups
100[network_groups]
101"backend" = ["app.mydomain.com", "api.mydomain.com"]
102
103# Attachments
104[attachments]
105"app.mydomain.com" = ["postgres:latest", "redis:latest"]
106"backend" = ["rabbitmq:latest"]
107```
108
109## Configuration Sections
110
111| Section | Description | Documentation |
112|---------|-------------|---------------|
113| `[server]` | Core server settings | [Server](./server.md) |
114| `[secrets]` | Secrets backend configuration | [Secrets](./secrets.md) |
115| `[registry_auth]` | Registry authentication | [Registry Auth](./registry-auth.md) |
116| `[deploy]` | Deployment behavior | [Deploy](./deploy.md) |
117| `[logging]` | Logging configuration | [Logging](./logging.md) |
118| `[env]` | Environment variable settings | [Environment](./env.md) |
119| `[volumes]` | Volume management | [Volumes](./volumes.md) |
120| `[network_isolation]` | Network isolation settings | [Network Isolation](./network-isolation.md) |
121| `[auto_route]` | Automatic route creation | [Auto Route](./auto-route.md) |
122| `[routes]` | Domain to image mapping | [Routes](./routes.md) |
123| `[external_routes]` | Non-containerized service proxying | [External Routes](./external-routes.md) |
124| `[network_groups]` | Shared service networks | [Network Groups](./network-groups.md) |
125| `[attachments]` | Service dependencies | [Attachments](./attachments.md) |
126
127## Default Values
128
129| Setting | Default |
130|---------|---------|
131| `server.port` | `80` |
132| `server.registry_port` | `5000` |
133| `server.data_dir` | `~/.gordon` |
134| `secrets.backend` | `"unsafe"` |
135| `registry_auth.enabled` | `false` |
136| `registry_auth.type` | `"password"` |
137| `registry_auth.token_expiry` | `"30d"` |
138| `deploy.pull_policy` | `"if-tag-changed"` |
139| `logging.level` | `"info"` |
140| `logging.format` | `"console"` |
141| `logging.file.enabled` | `false` |
142| `logging.file.max_size` | `100` |
143| `logging.file.max_backups` | `3` |
144| `logging.file.max_age` | `28` |
145| `logging.container_logs.enabled` | `true` |
146| `volumes.auto_create` | `true` |
147| `volumes.prefix` | `"gordon"` |
148| `volumes.preserve` | `true` |
149| `network_isolation.enabled` | `false` |
150| `auto_route.enabled` | `false` |
151
152## Hot Reload
153
154Gordon watches the configuration file and reloads automatically when changes are detected. You can also trigger a manual reload:
155
156```bash
157gordon reload
158```
159
160The following settings require a restart to take effect:
161
162- `server.port`
163- `server.registry_port`
164- `server.data_dir`
165- `secrets.backend`
166- `registry_auth` settings
167- `deploy.pull_policy`
168
169## Environment Variable Override
170
171Configuration values can be overridden with environment variables:
172
173```bash
174GORDON_SERVER_PORT=8080 gordon serve
175GORDON_LOGGING_LEVEL=debug gordon serve
176```
177
178Pattern: `GORDON_SECTION_KEY` (uppercase, underscores instead of dots)
179
180## Related
181
182- [Server Configuration](./server.md)
183- [Routes Configuration](./routes.md)
184- [External Routes](./external-routes.md)
185- [Registry Authentication](./registry-auth.md)

index.md RawHistoryFolder