reference.md Raw History Folder

Configuration Reference

Complete configuration reference with all options and their default values.

Full Configuration Example

# =============================================================================
# SERVER
# =============================================================================
[server]
registry_port = 5000                         # Container registry port
tls_cert_file = ""                           # PEM cert path (optional, for static TLS fallback)
tls_key_file = ""                            # PEM key path (optional, must be set with tls_cert_file)
force_https_redirect = false                 # Redirect all HTTP traffic to HTTPS (for direct-access setups)
gordon_domain = ""                           # Required: Gordon domain (registry + API)
data_dir = "~/.gordon"                       # Data directory (varies by install type)
max_blob_chunk_size = "95MB"                 # Max size per registry blob upload chunk
max_blob_size = "1GB"                        # Max cumulative size per registry blob/layer upload
registry_allowed_ips = []                    # IPs or CIDR ranges allowed to access the registry (empty = allow all)
proxy_allowed_ips = []                       # IPs or CIDR ranges allowed to reach HTTP proxy paths (empty = allow all, e.g. Cloudflare IPs)
registry_listen_address = ""                 # Bind address for registry (empty = all interfaces, "127.0.0.1" = loopback only)

# =============================================================================
# ENTRYPOINTS
# =============================================================================
[entrypoints.edge]
address = ":443"                             # Deployment-selected public TCP socket
protocol = "smart_tcp"                       # Sniff HTTP, h2c, TLS, passthrough, or explicit raw fallback
trusted_cidrs = []                            # Peer socket IP allowlist for all traffic on this entrypoint
# raw_fallback = "ssh-fallback"              # Optional TCP router for unknown non-HTTP/non-TLS bytes
# raw_fallback_trusted_cidrs = ["100.64.0.0/10"]
# allow_public_raw_fallback = false

# =============================================================================
# DNS
# =============================================================================
[dns]
resolvers = ["1.1.1.1:53", "8.8.8.8:53"] # Recursive resolvers for public DNS visibility checks
propagation_timeout = "5m"                 # Max wait for DNS-01 TXT propagation
polling_interval = "5s"                    # Interval between DNS-01 propagation checks

# =============================================================================
# AUTHENTICATION (required - Gordon won't start without credentials configured)
# =============================================================================
[auth]
enabled = true                               # Enable registry authentication (default: true)
secrets_backend = "unsafe"                   # "pass", "sops", or "unsafe"
token_secret = ""                            # Path in secrets backend to JWT signing key (REQUIRED)
token_expiry = "30d"                         # Token expiry duration
access_token_ttl = "15m"                     # Ephemeral access token lifetime (default: 15m)

# =============================================================================
# PUBLIC TLS / ACME
# =============================================================================
[tls.acme]
enabled = false                              # Enable public ACME certificates (requires HTTPS fallback on a TLS-capable entrypoint)
email = ""                                   # ACME account email when enabled
challenge = "auto"                           # "auto", "http-01", or "cloudflare-dns-01"
obtain_batch_size = 1                         # New certificate orders per reconcile run

