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]
registry_port = 5000
gordon_domain = "gordon.mydomain.com"

[entrypoints.edge]
address = ":443"
protocol = "smart_tcp"

Application workloads live in standalone app files, not in gordon.toml — see App Manifest. Retired workload keys such as [routes], [attachments], [network_groups], app-like [[services]], [service_routes], [auto_route], and [previews] are rejected at startup.

Note: gordon_domain is the canonical registry and Admin API host.

For a staged registry host rename, set the new server.gordon_domain and keep old Gordon registry hosts in server.legacy_registry_domains until clients move. See Server and Upgrading.

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]
registry_port = 5000                     # Registry port (default: 5000)
gordon_domain = "gordon.mydomain.com"    # Required: Gordon domain (registry + API)
# data_dir = "~/.gordon"                 # Default for user installations

[entrypoints.edge]
address = ":443"                         # Deployment-selected public TCP socket
protocol = "smart_tcp"

# 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
# Token-only authentication (password login was removed in v2.30.0)

# 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

# Container runtime profile
[containers]
security_profile = "compat"              # compat or strict

# 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

# Workload logs are streamed directly from the container runtime with
# `gordon apps logs APP --service SERVICE`.

# Telemetry (OpenTelemetry)
[telemetry]
enabled = true                           # Enable OTLP export (default: false)
endpoint = "http://localhost:5080/api/default"  # OTLP HTTP endpoint
auth_token = ""                          # Base64 user:password for Basic auth
traces = true                            # Export traces
metrics = true                           # Export metrics
logs = true                              # Bridge zerolog to OTLP logs
trace_sample_rate = 1.0                  # 0.0 = none, 1.0 = all

