docs: add complete configuration reference with all defaults

New docs/config/reference.md containing:
- Full annotated TOML example with all options
- Default values summary table
- Environment variable patterns
- Option value explanations (pull policy, auth type, secrets backend, log levels)

Also linked from docs/config/index.md.

commit: 3ca626262ac06500281e9f443ba3f531a20a78b2
author: brice · 9mo ago · 2026-01-17 15:47 UTC
parent: 3cd0f9c
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

2 files · +205 -0

M docs/config/index.md +2 -0


@@ -23,6 +23,8 @@ gordon_domain = "gordon.mydomain.com"
23	23
24	24		## Full Configuration Reference
25	25
	26	+	For a complete list of all configuration options with their default values, see the [Configuration Reference](./reference.md).
	27	+
26	28		> Note: This example shows production-style paths. Default paths use `~/.gordon/` for user installations.
27	29
28	30		```toml


@@ -23,6 +23,8 @@ gordon_domain = "gordon.mydomain.com"
23		23
24	## Full Configuration Reference	24		## Full Configuration Reference
25		25
		26	+	For a complete list of all configuration options with their default values, see the [Configuration Reference](./reference.md).
		27	+
26	> Note: This example shows production-style paths. Default paths use `~/.gordon/` for user installations.	28		> Note: This example shows production-style paths. Default paths use `~/.gordon/` for user installations.
27		29
28	```toml	30		```toml

A docs/config/reference.md +203 -0

@@ -0,0 +1,203 @@
	1	+	# Configuration Reference
	2	+
	3	+	Complete configuration reference with all options and their default values.
	4	+
	5	+	## Full Configuration Example
	6	+
	7	+	```toml
	8	+	# =============================================================================
	9	+	# SERVER
	10	+	# =============================================================================
	11	+	[server]
	12	+	port = 80 # HTTP proxy port
	13	+	registry_port = 5000 # Container registry port
	14	+	gordon_domain = "" # Required: Gordon domain (registry + API)
	15	+	data_dir = "~/.gordon" # Data directory (varies by install type)
	16	+
	17	+	# =============================================================================
	18	+	# AUTHENTICATION
	19	+	# =============================================================================
	20	+	[auth]
	21	+	enabled = true # Enable registry authentication
	22	+	type = "password" # "password" or "token"
	23	+	secrets_backend = "unsafe" # "pass", "sops", or "unsafe"
	24	+	username = "" # Username for password auth
	25	+	password_hash = "" # Path in secrets backend to bcrypt hash
	26	+	token_secret = "" # Path in secrets backend to JWT signing key
	27	+	token_expiry = "720h" # Token expiry duration (720h = 30 days)
	28	+
	29	+	# =============================================================================
	30	+	# LOGGING
	31	+	# =============================================================================
	32	+	[logging]
	33	+	level = "info" # "debug", "info", "warn", "error"
	34	+	format = "console" # "console" or "json"
	35	+
	36	+	[logging.file]
	37	+	enabled = false # Enable file logging
	38	+	path = "" # Log file path (default: {data_dir}/logs/gordon.log)
	39	+	max_size = 100 # Max size in MB before rotation
	40	+	max_backups = 3 # Number of old files to keep
	41	+	max_age = 28 # Days to keep old files
	42	+
	43	+	[logging.container_logs]
	44	+	enabled = true # Enable container log collection
	45	+	dir = "" # Log directory (default: {data_dir}/container-logs)
	46	+	max_size = 100 # Max size in MB before rotation
	47	+	max_backups = 3 # Number of old files to keep
	48	+	max_age = 28 # Days to keep old files
	49	+
	50	+	# =============================================================================
	51	+	# ENVIRONMENT
	52	+	# =============================================================================
	53	+	[env]
	54	+	dir = "" # Env files directory (default: {data_dir}/env)
	55	+
	56	+	# =============================================================================
	57	+	# DEPLOYMENT
	58	+	# =============================================================================
	59	+	[deploy]
	60	+	pull_policy = "if-tag-changed" # "always", "if-tag-changed", "never"
	61	+
	62	+	# =============================================================================
	63	+	# AUTO-ROUTE
	64	+	# =============================================================================
	65	+	[auto_route]
	66	+	enabled = false # Create routes from image labels automatically
	67	+
	68	+	# =============================================================================
	69	+	# NETWORK ISOLATION
	70	+	# =============================================================================
	71	+	[network_isolation]
	72	+	enabled = false # Enable per-app Docker networks
	73	+	network_prefix = "gordon" # Prefix for created networks
	74	+	dns_suffix = ".internal" # DNS suffix for internal resolution
	75	+
	76	+	# =============================================================================
	77	+	# VOLUMES
	78	+	# =============================================================================
	79	+	[volumes]
	80	+	auto_create = true # Auto-create volumes from Dockerfile VOLUME
	81	+	prefix = "gordon" # Volume name prefix
	82	+	preserve = true # Keep volumes when containers are removed
	83	+
	84	+	# =============================================================================
	85	+	# ROUTES
	86	+	# =============================================================================
	87	+	[routes]
	88	+	# "domain.com" = "image:tag"
	89	+	# "http://insecure.domain.com" = "image:tag" # HTTP-only (no HTTPS redirect)
	90	+
	91	+	# =============================================================================
	92	+	# EXTERNAL ROUTES
	93	+	# =============================================================================
	94	+	[external_routes]
	95	+	# "domain.com" = "host:port" # Proxy to non-container services
	96	+
	97	+	# =============================================================================
	98	+	# NETWORK GROUPS
	99	+	# =============================================================================
	100	+	[network_groups]
	101	+	# "group-name" = ["domain1.com", "domain2.com"]
	102	+
	103	+	# =============================================================================
	104	+	# ATTACHMENTS
	105	+	# =============================================================================
	106	+	[attachments]
	107	+	# "domain-or-group" = ["image1:tag", "image2:tag"]
	108	+	```
	109	+
	110	+	## Default Values Summary
	111	+
	112	+	\| Setting \| Default \| Description \|
	113	+	\|---------\|---------\|-------------\|
	114	+	\| `server.port` \| `80` \| HTTP proxy port \|
	115	+	\| `server.registry_port` \| `5000` \| Container registry port \|
	116	+	\| `server.gordon_domain` \| `""` \| Required - Gordon domain \|
	117	+	\| `server.data_dir` \| `~/.gordon` \| Data directory \|
	118	+	\| `auth.enabled` \| `true` \| Enable authentication \|
	119	+	\| `auth.type` \| `"password"` \| Auth type \|
	120	+	\| `auth.secrets_backend` \| `"unsafe"` \| Secrets storage \|
	121	+	\| `auth.token_expiry` \| `"720h"` \| 30 days \|
	122	+	\| `logging.level` \| `"info"` \| Log level \|
	123	+	\| `logging.format` \| `"console"` \| Log format \|
	124	+	\| `logging.file.enabled` \| `false` \| File logging disabled \|
	125	+	\| `logging.file.max_size` \| `100` \| 100 MB \|
	126	+	\| `logging.file.max_backups` \| `3` \| Keep 3 old files \|
	127	+	\| `logging.file.max_age` \| `28` \| 28 days \|
	128	+	\| `logging.container_logs.enabled` \| `true` \| Container logs enabled \|
	129	+	\| `logging.container_logs.max_size` \| `100` \| 100 MB \|
	130	+	\| `logging.container_logs.max_backups` \| `3` \| Keep 3 old files \|
	131	+	\| `logging.container_logs.max_age` \| `28` \| 28 days \|
	132	+	\| `deploy.pull_policy` \| `"if-tag-changed"` \| Pull on tag change \|
	133	+	\| `auto_route.enabled` \| `false` \| Auto-route disabled \|
	134	+	\| `network_isolation.enabled` \| `false` \| Isolation disabled \|
	135	+	\| `network_isolation.network_prefix` \| `"gordon"` \| Network prefix \|
	136	+	\| `network_isolation.dns_suffix` \| `".internal"` \| DNS suffix \|
	137	+	\| `volumes.auto_create` \| `true` \| Auto-create volumes \|
	138	+	\| `volumes.prefix` \| `"gordon"` \| Volume prefix \|
	139	+	\| `volumes.preserve` \| `true` \| Keep volumes \|
	140	+
	141	+	## Environment Variables
	142	+
	143	+	All configuration options can be set via environment variables using the pattern:
	144	+
	145	+	```
	146	+	GORDON_<SECTION>_<KEY>=value
	147	+	```
	148	+
	149	+	Examples:
	150	+	```bash
	151	+	GORDON_SERVER_PORT=8080
	152	+	GORDON_SERVER_GORDON_DOMAIN=gordon.example.com
	153	+	GORDON_AUTH_ENABLED=true
	154	+	GORDON_AUTH_TYPE=token
	155	+	GORDON_LOGGING_LEVEL=debug
	156	+	GORDON_NETWORK_ISOLATION_ENABLED=true
	157	+	```
	158	+
	159	+	Nested keys use underscores:
	160	+	```bash
	161	+	GORDON_LOGGING_FILE_ENABLED=true
	162	+	GORDON_LOGGING_FILE_MAX_SIZE=200
	163	+	GORDON_LOGGING_CONTAINER_LOGS_ENABLED=false
	164	+	```
	165	+
	166	+	## Pull Policy Options
	167	+
	168	+	\| Value \| Behavior \|
	169	+	\|-------\|----------\|
	170	+	\| `"always"` \| Always pull image before deploying \|
	171	+	\| `"if-tag-changed"` \| Pull only if image tag differs from running container \|
	172	+	\| `"never"` \| Never pull, use local image only \|
	173	+
	174	+	## Auth Type Options
	175	+
	176	+	\| Value \| Description \|
	177	+	\|-------\|-------------\|
	178	+	\| `"password"` \| HTTP Basic authentication with username/password \|
	179	+	\| `"token"` \| JWT token authentication \|
	180	+
	181	+	## Secrets Backend Options
	182	+
	183	+	\| Value \| Description \|
	184	+	\|-------\|-------------\|
	185	+	\| `"pass"` \| Unix password manager (recommended for production) \|
	186	+	\| `"sops"` \| Mozilla SOPS encrypted files \|
	187	+	\| `"unsafe"` \| Plain text files (development only) \|
	188	+
	189	+	## Log Level Options
	190	+
	191	+	\| Value \| Description \|
	192	+	\|-------\|-------------\|
	193	+	\| `"debug"` \| Verbose debugging information \|
	194	+	\| `"info"` \| General operational information \|
	195	+	\| `"warn"` \| Warning conditions \|
	196	+	\| `"error"` \| Error conditions only \|
	197	+
	198	+	## Related
	199	+
	200	+	- [Configuration Overview](./index.md)
	201	+	- [Authentication](./auth.md)
	202	+	- [Network Isolation](./network-isolation.md)
	203	+	- [Volumes](./volumes.md)

@@ -0,0 +1,203 @@
	1	+	# Configuration Reference
	2	+
	3	+	Complete configuration reference with all options and their default values.
	4	+
	5	+	## Full Configuration Example
	6	+
	7	+	```toml
	8	+	# =============================================================================
	9	+	# SERVER
	10	+	# =============================================================================
	11	+	[server]
	12	+	port = 80 # HTTP proxy port
	13	+	registry_port = 5000 # Container registry port
	14	+	gordon_domain = "" # Required: Gordon domain (registry + API)
	15	+	data_dir = "~/.gordon" # Data directory (varies by install type)
	16	+
	17	+	# =============================================================================
	18	+	# AUTHENTICATION
	19	+	# =============================================================================
	20	+	[auth]
	21	+	enabled = true # Enable registry authentication
	22	+	type = "password" # "password" or "token"
	23	+	secrets_backend = "unsafe" # "pass", "sops", or "unsafe"
	24	+	username = "" # Username for password auth
	25	+	password_hash = "" # Path in secrets backend to bcrypt hash
	26	+	token_secret = "" # Path in secrets backend to JWT signing key
	27	+	token_expiry = "720h" # Token expiry duration (720h = 30 days)
	28	+
	29	+	# =============================================================================
	30	+	# LOGGING
	31	+	# =============================================================================
	32	+	[logging]
	33	+	level = "info" # "debug", "info", "warn", "error"
	34	+	format = "console" # "console" or "json"
	35	+
	36	+	[logging.file]
	37	+	enabled = false # Enable file logging
	38	+	path = "" # Log file path (default: {data_dir}/logs/gordon.log)
	39	+	max_size = 100 # Max size in MB before rotation
	40	+	max_backups = 3 # Number of old files to keep
	41	+	max_age = 28 # Days to keep old files
	42	+
	43	+	[logging.container_logs]
	44	+	enabled = true # Enable container log collection
	45	+	dir = "" # Log directory (default: {data_dir}/container-logs)
	46	+	max_size = 100 # Max size in MB before rotation
	47	+	max_backups = 3 # Number of old files to keep
	48	+	max_age = 28 # Days to keep old files
	49	+
	50	+	# =============================================================================
	51	+	# ENVIRONMENT
	52	+	# =============================================================================
	53	+	[env]
	54	+	dir = "" # Env files directory (default: {data_dir}/env)
	55	+
	56	+	# =============================================================================
	57	+	# DEPLOYMENT
	58	+	# =============================================================================
	59	+	[deploy]
	60	+	pull_policy = "if-tag-changed" # "always", "if-tag-changed", "never"
	61	+
	62	+	# =============================================================================
	63	+	# AUTO-ROUTE
	64	+	# =============================================================================
	65	+	[auto_route]
	66	+	enabled = false # Create routes from image labels automatically
	67	+
	68	+	# =============================================================================
	69	+	# NETWORK ISOLATION
	70	+	# =============================================================================
	71	+	[network_isolation]
	72	+	enabled = false # Enable per-app Docker networks
	73	+	network_prefix = "gordon" # Prefix for created networks
	74	+	dns_suffix = ".internal" # DNS suffix for internal resolution
	75	+
	76	+	# =============================================================================
	77	+	# VOLUMES
	78	+	# =============================================================================
	79	+	[volumes]
	80	+	auto_create = true # Auto-create volumes from Dockerfile VOLUME
	81	+	prefix = "gordon" # Volume name prefix
	82	+	preserve = true # Keep volumes when containers are removed
	83	+
	84	+	# =============================================================================
	85	+	# ROUTES
	86	+	# =============================================================================
	87	+	[routes]
	88	+	# "domain.com" = "image:tag"
	89	+	# "http://insecure.domain.com" = "image:tag" # HTTP-only (no HTTPS redirect)
	90	+
	91	+	# =============================================================================
	92	+	# EXTERNAL ROUTES
	93	+	# =============================================================================
	94	+	[external_routes]
	95	+	# "domain.com" = "host:port" # Proxy to non-container services
	96	+
	97	+	# =============================================================================
	98	+	# NETWORK GROUPS
	99	+	# =============================================================================
	100	+	[network_groups]
	101	+	# "group-name" = ["domain1.com", "domain2.com"]
	102	+
	103	+	# =============================================================================
	104	+	# ATTACHMENTS
	105	+	# =============================================================================
	106	+	[attachments]
	107	+	# "domain-or-group" = ["image1:tag", "image2:tag"]
	108	+	```
	109	+
	110	+	## Default Values Summary
	111	+
	112	+	\| Setting \| Default \| Description \|
	113	+	\|---------\|---------\|-------------\|
	114	+	\| `server.port` \| `80` \| HTTP proxy port \|
	115	+	\| `server.registry_port` \| `5000` \| Container registry port \|
	116	+	\| `server.gordon_domain` \| `""` \| Required - Gordon domain \|
	117	+	\| `server.data_dir` \| `~/.gordon` \| Data directory \|
	118	+	\| `auth.enabled` \| `true` \| Enable authentication \|
	119	+	\| `auth.type` \| `"password"` \| Auth type \|
	120	+	\| `auth.secrets_backend` \| `"unsafe"` \| Secrets storage \|
	121	+	\| `auth.token_expiry` \| `"720h"` \| 30 days \|
	122	+	\| `logging.level` \| `"info"` \| Log level \|
	123	+	\| `logging.format` \| `"console"` \| Log format \|
	124	+	\| `logging.file.enabled` \| `false` \| File logging disabled \|
	125	+	\| `logging.file.max_size` \| `100` \| 100 MB \|
	126	+	\| `logging.file.max_backups` \| `3` \| Keep 3 old files \|
	127	+	\| `logging.file.max_age` \| `28` \| 28 days \|
	128	+	\| `logging.container_logs.enabled` \| `true` \| Container logs enabled \|
	129	+	\| `logging.container_logs.max_size` \| `100` \| 100 MB \|
	130	+	\| `logging.container_logs.max_backups` \| `3` \| Keep 3 old files \|
	131	+	\| `logging.container_logs.max_age` \| `28` \| 28 days \|
	132	+	\| `deploy.pull_policy` \| `"if-tag-changed"` \| Pull on tag change \|
	133	+	\| `auto_route.enabled` \| `false` \| Auto-route disabled \|
	134	+	\| `network_isolation.enabled` \| `false` \| Isolation disabled \|
	135	+	\| `network_isolation.network_prefix` \| `"gordon"` \| Network prefix \|
	136	+	\| `network_isolation.dns_suffix` \| `".internal"` \| DNS suffix \|
	137	+	\| `volumes.auto_create` \| `true` \| Auto-create volumes \|
	138	+	\| `volumes.prefix` \| `"gordon"` \| Volume prefix \|
	139	+	\| `volumes.preserve` \| `true` \| Keep volumes \|
	140	+
	141	+	## Environment Variables
	142	+
	143	+	All configuration options can be set via environment variables using the pattern:
	144	+
	145	+	```
	146	+	GORDON_<SECTION>_<KEY>=value
	147	+	```
	148	+
	149	+	Examples:
	150	+	```bash
	151	+	GORDON_SERVER_PORT=8080
	152	+	GORDON_SERVER_GORDON_DOMAIN=gordon.example.com
	153	+	GORDON_AUTH_ENABLED=true
	154	+	GORDON_AUTH_TYPE=token
	155	+	GORDON_LOGGING_LEVEL=debug
	156	+	GORDON_NETWORK_ISOLATION_ENABLED=true
	157	+	```
	158	+
	159	+	Nested keys use underscores:
	160	+	```bash
	161	+	GORDON_LOGGING_FILE_ENABLED=true
	162	+	GORDON_LOGGING_FILE_MAX_SIZE=200
	163	+	GORDON_LOGGING_CONTAINER_LOGS_ENABLED=false
	164	+	```
	165	+
	166	+	## Pull Policy Options
	167	+
	168	+	\| Value \| Behavior \|
	169	+	\|-------\|----------\|
	170	+	\| `"always"` \| Always pull image before deploying \|
	171	+	\| `"if-tag-changed"` \| Pull only if image tag differs from running container \|
	172	+	\| `"never"` \| Never pull, use local image only \|
	173	+
	174	+	## Auth Type Options
	175	+
	176	+	\| Value \| Description \|
	177	+	\|-------\|-------------\|
	178	+	\| `"password"` \| HTTP Basic authentication with username/password \|
	179	+	\| `"token"` \| JWT token authentication \|
	180	+
	181	+	## Secrets Backend Options
	182	+
	183	+	\| Value \| Description \|
	184	+	\|-------\|-------------\|
	185	+	\| `"pass"` \| Unix password manager (recommended for production) \|
	186	+	\| `"sops"` \| Mozilla SOPS encrypted files \|
	187	+	\| `"unsafe"` \| Plain text files (development only) \|
	188	+
	189	+	## Log Level Options
	190	+
	191	+	\| Value \| Description \|
	192	+	\|-------\|-------------\|
	193	+	\| `"debug"` \| Verbose debugging information \|
	194	+	\| `"info"` \| General operational information \|
	195	+	\| `"warn"` \| Warning conditions \|
	196	+	\| `"error"` \| Error conditions only \|
	197	+
	198	+	## Related
	199	+
	200	+	- [Configuration Overview](./index.md)
	201	+	- [Authentication](./auth.md)
	202	+	- [Network Isolation](./network-isolation.md)
	203	+	- [Volumes](./volumes.md)