# =============================================================================
# API (applies to both Registry and Admin endpoints)
# =============================================================================
[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 client IP
burst = 100                                  # Burst size for rate limiters
trusted_proxies = []                         # IPs/CIDRs trusted to set X-Forwarded-For

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

[logging.file]
enabled = false                              # Enable file logging
path = ""                                    # Log file path (default: {data_dir}/logs/gordon.log)
max_size = 100                               # Max size in MB before rotation
max_backups = 3                              # Number of old files to keep
max_age = 28                                 # Days to keep old files

# Workload logs are streamed from the container runtime with
# `gordon apps logs APP --service SERVICE`. The accepted
# logging.container_logs fields are not connected to a production file sink.

[logging.access_log]
enabled = false                              # Dedicated HTTP access log for reverse-proxy traffic
format = "json"                             # "json", "clf", or "combined"
output = "stdout"                           # "stdout", "file", or "journald"
file_path = ""                               # Required when output = "file"
max_size = 100                               # Max size in MB before rotation (file output)
max_backups = 3                              # Number of old files to keep (file output)
max_age = 28                                 # Days to keep old files (file output)
exclude_health_checks = true                 # Skip noisy readiness/liveness requests
syslog_identifier = "gordon-access"         # Journald identifier when output = "journald"

# =============================================================================
# TELEMETRY (OpenTelemetry)
# =============================================================================
[telemetry]
enabled = false                              # Enable OTLP telemetry export
endpoint = ""                                # OTLP HTTP endpoint URL
auth_token = ""                              # Base64-encoded user:password for Basic auth
traces = true                                # Export distributed traces
metrics = true                               # Export metrics
logs = true                                  # Bridge zerolog output to OTLP logs
trace_sample_rate = 1.0                      # Fraction of traces to sample (0.0–1.0)

# =============================================================================
# ENVIRONMENT
# =============================================================================
[env]
dir = ""                                     # Env files directory (default: {data_dir}/env)

# =============================================================================
# CONTAINERS
# =============================================================================
[containers]
security_profile = "compat"                  # "compat" or "strict"

# =============================================================================
# NETWORK ISOLATION
# =============================================================================
[network_isolation]
enabled = true                               # Installation network policy for Gordon-managed networks
network_prefix = "gordon"                    # Prefix filter for `gordon networks list`
internal = false                             # Create Docker internal networks (blocks direct egress)

# =============================================================================
# VOLUMES
# =============================================================================
[volumes]
auto_create = true                           # Auto-create volumes from Dockerfile VOLUME
prefix = "gordon"                            # Volume name prefix
preserve = true                              # Keep volumes when containers are removed

# =============================================================================
# ADMINISTRATIVE APP BIND MOUNTS
# =============================================================================
# A named policy is the only way an app manifest may reference a host path.
# App manifests declare [[service.bind]] with name = "<mount>"; direct host
# paths are always rejected, and the policy's allowlists are exact and
# non-empty. read_only on the policy and readonly on the bind both force
# read-only: either side wins and a bind never weakens its policy.
# [app_mounts.app-logs]
# source = "/srv/gordon/host-logs"           # Required; absolute, normalized
# read_only = true                           # Force read-only for this mount
# allowed_apps = ["metrics-agent"]           # Required; exact, non-empty
# allowed_services = ["web"]                 # Required; exact, non-empty
# root = "/srv/gordon"                       # Optional; default: parent of source

# =============================================================================
# ADMINISTRATIVE APP DEVICES (CDI)
# =============================================================================
# A named device grant is the only way an app manifest may request host
# devices. Manifests declare devices = ["<name>"]; raw /dev paths are
# always rejected, and the policy's allowlists are exact and non-empty.
# Aggregate "=all" CDI selectors are rejected: name every device
# explicitly. Device-bearing creates require Podman 5.4+ or Docker 28.3+
# with native CDI configured.
# [app_devices.transcode-gpu]
# cdi = ["example.com/gpu=GPU-device-uuid"]  # Required; explicit, non-empty
# allowed_apps = ["video"]                   # Required; exact, non-empty
# allowed_services = ["transcoder"]          # Required; exact, non-empty

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

# =============================================================================
# EXTERNAL ROUTES
# =============================================================================
[external_routes]
# "domain.com" = "host:port"                 # Proxy to non-container services

# =============================================================================
# STANDALONE SERVICES
# =============================================================================
# [[services]]
# name = "rust"
# image = "registry.example.com:5000/rust:latest"
# enabled = true
# env_file = "/srv/gordon/services/rust.env"
#
# [[services.ports]]
# name = "game"
# container = 28015
# protocol = "udp"
# publish = "127.0.0.1:38015"
#
# [[services.ports]]
# name = "rcon"
# container = 28016
# protocol = "tcp"
# publish = "127.0.0.1:38016"
# trusted_cidrs = ["100.64.0.0/10"]

# =============================================================================
# BACKUPS
# =============================================================================
[backups]
enabled = false                              # Enable backup service
schedule = "daily"                          # "hourly", "daily", "weekly", "monthly"
storage_dir = ""                            # Backup root (default: {data_dir}/backups)

[backups.retention]
hourly = 0                                   # Keep N hourly backups per DB
daily = 0                                    # Keep N daily backups per DB
weekly = 0                                   # Keep N weekly backups per DB
monthly = 0                                  # Keep N monthly backups per DB

# =============================================================================
# IMAGES
# =============================================================================
[images]
# Defaults: docker.io/registry-1.docker.io, ghcr.io, quay.io, Gordon registry.
# Add private or other registries as exact hostname+port entries.
allowed_registries = []
require_digest = false

[images.prune]
enabled = false                              # Enable scheduled image cleanup
schedule = "daily"                          # "hourly", "daily", "weekly", "monthly"
keep_last = 3                                # Keep N newest tags per repository

# Note: retention values set to 0 keep no backups for that tier.
# For practical defaults, consider setting daily = 7.

Default Values Summary

Setting	Default	Description
`server.registry_port`	`5000`	Container registry port
`server.tls_cert_file`	`""`	PEM cert path for static TLS (optional)
`server.tls_key_file`	`""`	PEM key path for static TLS (optional)
`server.force_https_redirect`	`false`	Redirect all HTTP to HTTPS (for direct-access setups)
`server.gordon_domain`	`""`	Required - Gordon domain
`server.data_dir`	`~/.gordon`	Data directory
`server.max_blob_chunk_size`	`"95MB"`	Max size per registry blob upload chunk
`server.max_blob_size`	`"1GB"`	Max cumulative size per registry blob/layer upload
`server.registry_allowed_ips`	`[]`	IPs or CIDR ranges allowed to access the registry (empty = allow all)
`server.proxy_allowed_ips`	`[]`	IPs or CIDR ranges allowed to reach the proxy (empty = allow all)
`server.registry_listen_address`	`""`	Bind address for registry (empty = all interfaces)
`entrypoints.<name>.address`	none	Deployment-selected listen address; `edge` is conventional for route-capable entrypoints but is not required when exactly one `smart_tcp` or `tls_mux` entrypoint exists
`entrypoints.<name>.protocol`	none	Entrypoint protocol: `smart_tcp`, `tls_mux`, `tcp`, or `udp`
`entrypoints.<name>.trusted_cidrs`	`[]`	Peer socket IP allowlist for all traffic on the entrypoint
`entrypoints.<name>.raw_fallback`	`""`	TCP router used by smart TCP for unknown non-HTTP/non-TLS bytes
`entrypoints.<name>.raw_fallback_trusted_cidrs`	`[]`	Peer socket IP allowlist for smart TCP raw fallback
`entrypoints.<name>.allow_public_raw_fallback`	`false`	Explicit acknowledgement for public raw fallback exposure
`dns.resolvers`	`["1.1.1.1:53", "8.8.8.8:53"]`	Recursive resolvers used for public DNS visibility checks, including ACME DNS-01 propagation
`dns.propagation_timeout`	`"5m"`	Maximum time to wait for DNS-01 TXT records to become visible through configured recursive resolvers
`dns.polling_interval`	`"5s"`	Interval between DNS-01 propagation checks
`tls.acme.enabled`	`false`	Enable public ACME certificates (requires HTTPS fallback on a TLS-capable entrypoint)
`tls.acme.email`	`""`	ACME account email when enabled
`tls.acme.challenge`	`"auto"`	ACME challenge mode: `auto`, `http-01`, or `cloudflare-dns-01`
`tls.acme.obtain_batch_size`	`1`	Maximum new ACME certificate orders per reconcile run
`auth.enabled`	`true`	Enable authentication; when `false`, run local-only mode (loopback-only `/v2/`, TCP `/admin/` not registered, owner-only admin socket for local `gordon apps`)
`auth.secrets_backend`	`"unsafe"`	Secrets storage
`auth.token_expiry`	`"30d"`	30 days
`auth.access_token_ttl`	`"15m"`	Ephemeral access token lifetime
`api.rate_limit.enabled`	`true`	Enable rate limiting
`api.rate_limit.global_rps`	`500`	Global requests/second
`api.rate_limit.per_ip_rps`	`50`	Per-IP requests/second
`api.rate_limit.burst`	`100`	Burst size
`api.rate_limit.trusted_proxies`	`[]`	IPs/CIDRs trusted for X-Forwarded-For
`logging.level`	`"info"`	Log level
`logging.format`	`"console"`	Log format
`logging.file.enabled`	`false`	File logging disabled
`logging.file.max_size`	`100`	100 MB
`logging.file.max_backups`	`3`	Keep 3 old files
`logging.file.max_age`	`28`	28 days
`logging.access_log.enabled`	`false`	Dedicated HTTP access log disabled
`logging.access_log.format`	`"json"`	Access log format (`json`, `clf`, `combined`)
`logging.access_log.output`	`"stdout"`	Access log sink (`stdout`, `file`, `journald`)
`logging.access_log.max_size`	`100`	100 MB for file output
`logging.access_log.max_backups`	`3`	Keep 3 old files for file output
`logging.access_log.max_age`	`28`	28 days for file output
`logging.access_log.exclude_health_checks`	`true`	Skip health-check requests
`logging.access_log.syslog_identifier`	`"gordon-access"`	Journald identifier
`telemetry.enabled`	`false`	Enable OTLP telemetry export
`telemetry.endpoint`	`""`	OTLP HTTP endpoint URL
`telemetry.auth_token`	`""`	Base64 `user:password` for Basic auth
`telemetry.traces`	`true`	Export distributed traces
`telemetry.metrics`	`true`	Export metrics
`telemetry.logs`	`true`	Bridge zerolog to OTLP logs
`telemetry.trace_sample_rate`	`1.0`	Fraction of traces to sample (0.0–1.0)
`containers.security_profile`	`"compat"`	Runtime hardening profile: `compat` preserves existing behavior, `strict` enables read-only rootfs and narrower capabilities
`network_isolation.enabled`	`true`	Network isolation enabled
`network_isolation.network_prefix`	`"gordon"`	Network prefix
`network_isolation.internal`	`false`	Create Docker internal networks without direct external egress
`volumes.auto_create`	`true`	Auto-create volumes
`volumes.prefix`	`"gordon"`	Volume prefix
`volumes.preserve`	`true`	Keep volumes
`app_mounts.<name>.source`	none	Required host source of a named administrative bind; absolute and normalized. The only host path that mount may come from
`app_mounts.<name>.allowed_apps`	none	Required exact, non-empty app allowlist for this mount (no wildcard or empty-means-all form)
`app_mounts.<name>.allowed_services`	none	Required exact, non-empty service allowlist for this mount
`app_mounts.<name>.read_only`	`false`	Force every bind resolved under this policy read-only; a manifest bind can never weaken it
`app_mounts.<name>.root`	parent of `source`	Optional administrative boundary the resolved source must stay under
`app_devices.<name>.cdi`	none	Required explicit, non-empty CDI device IDs granted under this logical name (no `=all` aggregate form)
`app_devices.<name>.allowed_apps`	none	Required exact, non-empty app allowlist for this grant (no wildcard or empty-means-all form)
`app_devices.<name>.allowed_services`	none	Required exact, non-empty service allowlist for this grant
`services[].name`	none	Standalone service name used by `service:<service>:<port-name>` traffic refs
`services[].image`	none	Container image for enabled standalone services
`services[].enabled`	`false`	Whether Gordon creates, starts, and reconciles the service container
`services[].env`	`[]`	Inline `KEY=value` environment entries
`services[].env_file`	`""`	Env file loaded before inline entries
`services[].ports[].name`	none	Port name used by traffic service refs
`services[].ports[].container`	none	Container port number
`services[].ports[].protocol`	none	`tcp` or `udp`
`services[].ports[].publish`	`""`	Host-side bind address, usually loopback, that the traffic manager dials
`services[].ports[].private`	`false`	Require matching service and entrypoint `trusted_cidrs` for this port
`services[].ports[].public`	`false`	Explicit public opt-out for admin port names such as `rcon`
`services[].ports[].trusted_cidrs`	`[]`	CIDRs allowed for private port routing; must match the target entrypoint
`services[].volumes[].source`	`""`	Explicit named volume or bind source; omitted service volumes use image `VOLUME` metadata
`services[].volumes[].target`	none	Absolute container mount path
`services[].volumes[].read_only`	`false`	Mount explicit volume read-only
`services[].readiness.type`	`"none"`	`none`, `tcp`, or `log`
`services[].readiness.path`	`""`	Log readiness path inside the container
`services[].readiness.contains`	`""`	Text required in the readiness log
`services[].readiness.timeout`	default wait	Positive readiness timeout when set
`services[].cleanup.preserve_volumes`	`true`	Preserve managed image-discovered volumes on cleanup
`services[].cleanup.remove_container`	`true`	Remove old, disabled, or removed service containers
`backups.enabled`	`false`	Backup service disabled
`backups.schedule`	`"daily"`	Backup scheduler preset
`backups.storage_dir`	`""`	Uses `{server.data_dir}/backups` when empty
`backups.retention.hourly`	`0`	Keep no hourly backups by default
`backups.retention.daily`	`0`	Keep no daily backups by default (recommend `7`)
`backups.retention.weekly`	`0`	Keep no weekly backups by default
`backups.retention.monthly`	`0`	Keep no monthly backups by default
`images.allowed_registries`	`[]`	Additional exact hostname+port entries. Defaults allow Docker Hub (`docker.io` and `registry-1.docker.io`), `ghcr.io`, `quay.io`, and Gordon's registry. This allowlist does not configure registry credentials and is not DNS/IP or runtime egress enforcement.
`images.require_digest`	`false`	Require valid SHA-256 digest-pinned references for every registry, including Gordon
`images.prune.enabled`	`false`	Scheduled image cleanup disabled
`images.prune.schedule`	`"daily"`	Cleanup schedule preset
`images.prune.keep_last`	`3`	Number of recent tags kept per repository

Note: for all backups.retention.* keys, 0 means keep no backups for that retention tier.

App Manifest HTTP Interfaces

[[service.http]] declares HTTP interfaces in a standalone app manifest (see App Manifest).

Key	Values	Default	Description
`service.http[].visibility`	`"public"`, `"internal"`	`"public"`	`public` is proxied by host and may terminate TLS; `internal` is reachable only from the app's private network
`service.http[].host`	hostname	none	Required for public interfaces; must be absent for `visibility = "internal"`
`service.http[].port`	integer	none	Required container port for every interface
`service.http[].tls`	`"auto"`, `"always"`, `"never"`	`"auto"`	Public interfaces only; `visibility = "internal"` rejects any declared value

visibility = "internal" creates no proxy route, host reservation, certificate target, or host port publication. A container port declared by both an internal HTTP interface and an externally backed interface (public HTTP or TCP) is rejected, as are duplicate internal HTTP ports.

Environment Variables

All configuration options can be set via environment variables using the pattern:

GORDON_<SECTION>_<KEY>=value

Examples:

GORDON_SERVER_GORDON_DOMAIN=gordon.example.com
GORDON_AUTH_ENABLED=true
GORDON_LOGGING_LEVEL=debug
GORDON_NETWORK_ISOLATION_ENABLED=true

Nested keys use underscores:

GORDON_LOGGING_FILE_ENABLED=true
GORDON_LOGGING_FILE_MAX_SIZE=200
GORDON_LOGGING_CONTAINER_LOGS_ENABLED=false

Security Environment Variables

These special environment variables take priority over config file values:

Variable	Description
`GORDON_AUTH_TOKEN_SECRET`	JWT signing secret (avoids storing secret on disk)

Example:

export GORDON_AUTH_TOKEN_SECRET="your-secure-32-char-secret-here"
gordon serve

Pull Policy Options

Value	Behavior
`"always"`	Always pull image before deploying
`"if-tag-changed"`	Pull only if image tag differs from running container
`"never"`	Never pull, use local image only

Secrets Backend Options

Value	Description
`"pass"`	Unix password manager (recommended for production)
`"sops"`	Mozilla SOPS encrypted files
`"unsafe"`	Plain text files (development only)

Log Level Options

Value	Description
`"debug"`	Verbose debugging information
`"info"`	General operational information
`"warn"`	Warning conditions
`"error"`	Error conditions only

source

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]
12registry_port = 5000                         # Container registry port
13tls_cert_file = ""                           # PEM cert path (optional, for static TLS fallback)
14tls_key_file = ""                            # PEM key path (optional, must be set with tls_cert_file)
15force_https_redirect = false                 # Redirect all HTTP traffic to HTTPS (for direct-access setups)
16gordon_domain = ""                           # Required: Gordon domain (registry + API)
17data_dir = "~/.gordon"                       # Data directory (varies by install type)
18max_blob_chunk_size = "95MB"                 # Max size per registry blob upload chunk
19max_blob_size = "1GB"                        # Max cumulative size per registry blob/layer upload
20registry_allowed_ips = []                    # IPs or CIDR ranges allowed to access the registry (empty = allow all)
21proxy_allowed_ips = []                       # IPs or CIDR ranges allowed to reach HTTP proxy paths (empty = allow all, e.g. Cloudflare IPs)
22registry_listen_address = ""                 # Bind address for registry (empty = all interfaces, "127.0.0.1" = loopback only)
23
24# =============================================================================
25# ENTRYPOINTS
26# =============================================================================
27[entrypoints.edge]
28address = ":443"                             # Deployment-selected public TCP socket
29protocol = "smart_tcp"                       # Sniff HTTP, h2c, TLS, passthrough, or explicit raw fallback
30trusted_cidrs = []                            # Peer socket IP allowlist for all traffic on this entrypoint
31# raw_fallback = "ssh-fallback"              # Optional TCP router for unknown non-HTTP/non-TLS bytes
32# raw_fallback_trusted_cidrs = ["100.64.0.0/10"]
33# allow_public_raw_fallback = false
34
35# =============================================================================
36# DNS
37# =============================================================================
38[dns]
39resolvers = ["1.1.1.1:53", "8.8.8.8:53"] # Recursive resolvers for public DNS visibility checks
40propagation_timeout = "5m"                 # Max wait for DNS-01 TXT propagation
41polling_interval = "5s"                    # Interval between DNS-01 propagation checks
42
43# =============================================================================
44# AUTHENTICATION (required - Gordon won't start without credentials configured)
45# =============================================================================
46[auth]
47enabled = true                               # Enable registry authentication (default: true)
48secrets_backend = "unsafe"                   # "pass", "sops", or "unsafe"
49token_secret = ""                            # Path in secrets backend to JWT signing key (REQUIRED)
50token_expiry = "30d"                         # Token expiry duration
51access_token_ttl = "15m"                     # Ephemeral access token lifetime (default: 15m)
52
53# =============================================================================
54# PUBLIC TLS / ACME
55# =============================================================================
56[tls.acme]
57enabled = false                              # Enable public ACME certificates (requires HTTPS fallback on a TLS-capable entrypoint)
58email = ""                                   # ACME account email when enabled
59challenge = "auto"                           # "auto", "http-01", or "cloudflare-dns-01"
60obtain_batch_size = 1                         # New certificate orders per reconcile run
61
62# =============================================================================
63# API (applies to both Registry and Admin endpoints)
64# =============================================================================
65[api.rate_limit]
66enabled = true                               # Enable rate limiting (default: true)
67global_rps = 500                             # Max requests/second globally
68per_ip_rps = 50                              # Max requests/second per client IP
69burst = 100                                  # Burst size for rate limiters
70trusted_proxies = []                         # IPs/CIDRs trusted to set X-Forwarded-For
71
72# =============================================================================
73# LOGGING
74# =============================================================================
75[logging]
76level = "info"                               # "debug", "info", "warn", "error"
77format = "console"                           # "console" or "json"
78
79[logging.file]
80enabled = false                              # Enable file logging
81path = ""                                    # Log file path (default: {data_dir}/logs/gordon.log)
82max_size = 100                               # Max size in MB before rotation
83max_backups = 3                              # Number of old files to keep
84max_age = 28                                 # Days to keep old files
85
86# Workload logs are streamed from the container runtime with
87# `gordon apps logs APP --service SERVICE`. The accepted
88# logging.container_logs fields are not connected to a production file sink.
89
90[logging.access_log]
91enabled = false                              # Dedicated HTTP access log for reverse-proxy traffic
92format = "json"                             # "json", "clf", or "combined"
93output = "stdout"                           # "stdout", "file", or "journald"
94file_path = ""                               # Required when output = "file"
95max_size = 100                               # Max size in MB before rotation (file output)
96max_backups = 3                              # Number of old files to keep (file output)
97max_age = 28                                 # Days to keep old files (file output)
98exclude_health_checks = true                 # Skip noisy readiness/liveness requests
99syslog_identifier = "gordon-access"         # Journald identifier when output = "journald"
100
101# =============================================================================
102# TELEMETRY (OpenTelemetry)
103# =============================================================================
104[telemetry]
105enabled = false                              # Enable OTLP telemetry export
106endpoint = ""                                # OTLP HTTP endpoint URL
107auth_token = ""                              # Base64-encoded user:password for Basic auth
108traces = true                                # Export distributed traces
109metrics = true                               # Export metrics
110logs = true                                  # Bridge zerolog output to OTLP logs
111trace_sample_rate = 1.0                      # Fraction of traces to sample (0.0–1.0)
112
113# =============================================================================
114# ENVIRONMENT
115# =============================================================================
116[env]
117dir = ""                                     # Env files directory (default: {data_dir}/env)
118
119# =============================================================================
120# CONTAINERS
121# =============================================================================
122[containers]
123security_profile = "compat"                  # "compat" or "strict"
124
125# =============================================================================
126# NETWORK ISOLATION
127# =============================================================================
128[network_isolation]
129enabled = true                               # Installation network policy for Gordon-managed networks
130network_prefix = "gordon"                    # Prefix filter for `gordon networks list`
131internal = false                             # Create Docker internal networks (blocks direct egress)
132
133# =============================================================================
134# VOLUMES
135# =============================================================================
136[volumes]
137auto_create = true                           # Auto-create volumes from Dockerfile VOLUME
138prefix = "gordon"                            # Volume name prefix
139preserve = true                              # Keep volumes when containers are removed
140
141# =============================================================================
142# ADMINISTRATIVE APP BIND MOUNTS
143# =============================================================================
144# A named policy is the only way an app manifest may reference a host path.
145# App manifests declare [[service.bind]] with name = "<mount>"; direct host
146# paths are always rejected, and the policy's allowlists are exact and
147# non-empty. read_only on the policy and readonly on the bind both force
148# read-only: either side wins and a bind never weakens its policy.
149# [app_mounts.app-logs]
150# source = "/srv/gordon/host-logs"           # Required; absolute, normalized
151# read_only = true                           # Force read-only for this mount
152# allowed_apps = ["metrics-agent"]           # Required; exact, non-empty
153# allowed_services = ["web"]                 # Required; exact, non-empty
154# root = "/srv/gordon"                       # Optional; default: parent of source
155
156# =============================================================================
157# ADMINISTRATIVE APP DEVICES (CDI)
158# =============================================================================
159# A named device grant is the only way an app manifest may request host
160# devices. Manifests declare devices = ["<name>"]; raw /dev paths are
161# always rejected, and the policy's allowlists are exact and non-empty.
162# Aggregate "=all" CDI selectors are rejected: name every device
163# explicitly. Device-bearing creates require Podman 5.4+ or Docker 28.3+
164# with native CDI configured.
165# [app_devices.transcode-gpu]
166# cdi = ["example.com/gpu=GPU-device-uuid"]  # Required; explicit, non-empty
167# allowed_apps = ["video"]                   # Required; exact, non-empty
168# allowed_services = ["transcoder"]          # Required; exact, non-empty
169
170# REMOVED in v3: [routes], [attachments], [network_groups],
171# [[services]]-as-apps, [service_routes], [auto_route], [previews].
172# Declare apps in standalone files (see ./apps.md).
173
174# =============================================================================
175# EXTERNAL ROUTES
176# =============================================================================
177[external_routes]
178# "domain.com" = "host:port"                 # Proxy to non-container services
179
180# =============================================================================
181# STANDALONE SERVICES
182# =============================================================================
183# [[services]]
184# name = "rust"
185# image = "registry.example.com:5000/rust:latest"
186# enabled = true
187# env_file = "/srv/gordon/services/rust.env"
188#
189# [[services.ports]]
190# name = "game"
191# container = 28015
192# protocol = "udp"
193# publish = "127.0.0.1:38015"
194#
195# [[services.ports]]
196# name = "rcon"
197# container = 28016
198# protocol = "tcp"
199# publish = "127.0.0.1:38016"
200# trusted_cidrs = ["100.64.0.0/10"]
201
202# =============================================================================
203# BACKUPS
204# =============================================================================
205[backups]
206enabled = false                              # Enable backup service
207schedule = "daily"                          # "hourly", "daily", "weekly", "monthly"
208storage_dir = ""                            # Backup root (default: {data_dir}/backups)
209
210[backups.retention]
211hourly = 0                                   # Keep N hourly backups per DB
212daily = 0                                    # Keep N daily backups per DB
213weekly = 0                                   # Keep N weekly backups per DB
214monthly = 0                                  # Keep N monthly backups per DB
215
216# =============================================================================
217# IMAGES
218# =============================================================================
219[images]
220# Defaults: docker.io/registry-1.docker.io, ghcr.io, quay.io, Gordon registry.
221# Add private or other registries as exact hostname+port entries.
222allowed_registries = []
223require_digest = false
224
225[images.prune]
226enabled = false                              # Enable scheduled image cleanup
227schedule = "daily"                          # "hourly", "daily", "weekly", "monthly"
228keep_last = 3                                # Keep N newest tags per repository
229
230# Note: retention values set to 0 keep no backups for that tier.
231# For practical defaults, consider setting daily = 7.
232```
233
234## Default Values Summary
235
236| Setting | Default | Description |
237|---------|---------|-------------|
238| `server.registry_port` | `5000` | Container registry port |
239| `server.tls_cert_file` | `""` | PEM cert path for static TLS (optional) |
240| `server.tls_key_file` | `""` | PEM key path for static TLS (optional) |
241| `server.force_https_redirect` | `false` | Redirect all HTTP to HTTPS (for direct-access setups) |
242| `server.gordon_domain` | `""` | **Required** - Gordon domain |
243| `server.data_dir` | `~/.gordon` | Data directory |
244| `server.max_blob_chunk_size` | `"95MB"` | Max size per registry blob upload chunk |
245| `server.max_blob_size` | `"1GB"` | Max cumulative size per registry blob/layer upload |
246| `server.registry_allowed_ips` | `[]` | IPs or CIDR ranges allowed to access the registry (empty = allow all) |
247| `server.proxy_allowed_ips` | `[]` | IPs or CIDR ranges allowed to reach the proxy (empty = allow all) |
248| `server.registry_listen_address` | `""` | Bind address for registry (empty = all interfaces) |
249| `entrypoints.<name>.address` | none | Deployment-selected listen address; `edge` is conventional for route-capable entrypoints but is not required when exactly one `smart_tcp` or `tls_mux` entrypoint exists |
250| `entrypoints.<name>.protocol` | none | Entrypoint protocol: `smart_tcp`, `tls_mux`, `tcp`, or `udp` |
251| `entrypoints.<name>.trusted_cidrs` | `[]` | Peer socket IP allowlist for all traffic on the entrypoint |
252| `entrypoints.<name>.raw_fallback` | `""` | TCP router used by smart TCP for unknown non-HTTP/non-TLS bytes |
253| `entrypoints.<name>.raw_fallback_trusted_cidrs` | `[]` | Peer socket IP allowlist for smart TCP raw fallback |
254| `entrypoints.<name>.allow_public_raw_fallback` | `false` | Explicit acknowledgement for public raw fallback exposure |
255| `dns.resolvers` | `["1.1.1.1:53", "8.8.8.8:53"]` | Recursive resolvers used for public DNS visibility checks, including ACME DNS-01 propagation |
256| `dns.propagation_timeout` | `"5m"` | Maximum time to wait for DNS-01 TXT records to become visible through configured recursive resolvers |
257| `dns.polling_interval` | `"5s"` | Interval between DNS-01 propagation checks |
258| `tls.acme.enabled` | `false` | Enable public ACME certificates (requires HTTPS fallback on a TLS-capable entrypoint) |
259| `tls.acme.email` | `""` | ACME account email when enabled |
260| `tls.acme.challenge` | `"auto"` | ACME challenge mode: `auto`, `http-01`, or `cloudflare-dns-01` |
261| `tls.acme.obtain_batch_size` | `1` | Maximum new ACME certificate orders per reconcile run |
262| `auth.enabled` | `true` | Enable authentication; when `false`, run local-only mode (loopback-only `/v2/*`, TCP `/admin/*` not registered, owner-only admin socket for local `gordon apps`) |
263| `auth.secrets_backend` | `"unsafe"` | Secrets storage |
264| `auth.token_expiry` | `"30d"` | 30 days |
265| `auth.access_token_ttl` | `"15m"` | Ephemeral access token lifetime |
266| `api.rate_limit.enabled` | `true` | Enable rate limiting |
267| `api.rate_limit.global_rps` | `500` | Global requests/second |
268| `api.rate_limit.per_ip_rps` | `50` | Per-IP requests/second |
269| `api.rate_limit.burst` | `100` | Burst size |
270| `api.rate_limit.trusted_proxies` | `[]` | IPs/CIDRs trusted for X-Forwarded-For |
271| `logging.level` | `"info"` | Log level |
272| `logging.format` | `"console"` | Log format |
273| `logging.file.enabled` | `false` | File logging disabled |
274| `logging.file.max_size` | `100` | 100 MB |
275| `logging.file.max_backups` | `3` | Keep 3 old files |
276| `logging.file.max_age` | `28` | 28 days |
277| `logging.access_log.enabled` | `false` | Dedicated HTTP access log disabled |
278| `logging.access_log.format` | `"json"` | Access log format (`json`, `clf`, `combined`) |
279| `logging.access_log.output` | `"stdout"` | Access log sink (`stdout`, `file`, `journald`) |
280| `logging.access_log.max_size` | `100` | 100 MB for file output |
281| `logging.access_log.max_backups` | `3` | Keep 3 old files for file output |
282| `logging.access_log.max_age` | `28` | 28 days for file output |
283| `logging.access_log.exclude_health_checks` | `true` | Skip health-check requests |
284| `logging.access_log.syslog_identifier` | `"gordon-access"` | Journald identifier |
285| `telemetry.enabled` | `false` | Enable OTLP telemetry export |
286| `telemetry.endpoint` | `""` | OTLP HTTP endpoint URL |
287| `telemetry.auth_token` | `""` | Base64 `user:password` for Basic auth |
288| `telemetry.traces` | `true` | Export distributed traces |
289| `telemetry.metrics` | `true` | Export metrics |
290| `telemetry.logs` | `true` | Bridge zerolog to OTLP logs |
291| `telemetry.trace_sample_rate` | `1.0` | Fraction of traces to sample (0.0–1.0) |
292| `containers.security_profile` | `"compat"` | Runtime hardening profile: `compat` preserves existing behavior, `strict` enables read-only rootfs and narrower capabilities |
293| `network_isolation.enabled` | `true` | Network isolation enabled |
294| `network_isolation.network_prefix` | `"gordon"` | Network prefix |
295| `network_isolation.internal` | `false` | Create Docker internal networks without direct external egress |
296| `volumes.auto_create` | `true` | Auto-create volumes |
297| `volumes.prefix` | `"gordon"` | Volume prefix |
298| `volumes.preserve` | `true` | Keep volumes |
299| `app_mounts.<name>.source` | none | Required host source of a named administrative bind; absolute and normalized. The only host path that mount may come from |
300| `app_mounts.<name>.allowed_apps` | none | Required exact, non-empty app allowlist for this mount (no wildcard or empty-means-all form) |
301| `app_mounts.<name>.allowed_services` | none | Required exact, non-empty service allowlist for this mount |
302| `app_mounts.<name>.read_only` | `false` | Force every bind resolved under this policy read-only; a manifest bind can never weaken it |
303| `app_mounts.<name>.root` | parent of `source` | Optional administrative boundary the resolved source must stay under |
304| `app_devices.<name>.cdi` | none | Required explicit, non-empty CDI device IDs granted under this logical name (no `=all` aggregate form) |
305| `app_devices.<name>.allowed_apps` | none | Required exact, non-empty app allowlist for this grant (no wildcard or empty-means-all form) |
306| `app_devices.<name>.allowed_services` | none | Required exact, non-empty service allowlist for this grant |
307| `services[].name` | none | Standalone service name used by `service:<service>:<port-name>` traffic refs |
308| `services[].image` | none | Container image for enabled standalone services |
309| `services[].enabled` | `false` | Whether Gordon creates, starts, and reconciles the service container |
310| `services[].env` | `[]` | Inline `KEY=value` environment entries |
311| `services[].env_file` | `""` | Env file loaded before inline entries |
312| `services[].ports[].name` | none | Port name used by traffic service refs |
313| `services[].ports[].container` | none | Container port number |
314| `services[].ports[].protocol` | none | `tcp` or `udp` |
315| `services[].ports[].publish` | `""` | Host-side bind address, usually loopback, that the traffic manager dials |
316| `services[].ports[].private` | `false` | Require matching service and entrypoint `trusted_cidrs` for this port |
317| `services[].ports[].public` | `false` | Explicit public opt-out for admin port names such as `rcon` |
318| `services[].ports[].trusted_cidrs` | `[]` | CIDRs allowed for private port routing; must match the target entrypoint |
319| `services[].volumes[].source` | `""` | Explicit named volume or bind source; omitted service volumes use image `VOLUME` metadata |
320| `services[].volumes[].target` | none | Absolute container mount path |
321| `services[].volumes[].read_only` | `false` | Mount explicit volume read-only |
322| `services[].readiness.type` | `"none"` | `none`, `tcp`, or `log` |
323| `services[].readiness.path` | `""` | Log readiness path inside the container |
324| `services[].readiness.contains` | `""` | Text required in the readiness log |
325| `services[].readiness.timeout` | default wait | Positive readiness timeout when set |
326| `services[].cleanup.preserve_volumes` | `true` | Preserve managed image-discovered volumes on cleanup |
327| `services[].cleanup.remove_container` | `true` | Remove old, disabled, or removed service containers |
328| `backups.enabled` | `false` | Backup service disabled |
329| `backups.schedule` | `"daily"` | Backup scheduler preset |
330| `backups.storage_dir` | `""` | Uses `{server.data_dir}/backups` when empty |
331| `backups.retention.hourly` | `0` | Keep no hourly backups by default |
332| `backups.retention.daily` | `0` | Keep no daily backups by default (recommend `7`) |
333| `backups.retention.weekly` | `0` | Keep no weekly backups by default |
334| `backups.retention.monthly` | `0` | Keep no monthly backups by default |
335| `images.allowed_registries` | `[]` | Additional exact hostname+port entries. Defaults allow Docker Hub (`docker.io` and `registry-1.docker.io`), `ghcr.io`, `quay.io`, and Gordon's registry. This allowlist does not configure registry credentials and is not DNS/IP or runtime egress enforcement. |
336| `images.require_digest` | `false` | Require valid SHA-256 digest-pinned references for every registry, including Gordon |
337| `images.prune.enabled` | `false` | Scheduled image cleanup disabled |
338| `images.prune.schedule` | `"daily"` | Cleanup schedule preset |
339| `images.prune.keep_last` | `3` | Number of recent tags kept per repository |
340
341Note: for all `backups.retention.*` keys, `0` means keep no backups for that retention tier.
342
343## App Manifest HTTP Interfaces
344
345`[[service.http]]` declares HTTP interfaces in a standalone app manifest (see [App Manifest](./apps.md)).
346
347| Key | Values | Default | Description |
348|-----|--------|---------|-------------|
349| `service.http[].visibility` | `"public"`, `"internal"` | `"public"` | `public` is proxied by host and may terminate TLS; `internal` is reachable only from the app's private network |
350| `service.http[].host` | hostname | none | Required for public interfaces; must be absent for `visibility = "internal"` |
351| `service.http[].port` | integer | none | Required container port for every interface |
352| `service.http[].tls` | `"auto"`, `"always"`, `"never"` | `"auto"` | Public interfaces only; `visibility = "internal"` rejects any declared value |
353
354`visibility = "internal"` creates no proxy route, host reservation, certificate target, or host port publication. A container port declared by both an internal HTTP interface and an externally backed interface (public HTTP or TCP) is rejected, as are duplicate internal HTTP ports.
355
356## Environment Variables
357
358All configuration options can be set via environment variables using the pattern:
359
360```
361GORDON_<SECTION>_<KEY>=value
362```
363
364Examples:
365```bash
366GORDON_SERVER_GORDON_DOMAIN=gordon.example.com
367GORDON_AUTH_ENABLED=true
368GORDON_LOGGING_LEVEL=debug
369GORDON_NETWORK_ISOLATION_ENABLED=true
370```
371
372Nested keys use underscores:
373```bash
374GORDON_LOGGING_FILE_ENABLED=true
375GORDON_LOGGING_FILE_MAX_SIZE=200
376GORDON_LOGGING_CONTAINER_LOGS_ENABLED=false
377```
378
379### Security Environment Variables
380
381These special environment variables take priority over config file values:
382
383| Variable | Description |
384|----------|-------------|
385| `GORDON_AUTH_TOKEN_SECRET` | JWT signing secret (avoids storing secret on disk) |
386
387Example:
388```bash
389export GORDON_AUTH_TOKEN_SECRET="your-secure-32-char-secret-here"
390gordon serve
391```
392
393## Pull Policy Options
394
395| Value | Behavior |
396|-------|----------|
397| `"always"` | Always pull image before deploying |
398| `"if-tag-changed"` | Pull only if image tag differs from running container |
399| `"never"` | Never pull, use local image only |
400
401## Secrets Backend Options
402
403| Value | Description |
404|-------|-------------|
405| `"pass"` | Unix password manager (recommended for production) |
406| `"sops"` | Mozilla SOPS encrypted files |
407| `"unsafe"` | Plain text files (development only) |
408
409## Log Level Options
410
411| Value | Description |
412|-------|-------------|
413| `"debug"` | Verbose debugging information |
414| `"info"` | General operational information |
415| `"warn"` | Warning conditions |
416| `"error"` | Error conditions only |
417
418## Related
419
420- [Configuration Overview](./index.md)
421- [Authentication](./auth.md)
422- [Telemetry](./telemetry.md)
423- [Network Isolation](./network-isolation.md)
424- [Volumes](./volumes.md)
425- [App Manifest](./apps.md)
426- [Standalone Services](./services.md)
427- [Images](./images.md)

reference.md RawHistoryFolder