# Installation secret store location
[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

# Installation network policy (prefix filter for `gordon networks list`)
[network_isolation]
enabled = true                           # Gordon-managed network policy
network_prefix = "gordon"                # Network name prefix
internal = false                          # Set true to block direct egress from isolated networks

# REMOVED in v3 (declare apps in standalone files, see ./apps.md):
# [routes], [attachments], [network_groups], [[services]]-as-apps,
# [service_routes], [auto_route], [previews]

# Backups
[backups]
enabled = true
schedule = "daily"                        # "hourly", "daily", "weekly", "monthly"
storage_dir = "~/.gordon/backups"

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

# Images
[images]
allowed_registries = []                   # Additional exact registry hostname+port entries
require_digest = false                    # Require SHA-256 digests for every image registry

[images.prune]
enabled = false
schedule = "daily"
keep_last = 3

Docker Hub (docker.io and registry-1.docker.io), ghcr.io, quay.io, and Gordon's registry are allowed by default. Add private or other registries with exact hostname+port entries. This hostname policy does not enforce resolved IP destinations or runtime egress; see Images.

Configuration Sections

Section	Description	Documentation
`[server]`	Core server settings	Server
`[auth]`	Authentication and secrets backend	Auth
`[api.rate_limit]`	Rate limiting configuration	Rate Limiting
`[logging]`	Logging configuration	Logging
`[telemetry]`	OpenTelemetry observability export	Telemetry
`[env]`	Installation secret store location	Environment
`[volumes]`	Volume management	Volumes
`[network_isolation]`	Installation network policy	Network Isolation
`[external_routes]`	Non-containerized service proxying	External Routes
`[entrypoints]`, `[traffic]`, `[[network_services]]`, `[[services]]`	L4 and TLS passthrough traffic plane	Traffic
App files (`<app>.toml`)	Declarative apps: services, hosts, secrets, volumes, backup targets	App Manifest
`[backups]`	Database backup storage, scheduling, and retention	Backups
`[images.prune]`	Scheduled image cleanup	Images
Security hardening	Security controls and recommended knobs	Security Hardening

Default Values

Setting	Default
`server.registry_port`	`5000`
`server.data_dir`	`~/.gordon`
`server.max_blob_chunk_size`	`"95MB"`
`server.max_blob_size`	`"1GB"`
`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`	`[]`
`containers.security_profile`	`"compat"`
`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`
`volumes.auto_create`	`true`
`volumes.prefix`	`"gordon"`
`volumes.preserve`	`true`
`network_isolation.enabled`	`true`
`network_isolation.internal`	`false`
`backups.enabled`	`false`
`backups.schedule`	`"daily"` (`"hourly"`, `"daily"`, `"weekly"`, `"monthly"`)
`images.allowed_registries`	`[]`
`images.require_digest`	`false`
`images.prune.enabled`	`false`
`images.prune.schedule`	`"daily"`
`images.prune.keep_last`	`3`
`telemetry.enabled`	`false`
`telemetry.endpoint`	`""`
`telemetry.auth_token`	`""`
`telemetry.traces`	`true`
`telemetry.metrics`	`true`
`telemetry.logs`	`true`
`telemetry.trace_sample_rate`	`1.0`

When auth.enabled=false, Gordon runs in local-only mode: /admin/* is not registered on the TCP listener and /v2/* is loopback-only. Local gordon apps commands discover the daemon's owner-only admin socket in $XDG_RUNTIME_DIR/gordon, /run/user/<uid>/gordon, or ~/.gordon/run; the daemon itself uses the XDG location when configured and otherwise the home fallback. See Authentication.

Hot Reload

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

gordon reload

Hot-reloaded (no restart needed)

Setting
`server.gordon_domain` (registry domain)
`server.registry_port`
`server.max_proxy_body_size`
`server.max_proxy_response_size`
`server.max_concurrent_conns`

Requires restart

Setting
`entrypoints.edge.address`
`server.data_dir`
`server.max_blob_chunk_size`
`server.max_blob_size`
`auth.*`

Environment Variable Override

Configuration values can be overridden with environment variables:

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]
16registry_port = 5000
17gordon_domain = "gordon.mydomain.com"
18
19[entrypoints.edge]
20address = ":443"
21protocol = "smart_tcp"
22```
23
24Application workloads live in standalone app files, not in `gordon.toml` — see [App Manifest](./apps.md). Retired workload keys such as `[routes]`, `[attachments]`, `[network_groups]`, app-like `[[services]]`, `[service_routes]`, `[auto_route]`, and `[previews]` are rejected at startup.
25
26> **Note:** `gordon_domain` is the canonical registry and Admin API host.
27>
28> For a staged registry host rename, set the new `server.gordon_domain` and keep old Gordon registry hosts in `server.legacy_registry_domains` until clients move. See [Server](./server.md#gordon-domain) and [Upgrading](../upgrading.md#staged-registry-host-rename).
29
30## Full Configuration Reference
31
32For a complete list of all configuration options with their default values, see the [Configuration Reference](./reference.md).
33
34> **Note:** This example shows production-style paths. Default paths use `~/.gordon/` for user installations.
35
36```toml
37# Server settings
38[server]
39registry_port = 5000                     # Registry port (default: 5000)
40gordon_domain = "gordon.mydomain.com"    # Required: Gordon domain (registry + API)
41# data_dir = "~/.gordon"                 # Default for user installations
42
43[entrypoints.edge]
44address = ":443"                         # Deployment-selected public TCP socket
45protocol = "smart_tcp"
46
47# Authentication (includes secrets backend)
48[auth]
49enabled = true                           # Enable registry authentication (default: true)
50secrets_backend = "pass"                 # "pass", "sops", or "unsafe"
51token_secret = "gordon/auth/token_secret"  # Required: JWT signing secret
52token_expiry = "30d"                     # Duration (1y, 30d, 2w) or 0 for never
53# Token-only authentication (password login was removed in v2.30.0)
54
55# API rate limiting
56[api.rate_limit]
57enabled = true                           # Enable rate limiting (default: true)
58global_rps = 500                         # Max requests/second globally
59per_ip_rps = 50                          # Max requests/second per IP
60burst = 100                              # Burst size
61trusted_proxies = []                     # IPs/CIDRs trusted for X-Forwarded-For
62
63# Container runtime profile
64[containers]
65security_profile = "compat"              # compat or strict
66
67# Logging
68[logging]
69level = "info"                           # trace, debug, info, warn, error
70format = "console"                       # console or json
71
72[logging.file]
73enabled = true
74path = "~/.gordon/logs/gordon.log"       # Default location
75max_size = 100                           # MB before rotation
76max_backups = 3                          # Old files to keep
77max_age = 28                             # Days to keep
78
79# Workload logs are streamed directly from the container runtime with
80# `gordon apps logs APP --service SERVICE`.
81
82# Telemetry (OpenTelemetry)
83[telemetry]
84enabled = true                           # Enable OTLP export (default: false)
85endpoint = "http://localhost:5080/api/default"  # OTLP HTTP endpoint
86auth_token = ""                          # Base64 user:password for Basic auth
87traces = true                            # Export traces
88metrics = true                           # Export metrics
89logs = true                              # Bridge zerolog to OTLP logs
90trace_sample_rate = 1.0                  # 0.0 = none, 1.0 = all
91
92# Installation secret store location
93[env]
94dir = "~/.gordon/env"                    # Default location
95
96# Volume settings
97[volumes]
98auto_create = true                       # Auto-create from Dockerfile VOLUME
99prefix = "gordon"                        # Volume name prefix
100preserve = true                          # Keep volumes on container removal
101
102# Installation network policy (prefix filter for `gordon networks list`)
103[network_isolation]
104enabled = true                           # Gordon-managed network policy
105network_prefix = "gordon"                # Network name prefix
106internal = false                          # Set true to block direct egress from isolated networks
107
108# REMOVED in v3 (declare apps in standalone files, see ./apps.md):
109# [routes], [attachments], [network_groups], [[services]]-as-apps,
110# [service_routes], [auto_route], [previews]
111
112# Backups
113[backups]
114enabled = true
115schedule = "daily"                        # "hourly", "daily", "weekly", "monthly"
116storage_dir = "~/.gordon/backups"
117
118[backups.retention]
119hourly = 24
120daily = 7
121weekly = 4
122monthly = 12
123
124# Images
125[images]
126allowed_registries = []                   # Additional exact registry hostname+port entries
127require_digest = false                    # Require SHA-256 digests for every image registry
128
129[images.prune]
130enabled = false
131schedule = "daily"
132keep_last = 3
133```
134
135Docker Hub (`docker.io` and `registry-1.docker.io`), `ghcr.io`, `quay.io`, and Gordon's registry are allowed by default. Add private or other registries with exact hostname+port entries. This hostname policy does not enforce resolved IP destinations or runtime egress; see [Images](./images.md).
136
137## Configuration Sections
138
139| Section | Description | Documentation |
140|---------|-------------|---------------|
141| `[server]` | Core server settings | [Server](./server.md) |
142| `[auth]` | Authentication and secrets backend | [Auth](./auth.md) |
143| `[api.rate_limit]` | Rate limiting configuration | [Rate Limiting](./rate-limiting.md) |
144| `[logging]` | Logging configuration | [Logging](./logging.md) |
145| `[telemetry]` | OpenTelemetry observability export | [Telemetry](./telemetry.md) |
146| `[env]` | Installation secret store location | [Environment](./env.md) |
147| `[volumes]` | Volume management | [Volumes](./volumes.md) |
148| `[network_isolation]` | Installation network policy | [Network Isolation](./network-isolation.md) |
149| `[external_routes]` | Non-containerized service proxying | [External Routes](./external-routes.md) |
150| `[entrypoints]`, `[traffic]`, `[[network_services]]`, `[[services]]` | L4 and TLS passthrough traffic plane | [Traffic](./traffic.md) |
151| App files (`<app>.toml`) | Declarative apps: services, hosts, secrets, volumes, backup targets | [App Manifest](./apps.md) |
152| `[backups]` | Database backup storage, scheduling, and retention | [Backups](./backups.md) |
153| `[images.prune]` | Scheduled image cleanup | [Images](./images.md) |
154| Security hardening | Security controls and recommended knobs | [Security Hardening](./security-hardening.md) |
155
156## Default Values
157
158| Setting | Default |
159|---------|---------|
160| `server.registry_port` | `5000` |
161| `server.data_dir` | `~/.gordon` |
162| `server.max_blob_chunk_size` | `"95MB"` |
163| `server.max_blob_size` | `"1GB"` |
164| `auth.enabled` | `true` |
165| `auth.secrets_backend` | `"unsafe"` |
166| `auth.token_expiry` | `"30d"` |
167| `api.rate_limit.enabled` | `true` |
168| `api.rate_limit.global_rps` | `500` |
169| `api.rate_limit.per_ip_rps` | `50` |
170| `api.rate_limit.burst` | `100` |
171| `api.rate_limit.trusted_proxies` | `[]` |
172| `containers.security_profile` | `"compat"` |
173| `logging.level` | `"info"` |
174| `logging.format` | `"console"` |
175| `logging.file.enabled` | `false` |
176| `logging.file.max_size` | `100` |
177| `logging.file.max_backups` | `3` |
178| `logging.file.max_age` | `28` |
179| `volumes.auto_create` | `true` |
180| `volumes.prefix` | `"gordon"` |
181| `volumes.preserve` | `true` |
182| `network_isolation.enabled` | `true` |
183| `network_isolation.internal` | `false` |
184| `backups.enabled` | `false` |
185| `backups.schedule` | `"daily"` (`"hourly"`, `"daily"`, `"weekly"`, `"monthly"`) |
186| `images.allowed_registries` | `[]` |
187| `images.require_digest` | `false` |
188| `images.prune.enabled` | `false` |
189| `images.prune.schedule` | `"daily"` |
190| `images.prune.keep_last` | `3` |
191| `telemetry.enabled` | `false` |
192| `telemetry.endpoint` | `""` |
193| `telemetry.auth_token` | `""` |
194| `telemetry.traces` | `true` |
195| `telemetry.metrics` | `true` |
196| `telemetry.logs` | `true` |
197| `telemetry.trace_sample_rate` | `1.0` |
198
199When `auth.enabled=false`, Gordon runs in local-only mode: `/admin/*` is not registered on the TCP listener and `/v2/*` is loopback-only. Local `gordon apps` commands discover the daemon's owner-only admin socket in `$XDG_RUNTIME_DIR/gordon`, `/run/user/<uid>/gordon`, or `~/.gordon/run`; the daemon itself uses the XDG location when configured and otherwise the home fallback. See [Authentication](./auth.md#local-only-mode).
200
201## Hot Reload
202
203Gordon watches the configuration file and reloads automatically when changes are detected. You can also trigger a manual reload:
204
205```bash
206gordon reload
207```
208
209### Hot-reloaded (no restart needed)
210
211| Setting |
212|---------|
213| `server.gordon_domain` (registry domain) |
214| `server.registry_port` |
215| `server.max_proxy_body_size` |
216| `server.max_proxy_response_size` |
217| `server.max_concurrent_conns` |
218
219
220### Requires restart
221
222| Setting |
223|---------|
224| `entrypoints.edge.address` |
225| `server.data_dir` |
226| `server.max_blob_chunk_size` |
227| `server.max_blob_size` |
228| `auth.*` |
229
230## Environment Variable Override
231
232Configuration values can be overridden with environment variables:
233
234```bash
235GORDON_LOGGING_LEVEL=debug gordon serve
236```
237
238Pattern: `GORDON_SECTION_KEY` (uppercase, underscores instead of dots)
239
240## Related
241
242- [Server Configuration](./server.md)
243- [App Manifest](./apps.md)
244- [External Routes](./external-routes.md)
245- [Standalone Services](./services.md)
246- [Traffic Plane](./traffic.md)
247- [Authentication](./auth.md)
248- [Telemetry](./telemetry.md)
249- [Backups](./backups.md)
250- [Images](./images.md)

index.md RawHistoryFolder