2a95454 docs: update configuration examples with new authentication options · gordon

M README.md +71 -2


@@ -139,9 +139,21 @@ Gordon uses a single TOML file for all configuration:
139	139		[server]
140	140		registry_domain = "registry.mydomain.com" # Required
141	141
	142	+	# Secrets backend for sensitive data (tokens, passwords)
	143	+	[secrets]
	144	+	backend = "pass" # "pass", "sops", or "unsafe" (plain text in data_dir)
	145	+
	146	+	# Registry authentication (choose password or token type)
142	147		[registry_auth]
143		-	username = "admin" # Choose your credentials
144		-	password = "your-secure-password"
	148	+	enabled = true
	149	+	type = "password" # "password" or "token"
	150	+
	151	+	# Password auth: bcrypt hash stored in secrets backend
	152	+	username = "deploy"
	153	+	password_hash = "gordon/registry/password_hash" # path in secrets backend
	154	+
	155	+	# Token auth: JWT-based authentication
	156	+	# token_secret = "gordon/registry/token_secret" # path in secrets backend
145	157
146	158		[routes]
147	159		"app.mydomain.com" = "myapp:latest" # Domain → Image mapping

@@ -155,6 +167,63 @@ password = "your-secure-password"
155	167
156	168		See [examples/](examples/) for advanced configurations including network groups and more.
157	169
	170	+	### Authentication Types
	171	+
	172	+	Password Authentication (simple):
	173	+	```bash
	174	+	# Generate a bcrypt hash for your password
	175	+	gordon auth password hash
	176	+	# Store the hash in your secrets backend, then reference it in config
	177	+	```
	178	+
	179	+	Token Authentication (recommended for CI/CD):
	180	+	```bash
	181	+	# Generate a never-expiring token for CI
	182	+	gordon auth token generate --subject ci-bot --scopes push,pull --expiry 0
	183	+
	184	+	# List all tokens
	185	+	gordon auth token list
	186	+
	187	+	# Revoke a compromised token
	188	+	gordon auth token revoke <token-id>
	189	+	```
	190	+
	191	+	Tokens are stored in your configured secrets backend and are unique to each Gordon instance (different `token_secret` = incompatible tokens).
	192	+
	193	+	### GitHub Actions Integration
	194	+
	195	+	Gordon provides an official GitHub Action for automated deployments on tag push:
	196	+
	197	+	```yaml
	198	+	# .github/workflows/deploy.yml
	199	+	name: Deploy to Gordon
	200	+
	201	+	on:
	202	+	push:
	203	+	tags:
	204	+	- 'v*'
	205	+
	206	+	jobs:
	207	+	deploy:
	208	+	runs-on: ubuntu-latest
	209	+	steps:
	210	+	- uses: actions/checkout@v6
	211	+
	212	+	- name: Deploy to Gordon
	213	+	uses: bnema/gordon/.github/actions/deploy@main
	214	+	with:
	215	+	registry: ${{ secrets.GORDON_REGISTRY }}
	216	+	username: ${{ secrets.GORDON_USERNAME }}
	217	+	password: ${{ secrets.GORDON_TOKEN }}
	218	+	```
	219	+
	220	+	Setup:
	221	+	1. Generate a CI token: `gordon auth token generate --subject github-actions --scopes push,pull --expiry 0`
	222	+	2. Add secrets to your GitHub repository: `GORDON_REGISTRY`, `GORDON_USERNAME`, `GORDON_TOKEN`
	223	+	3. Push a tag to deploy: `git tag v1.0.0 && git push origin v1.0.0`
	224	+
	225	+	See [examples/github-workflow.yml](examples/github-workflow.yml) and [.github/actions/deploy/README.md](.github/actions/deploy/README.md) for advanced options.
	226	+
158	227		## Detailed Setup Guide (Podman Rootless Mode)
159	228
160	229		> Note: This guide uses Podman in rootless mode for enhanced security. Docker users can follow similar steps - Gordon works with any OCI-compatible runtime. Refer to Quick Start for the binary installation.


@@ -139,9 +139,21 @@ Gordon uses a single TOML file for all configuration:
139		[server]	139		[server]
140		registry_domain = "registry.mydomain.com" # Required	140		registry_domain = "registry.mydomain.com" # Required
141			141
			142	+	# Secrets backend for sensitive data (tokens, passwords)
			143	+	[secrets]
			144	+	backend = "pass" # "pass", "sops", or "unsafe" (plain text in data_dir)
			145	+
			146	+	# Registry authentication (choose password or token type)
142		[registry_auth]	147		[registry_auth]
143	-	username = "admin" # Choose your credentials	148	+	enabled = true
144	-	password = "your-secure-password"	149	+	type = "password" # "password" or "token"
			150	+
			151	+	# Password auth: bcrypt hash stored in secrets backend
			152	+	username = "deploy"
			153	+	password_hash = "gordon/registry/password_hash" # path in secrets backend
			154	+
			155	+	# Token auth: JWT-based authentication
			156	+	# token_secret = "gordon/registry/token_secret" # path in secrets backend
145			157
146		[routes]	158		[routes]
147		"app.mydomain.com" = "myapp:latest" # Domain → Image mapping	159		"app.mydomain.com" = "myapp:latest" # Domain → Image mapping

@@ -155,6 +167,63 @@ password = "your-secure-password"
155			167
156		See [examples/](examples/) for advanced configurations including network groups and more.	168		See [examples/](examples/) for advanced configurations including network groups and more.
157			169
			170	+	### Authentication Types
			171	+
			172	+	Password Authentication (simple):
			173	+	```bash
			174	+	# Generate a bcrypt hash for your password
			175	+	gordon auth password hash
			176	+	# Store the hash in your secrets backend, then reference it in config
			177	+	```
			178	+
			179	+	Token Authentication (recommended for CI/CD):
			180	+	```bash
			181	+	# Generate a never-expiring token for CI
			182	+	gordon auth token generate --subject ci-bot --scopes push,pull --expiry 0
			183	+
			184	+	# List all tokens
			185	+	gordon auth token list
			186	+
			187	+	# Revoke a compromised token
			188	+	gordon auth token revoke <token-id>
			189	+	```
			190	+
			191	+	Tokens are stored in your configured secrets backend and are unique to each Gordon instance (different `token_secret` = incompatible tokens).
			192	+
			193	+	### GitHub Actions Integration
			194	+
			195	+	Gordon provides an official GitHub Action for automated deployments on tag push:
			196	+
			197	+	```yaml
			198	+	# .github/workflows/deploy.yml
			199	+	name: Deploy to Gordon
			200	+
			201	+	on:
			202	+	push:
			203	+	tags:
			204	+	- 'v*'
			205	+
			206	+	jobs:
			207	+	deploy:
			208	+	runs-on: ubuntu-latest
			209	+	steps:
			210	+	- uses: actions/checkout@v6
			211	+
			212	+	- name: Deploy to Gordon
			213	+	uses: bnema/gordon/.github/actions/deploy@main
			214	+	with:
			215	+	registry: ${{ secrets.GORDON_REGISTRY }}
			216	+	username: ${{ secrets.GORDON_USERNAME }}
			217	+	password: ${{ secrets.GORDON_TOKEN }}
			218	+	```
			219	+
			220	+	Setup:
			221	+	1. Generate a CI token: `gordon auth token generate --subject github-actions --scopes push,pull --expiry 0`
			222	+	2. Add secrets to your GitHub repository: `GORDON_REGISTRY`, `GORDON_USERNAME`, `GORDON_TOKEN`
			223	+	3. Push a tag to deploy: `git tag v1.0.0 && git push origin v1.0.0`
			224	+
			225	+	See [examples/github-workflow.yml](examples/github-workflow.yml) and [.github/actions/deploy/README.md](.github/actions/deploy/README.md) for advanced options.
			226	+
158		## Detailed Setup Guide (Podman Rootless Mode)	227		## Detailed Setup Guide (Podman Rootless Mode)
159			228
160		> Note: This guide uses Podman in rootless mode for enhanced security. Docker users can follow similar steps - Gordon works with any OCI-compatible runtime. Refer to Quick Start for the binary installation.	229		> Note: This guide uses Podman in rootless mode for enhanced security. Docker users can follow similar steps - Gordon works with any OCI-compatible runtime. Refer to Quick Start for the binary installation.

M examples/README.md +64 -22


@@ -20,10 +20,24 @@ data_dir = "~/.local/share/gordon" # Data directory (default: ~/.local/share/g
20	20		# Root user default: ./data
21	21		ssl_email = "" # Email for Let's Encrypt (default: "" - uses Cloudflare)
22	22
	23	+	[secrets]
	24	+	backend = "pass" # Secrets backend (default: "pass")
	25	+	# Options: pass, sops, unsafe
	26	+	# "unsafe" stores secrets in plain text (dev only)
	27	+
23	28		[registry_auth]
24	29		enabled = true # Enable registry authentication (default: true)
25		-	username = "" # REQUIRED when enabled (no default)
26		-	password = "" # REQUIRED when enabled (no default)
	30	+	type = "password" # Auth type (default: "password")
	31	+	# Options: password, token
	32	+
	33	+	# Password auth settings (when type = "password")
	34	+	username = "" # REQUIRED - username for docker login
	35	+	password_hash = "" # REQUIRED - path to bcrypt hash in secrets backend
	36	+	# Example: "gordon/registry/password_hash"
	37	+
	38	+	# Token auth settings (when type = "token")
	39	+	# token_secret = "" # REQUIRED - path to JWT signing secret
	40	+	# Example: "gordon/registry/token_secret"
27	41
28	42		[routes]
29	43		# Domain to image mappings (default: empty)

@@ -50,7 +64,7 @@ preserve = true # Keep volumes when removing containers (de
50	64
51	65		[env]
52	66		dir = "{data_dir}/env" # Environment files directory (default: {data_dir}/env)
53		-	providers = ["pass", "sops"] # Secret providers (default: ["pass", "sops"])
	67	+	# Note: Secret providers are now configured via [secrets].backend
54	68
55	69		[logging]
56	70		enabled = true # Enable file logging (default: true)

@@ -66,57 +80,64 @@ max_age = 28 # Days to keep old logs (default: 28)
66	80		compress = true # Compress rotated logs (default: true)
67	81		```
68	82
69		-	## 📁 Available Examples
	83	+	## Available Examples
70	84
71		-	### 🚀 [`minimal.toml`](minimal.toml)
	85	+	### [`minimal.toml`](minimal.toml)
72	86		Perfect for getting started
73	87		- Single route configuration
74	88		- Default settings
75	89		- No authentication
76	90		- Ideal for testing and learning
77	91
78		-	### 🏠 [`development.toml`](development.toml)
	92	+	### [`development.toml`](development.toml)
79	93		Local development setup
80	94		- Multiple .local domains
81	95		- No authentication for ease of use
82	96		- Third-party development tools
83	97		- localhost registry
84	98
85		-	### 🧪 [`staging.toml`](staging.toml)
	99	+	### [`staging.toml`](staging.toml)
86	100		Staging and preview environments
87	101		- Branch-based deployments
88	102		- Feature branch testing
89	103		- PR preview environments
90	104		- Separate staging registry
91	105
92		-	### 🏭 [`production.toml`](production.toml)
	106	+	### [`production.toml`](production.toml)
93	107		Production-ready configuration
94	108		- Pinned image versions
95	109		- Registry authentication
96	110		- Multiple production services
97	111		- Monitoring tools included
98	112
99		-	### 🏢 [`saas-multi-tenant.toml`](saas-multi-tenant.toml)
	113	+	### [`saas-multi-tenant.toml`](saas-multi-tenant.toml)
100	114		Multi-tenant SaaS platform
101	115		- Customer subdomains
102	116		- Custom domains
103	117		- Shared application architecture
104	118		- Enterprise features
105	119
106		-	### 📊 [`logging.toml`](logging.toml)
	120	+	### [`logging.toml`](logging.toml)
107	121		Comprehensive logging configuration
108	122		- Complete logging setup examples
109	123		- Different logging levels and configurations
110	124		- Production and development logging strategies
111	125		- Log rotation and monitoring examples
112	126
113		-	### 🔄 [`rollback-workflow-example.md`](rollback-workflow-example.md)
	127	+	### [`rollback-workflow-example.md`](rollback-workflow-example.md)
114	128		Simple version deployment and rollback workflow
115	129		- Manifest annotation-based deployments
116	130		- Simple version changes for deployments and rollbacks
117	131		- Version tracking and deployment strategies
118	132
119		-	## 🚀 Quick Start
	133	+	### [`github-workflow.yml`](github-workflow.yml)
	134	+	GitHub Actions CI/CD workflow
	135	+	- Automatic deployment on tag push
	136	+	- Uses official Gordon deploy action
	137	+	- Build arguments and multi-platform support
	138	+	- Monorepo configurations
	139	+
	140	+	## Quick Start
120	141
121	142		1. Choose an example that matches your use case
122	143		2. Copy the config file to your Gordon directory:

@@ -129,7 +150,7 @@ compress = true # Compress rotated logs (default: true)
129	150		gordon start
130	151		```
131	152
132		-	## 🔧 Customization Tips
	153	+	## Customization Tips
133	154
134	155		### Domain Configuration
135	156		Update the `[routes]` section with your actual domains:

@@ -145,10 +166,31 @@ Configure your registry domain and authentication:
145	166		[server]
146	167		registry_domain = "registry.your-domain.com"
147	168
	169	+	[secrets]
	170	+	backend = "pass" # or "sops", or "unsafe" for development
	171	+
148	172		[registry_auth]
149	173		enabled = true
150		-	username = "your-username"
151		-	password = "your-secure-password"
	174	+	type = "password" # or "token"
	175	+
	176	+	# For password auth:
	177	+	username = "deploy"
	178	+	password_hash = "gordon/registry/password_hash" # path in secrets backend
	179	+
	180	+	# For token auth (recommended for CI/CD):
	181	+	# type = "token"
	182	+	# token_secret = "gordon/registry/token_secret"
	183	+	```
	184	+
	185	+	Token Management CLI:
	186	+	```bash
	187	+	# Generate a bcrypt hash for password auth
	188	+	gordon auth password hash
	189	+
	190	+	# Generate tokens for CI/CD (token auth type)
	191	+	gordon auth token generate --subject ci-bot --scopes push,pull --expiry 0
	192	+	gordon auth token list
	193	+	gordon auth token revoke <token-id>
152	194		```
153	195
154	196		### Container Runtime Setup

@@ -308,7 +350,7 @@ When you deploy this image:
308	350		- Your data persists across deployments and reboots
309	351		- Environment variables are intelligently managed
310	352
311		-	## 🌐 DNS Configuration
	353	+	## DNS Configuration
312	354
313	355		### Cloudflare Setup (Recommended)
314	356		For all examples except development, set up these DNS records:

@@ -334,7 +376,7 @@ For the development example, add to `/etc/hosts`:
334	376		127.0.0.1 admin.local
335	377		```
336	378
337		-	## 🔄 Workflow Examples
	379	+	## Workflow Examples
338	380
339	381		### Simple Deployment
340	382		```bash

@@ -385,12 +427,12 @@ podman manifest push myapp:latest registry.your-domain.com/myapp:latest
385	427
386	428		See [`rollback-workflow-example.md`](rollback-workflow-example.md) for complete version deployment workflow documentation.
387	429
388		-	## 🤝 Need Help?
	430	+	## Need Help?
389	431
390		-	- 📖 Read the main [README](../README.md) for detailed documentation
391		-	- 🔍 Check the logs for deployment issues
392		-	- 🐛 Open an issue if you find problems with these examples
393		-	- 💡 Contribute your own configuration examples!
	432	+	- Read the main [README](../README.md) for detailed documentation
	433	+	- Check the logs for deployment issues
	434	+	- Open an issue if you find problems with these examples
	435	+	- Contribute your own configuration examples!
394	436
395	437		---
396	438		These examples are starting points - customize them for your specific needs!⏎̸


@@ -20,10 +20,24 @@ data_dir = "~/.local/share/gordon" # Data directory (default: ~/.local/share/g
20		# Root user default: ./data	20		# Root user default: ./data
21		ssl_email = "" # Email for Let's Encrypt (default: "" - uses Cloudflare)	21		ssl_email = "" # Email for Let's Encrypt (default: "" - uses Cloudflare)
22			22
			23	+	[secrets]
			24	+	backend = "pass" # Secrets backend (default: "pass")
			25	+	# Options: pass, sops, unsafe
			26	+	# "unsafe" stores secrets in plain text (dev only)
			27	+
23		[registry_auth]	28		[registry_auth]
24		enabled = true # Enable registry authentication (default: true)	29		enabled = true # Enable registry authentication (default: true)
25	-	username = "" # REQUIRED when enabled (no default)	30	+	type = "password" # Auth type (default: "password")
26	-	password = "" # REQUIRED when enabled (no default)	31	+	# Options: password, token
			32	+
			33	+	# Password auth settings (when type = "password")
			34	+	username = "" # REQUIRED - username for docker login
			35	+	password_hash = "" # REQUIRED - path to bcrypt hash in secrets backend
			36	+	# Example: "gordon/registry/password_hash"
			37	+
			38	+	# Token auth settings (when type = "token")
			39	+	# token_secret = "" # REQUIRED - path to JWT signing secret
			40	+	# Example: "gordon/registry/token_secret"
27			41
28		[routes]	42		[routes]
29		# Domain to image mappings (default: empty)	43		# Domain to image mappings (default: empty)

@@ -50,7 +64,7 @@ preserve = true # Keep volumes when removing containers (de
50			64
51		[env]	65		[env]
52		dir = "{data_dir}/env" # Environment files directory (default: {data_dir}/env)	66		dir = "{data_dir}/env" # Environment files directory (default: {data_dir}/env)
53	-	providers = ["pass", "sops"] # Secret providers (default: ["pass", "sops"])	67	+	# Note: Secret providers are now configured via [secrets].backend
54			68
55		[logging]	69		[logging]
56		enabled = true # Enable file logging (default: true)	70		enabled = true # Enable file logging (default: true)

@@ -66,57 +80,64 @@ max_age = 28 # Days to keep old logs (default: 28)
66		compress = true # Compress rotated logs (default: true)	80		compress = true # Compress rotated logs (default: true)
67		```	81		```
68			82
69	-	## 📁 Available Examples	83	+	## Available Examples
70			84
71	-	### 🚀 [`minimal.toml`](minimal.toml)	85	+	### [`minimal.toml`](minimal.toml)
72		Perfect for getting started	86		Perfect for getting started
73		- Single route configuration	87		- Single route configuration
74		- Default settings	88		- Default settings
75		- No authentication	89		- No authentication
76		- Ideal for testing and learning	90		- Ideal for testing and learning
77			91
78	-	### 🏠 [`development.toml`](development.toml)	92	+	### [`development.toml`](development.toml)
79		Local development setup	93		Local development setup
80		- Multiple .local domains	94		- Multiple .local domains
81		- No authentication for ease of use	95		- No authentication for ease of use
82		- Third-party development tools	96		- Third-party development tools
83		- localhost registry	97		- localhost registry
84			98
85	-	### 🧪 [`staging.toml`](staging.toml)	99	+	### [`staging.toml`](staging.toml)
86		Staging and preview environments	100		Staging and preview environments
87		- Branch-based deployments	101		- Branch-based deployments
88		- Feature branch testing	102		- Feature branch testing
89		- PR preview environments	103		- PR preview environments
90		- Separate staging registry	104		- Separate staging registry
91			105
92	-	### 🏭 [`production.toml`](production.toml)	106	+	### [`production.toml`](production.toml)
93		Production-ready configuration	107		Production-ready configuration
94		- Pinned image versions	108		- Pinned image versions
95		- Registry authentication	109		- Registry authentication
96		- Multiple production services	110		- Multiple production services
97		- Monitoring tools included	111		- Monitoring tools included
98			112
99	-	### 🏢 [`saas-multi-tenant.toml`](saas-multi-tenant.toml)	113	+	### [`saas-multi-tenant.toml`](saas-multi-tenant.toml)
100		Multi-tenant SaaS platform	114		Multi-tenant SaaS platform
101		- Customer subdomains	115		- Customer subdomains
102		- Custom domains	116		- Custom domains
103		- Shared application architecture	117		- Shared application architecture
104		- Enterprise features	118		- Enterprise features
105			119
106	-	### 📊 [`logging.toml`](logging.toml)	120	+	### [`logging.toml`](logging.toml)
107		Comprehensive logging configuration	121		Comprehensive logging configuration
108		- Complete logging setup examples	122		- Complete logging setup examples
109		- Different logging levels and configurations	123		- Different logging levels and configurations
110		- Production and development logging strategies	124		- Production and development logging strategies
111		- Log rotation and monitoring examples	125		- Log rotation and monitoring examples
112			126
113	-	### 🔄 [`rollback-workflow-example.md`](rollback-workflow-example.md)	127	+	### [`rollback-workflow-example.md`](rollback-workflow-example.md)
114		Simple version deployment and rollback workflow	128		Simple version deployment and rollback workflow
115		- Manifest annotation-based deployments	129		- Manifest annotation-based deployments
116		- Simple version changes for deployments and rollbacks	130		- Simple version changes for deployments and rollbacks
117		- Version tracking and deployment strategies	131		- Version tracking and deployment strategies
118			132
119	-	## 🚀 Quick Start	133	+	### [`github-workflow.yml`](github-workflow.yml)
			134	+	GitHub Actions CI/CD workflow
			135	+	- Automatic deployment on tag push
			136	+	- Uses official Gordon deploy action
			137	+	- Build arguments and multi-platform support
			138	+	- Monorepo configurations
			139	+
			140	+	## Quick Start
120			141
121		1. Choose an example that matches your use case	142		1. Choose an example that matches your use case
122		2. Copy the config file to your Gordon directory:	143		2. Copy the config file to your Gordon directory:

@@ -129,7 +150,7 @@ compress = true # Compress rotated logs (default: true)
129		gordon start	150		gordon start
130		```	151		```
131			152
132	-	## 🔧 Customization Tips	153	+	## Customization Tips
133			154
134		### Domain Configuration	155		### Domain Configuration
135		Update the `[routes]` section with your actual domains:	156		Update the `[routes]` section with your actual domains:

@@ -145,10 +166,31 @@ Configure your registry domain and authentication:
145		[server]	166		[server]
146		registry_domain = "registry.your-domain.com"	167		registry_domain = "registry.your-domain.com"
147			168
			169	+	[secrets]
			170	+	backend = "pass" # or "sops", or "unsafe" for development
			171	+
148		[registry_auth]	172		[registry_auth]
149		enabled = true	173		enabled = true
150	-	username = "your-username"	174	+	type = "password" # or "token"
151	-	password = "your-secure-password"	175	+
			176	+	# For password auth:
			177	+	username = "deploy"
			178	+	password_hash = "gordon/registry/password_hash" # path in secrets backend
			179	+
			180	+	# For token auth (recommended for CI/CD):
			181	+	# type = "token"
			182	+	# token_secret = "gordon/registry/token_secret"
			183	+	```
			184	+
			185	+	Token Management CLI:
			186	+	```bash
			187	+	# Generate a bcrypt hash for password auth
			188	+	gordon auth password hash
			189	+
			190	+	# Generate tokens for CI/CD (token auth type)
			191	+	gordon auth token generate --subject ci-bot --scopes push,pull --expiry 0
			192	+	gordon auth token list
			193	+	gordon auth token revoke <token-id>
152		```	194		```
153			195
154		### Container Runtime Setup	196		### Container Runtime Setup

@@ -308,7 +350,7 @@ When you deploy this image:
308		- Your data persists across deployments and reboots	350		- Your data persists across deployments and reboots
309		- Environment variables are intelligently managed	351		- Environment variables are intelligently managed
310			352
311	-	## 🌐 DNS Configuration	353	+	## DNS Configuration
312			354
313		### Cloudflare Setup (Recommended)	355		### Cloudflare Setup (Recommended)
314		For all examples except development, set up these DNS records:	356		For all examples except development, set up these DNS records:

@@ -334,7 +376,7 @@ For the development example, add to `/etc/hosts`:
334		127.0.0.1 admin.local	376		127.0.0.1 admin.local
335		```	377		```
336			378
337	-	## 🔄 Workflow Examples	379	+	## Workflow Examples
338			380
339		### Simple Deployment	381		### Simple Deployment
340		```bash	382		```bash

@@ -385,12 +427,12 @@ podman manifest push myapp:latest registry.your-domain.com/myapp:latest
385			427
386		See [`rollback-workflow-example.md`](rollback-workflow-example.md) for complete version deployment workflow documentation.	428		See [`rollback-workflow-example.md`](rollback-workflow-example.md) for complete version deployment workflow documentation.
387			429
388	-	## 🤝 Need Help?	430	+	## Need Help?
389			431
390	-	- 📖 Read the main [README](../README.md) for detailed documentation	432	+	- Read the main [README](../README.md) for detailed documentation
391	-	- 🔍 Check the logs for deployment issues	433	+	- Check the logs for deployment issues
392	-	- 🐛 Open an issue if you find problems with these examples	434	+	- Open an issue if you find problems with these examples
393	-	- 💡 Contribute your own configuration examples!	435	+	- Contribute your own configuration examples!
394			436
395		---	437		---
396		These examples are starting points - customize them for your specific needs!⏎̸	438		These examples are starting points - customize them for your specific needs!⏎̸

M examples/development.toml +11 -2


@@ -9,9 +9,19 @@ runtime = "auto" # auto-detects Docker/Podman
9	9		ssl_email = "dev@localhost"
10	10		data_dir = "./dev-data"
11	11
	12	+	# Secrets backend for development
	13	+	[secrets]
	14	+	backend = "unsafe" # Plain text storage for local development
	15	+
12	16		[registry_auth]
13	17		enabled = false # Disable auth for easier local development
14	18
	19	+	# To enable auth for development:
	20	+	# enabled = true
	21	+	# type = "password"
	22	+	# username = "dev"
	23	+	# password_hash = "gordon/registry/password_hash" # Generate: gordon auth password hash
	24	+
15	25		[auto_route]
16	26		enabled = true # Enable automatic route creation from image names
17	27

@@ -40,8 +50,7 @@ compress = true # Compress old logs
40	50		[env]
41	51		# Directory where .env files are stored for each route
42	52		dir = "./dev-data/env"
43		-	# Secret providers (optional for development)
44		-	providers = ["pass"] # For development secrets
	53	+	# Note: Secret providers use [secrets].backend configuration
45	54
46	55		# Development routes using your domain
47	56		[routes]

 ssl_email = "dev@localhost"
 data_dir = "./dev-data"
+# Secrets backend for development
+[secrets]
+backend = "unsafe"  # Plain text storage for local development
 [registry_auth]
 enabled = false  # Disable auth for easier local development
+# To enable auth for development:
+# enabled = true
+# type = "password"
+# username = "dev"
+# password_hash = "gordon/registry/password_hash"  # Generate: gordon auth password hash
 [auto_route]
 enabled = true  # Enable automatic route creation from image names
 [env]
 # Directory where .env files are stored for each route
 dir = "./dev-data/env"
-# Secret providers (optional for development)
+# Note: Secret providers use [secrets].backend configuration
-providers = ["pass"]  # For development secrets
 # Development routes using your domain
 [routes]

M examples/logging.toml +6 -1


@@ -8,10 +8,15 @@ registry_domain = "registry.yourdomain.com"
8	8		runtime = "auto"
9	9		data_dir = "./data"
10	10
	11	+	# Secrets backend
	12	+	[secrets]
	13	+	backend = "pass" # "pass", "sops", or "unsafe"
	14	+
11	15		[registry_auth]
12	16		enabled = true
	17	+	type = "password" # or "token"
13	18		username = "admin"
14		-	password = "secure-password"
	19	+	password_hash = "gordon/registry/password_hash" # bcrypt hash in secrets backend
15	20
16	21		# ============================================================================
17	22		# LOGGING CONFIGURATION EXAMPLES

 runtime = "auto"
 data_dir = "./data"
+# Secrets backend
+[secrets]
+backend = "pass"  # "pass", "sops", or "unsafe"
 [registry_auth]
 enabled = true
+type = "password"  # or "token"
 username = "admin"
-password = "secure-password"
+password_hash = "gordon/registry/password_hash"  # bcrypt hash in secrets backend
 # ============================================================================
 # LOGGING CONFIGURATION EXAMPLES

M examples/minimal.toml +16 -1


@@ -6,8 +6,23 @@ port = 8080
6	6		registry_port = 5000
7	7		registry_domain = "registry.local"
8	8
	9	+	# Secrets backend (optional, defaults to "pass")
	10	+	# [secrets]
	11	+	# backend = "unsafe" # Use "unsafe" for local dev without pass/sops
	12	+
9	13		[registry_auth]
10		-	enabled = false # Disabled for simplicity
	14	+	enabled = false # Disabled for local development
	15	+
	16	+	# To enable auth, choose a type:
	17	+	# enabled = true
	18	+	# type = "password" # Simple username/password
	19	+	# username = "dev"
	20	+	# password_hash = "gordon/registry/password_hash" # Generate with: gordon auth password hash
	21	+	#
	22	+	# OR for token auth (better for CI):
	23	+	# type = "token"
	24	+	# token_secret = "gordon/registry/token_secret"
	25	+	# Generate tokens with: gordon auth token generate --subject dev --expiry 0
11	26
12	27		# Optional: Enable basic logging
13	28		# [logging]


@@ -6,8 +6,23 @@ port = 8080
6		registry_port = 5000	6		registry_port = 5000
7		registry_domain = "registry.local"	7		registry_domain = "registry.local"
8			8
			9	+	# Secrets backend (optional, defaults to "pass")
			10	+	# [secrets]
			11	+	# backend = "unsafe" # Use "unsafe" for local dev without pass/sops
			12	+
9		[registry_auth]	13		[registry_auth]
10	-	enabled = false # Disabled for simplicity	14	+	enabled = false # Disabled for local development
			15	+
			16	+	# To enable auth, choose a type:
			17	+	# enabled = true
			18	+	# type = "password" # Simple username/password
			19	+	# username = "dev"
			20	+	# password_hash = "gordon/registry/password_hash" # Generate with: gordon auth password hash
			21	+	#
			22	+	# OR for token auth (better for CI):
			23	+	# type = "token"
			24	+	# token_secret = "gordon/registry/token_secret"
			25	+	# Generate tokens with: gordon auth token generate --subject dev --expiry 0
11			26
12		# Optional: Enable basic logging	27		# Optional: Enable basic logging
13		# [logging]	28		# [logging]

M examples/production.toml +19 -4


@@ -10,10 +10,26 @@ runtime = "auto" # auto-detects Docker/Podman
10	10		ssl_email = "devops@company.com"
11	11		data_dir = "/var/lib/gordon"
12	12
	13	+	# Secrets backend for sensitive data
	14	+	[secrets]
	15	+	backend = "pass" # "pass" (recommended), "sops", or "unsafe"
	16	+
13	17		[registry_auth]
14	18		enabled = true
15		-	username = "deploy-bot"
16		-	password = "CHANGE-THIS-IN-PRODUCTION" # Use environment variables in production!
	19	+	type = "token" # "token" (recommended for CI/CD) or "password"
	20	+
	21	+	# Token auth: JWT-based, ideal for CI pipelines
	22	+	token_secret = "gordon/registry/token_secret" # path in secrets backend
	23	+
	24	+	# Generate tokens with:
	25	+	# gordon auth token generate --subject deploy-bot --scopes push,pull --expiry 0
	26	+	# Each Gordon instance has unique tokens (different token_secret = incompatible tokens)
	27	+
	28	+	# Alternative: Password auth (simpler but less flexible)
	29	+	# type = "password"
	30	+	# username = "deploy-bot"
	31	+	# password_hash = "gordon/registry/password_hash" # bcrypt hash in secrets backend
	32	+	# Generate hash with: gordon auth password hash
17	33
18	34		# Production logging configuration
19	35		[logging]

@@ -34,8 +50,7 @@ compress = true # Compress old logs to save space
34	50		[env]
35	51		# Directory where .env files are stored for each route
36	52		dir = "/var/lib/gordon/env"
37		-	# Secret providers for secure credential management
38		-	providers = ["pass", "sops"]
	53	+	# Note: Secret providers now use [secrets].backend configuration
39	54
40	55		# Production service routes
41	56		[routes]


@@ -10,10 +10,26 @@ runtime = "auto" # auto-detects Docker/Podman
10		ssl_email = "devops@company.com"	10		ssl_email = "devops@company.com"
11		data_dir = "/var/lib/gordon"	11		data_dir = "/var/lib/gordon"
12			12
			13	+	# Secrets backend for sensitive data
			14	+	[secrets]
			15	+	backend = "pass" # "pass" (recommended), "sops", or "unsafe"
			16	+
13		[registry_auth]	17		[registry_auth]
14		enabled = true	18		enabled = true
15	-	username = "deploy-bot"	19	+	type = "token" # "token" (recommended for CI/CD) or "password"
16	-	password = "CHANGE-THIS-IN-PRODUCTION" # Use environment variables in production!	20	+
			21	+	# Token auth: JWT-based, ideal for CI pipelines
			22	+	token_secret = "gordon/registry/token_secret" # path in secrets backend
			23	+
			24	+	# Generate tokens with:
			25	+	# gordon auth token generate --subject deploy-bot --scopes push,pull --expiry 0
			26	+	# Each Gordon instance has unique tokens (different token_secret = incompatible tokens)
			27	+
			28	+	# Alternative: Password auth (simpler but less flexible)
			29	+	# type = "password"
			30	+	# username = "deploy-bot"
			31	+	# password_hash = "gordon/registry/password_hash" # bcrypt hash in secrets backend
			32	+	# Generate hash with: gordon auth password hash
17			33
18		# Production logging configuration	34		# Production logging configuration
19		[logging]	35		[logging]

@@ -34,8 +50,7 @@ compress = true # Compress old logs to save space
34		[env]	50		[env]
35		# Directory where .env files are stored for each route	51		# Directory where .env files are stored for each route
36		dir = "/var/lib/gordon/env"	52		dir = "/var/lib/gordon/env"
37	-	# Secret providers for secure credential management	53	+	# Note: Secret providers now use [secrets].backend configuration
38	-	providers = ["pass", "sops"]
39			54
40		# Production service routes	55		# Production service routes
41		[routes]	56		[routes]

M examples/saas-multi-tenant.toml +12 -2


@@ -9,10 +9,20 @@ runtime = "auto" # auto-detects Docker/Podman
9	9		ssl_email = "ops@saas-platform.com"
10	10		data_dir = "/var/lib/gordon"
11	11
	12	+	# Secrets backend for secure credential storage
	13	+	[secrets]
	14	+	backend = "pass" # Production should use "pass" or "sops"
	15	+
12	16		[registry_auth]
13	17		enabled = true
14		-	username = "deploy"
15		-	password = "secure-deployment-key"
	18	+	type = "token" # Token auth for automated deployments
	19	+
	20	+	# JWT signing secret (unique to this Gordon instance)
	21	+	token_secret = "gordon/saas/token_secret"
	22	+
	23	+	# Generate deployment tokens:
	24	+	# gordon auth token generate --subject deploy-bot --scopes push,pull --expiry 0
	25	+	# Each Gordon instance has unique tokens (prevents cross-instance token reuse)
16	26
17	27		# Multi-tenant customer routes
18	28		[routes]


@@ -9,10 +9,20 @@ runtime = "auto" # auto-detects Docker/Podman
9		ssl_email = "ops@saas-platform.com"	9		ssl_email = "ops@saas-platform.com"
10		data_dir = "/var/lib/gordon"	10		data_dir = "/var/lib/gordon"
11			11
			12	+	# Secrets backend for secure credential storage
			13	+	[secrets]
			14	+	backend = "pass" # Production should use "pass" or "sops"
			15	+
12		[registry_auth]	16		[registry_auth]
13		enabled = true	17		enabled = true
14	-	username = "deploy"	18	+	type = "token" # Token auth for automated deployments
15	-	password = "secure-deployment-key"	19	+
			20	+	# JWT signing secret (unique to this Gordon instance)
			21	+	token_secret = "gordon/saas/token_secret"
			22	+
			23	+	# Generate deployment tokens:
			24	+	# gordon auth token generate --subject deploy-bot --scopes push,pull --expiry 0
			25	+	# Each Gordon instance has unique tokens (prevents cross-instance token reuse)
16			26
17		# Multi-tenant customer routes	27		# Multi-tenant customer routes
18		[routes]	28		[routes]

M examples/staging.toml +17 -2


@@ -9,10 +9,25 @@ runtime = "auto" # auto-detects Docker/Podman
9	9		ssl_email = "devops@company.com"
10	10		data_dir = "./data"
11	11
	12	+	# Secrets backend for staging
	13	+	[secrets]
	14	+	backend = "pass" # Use pass for secure secret storage
	15	+
12	16		[registry_auth]
13	17		enabled = true
14		-	username = "staging-user"
15		-	password = "staging-pass-123"
	18	+	type = "token" # Token auth for CI/CD pipelines
	19	+
	20	+	# JWT signing secret stored in pass
	21	+	token_secret = "gordon/staging/token_secret"
	22	+
	23	+	# Generate CI tokens with:
	24	+	# gordon auth token generate --subject ci-staging --scopes push,pull --expiry 0
	25	+	# Tokens are unique to this Gordon instance (different token_secret = incompatible tokens)
	26	+
	27	+	# Alternative: Password auth
	28	+	# type = "password"
	29	+	# username = "staging-user"
	30	+	# password_hash = "gordon/staging/password_hash" # bcrypt hash in pass
16	31
17	32		# Staging logging configuration
18	33		[logging]


@@ -9,10 +9,25 @@ runtime = "auto" # auto-detects Docker/Podman
9		ssl_email = "devops@company.com"	9		ssl_email = "devops@company.com"
10		data_dir = "./data"	10		data_dir = "./data"
11			11
			12	+	# Secrets backend for staging
			13	+	[secrets]
			14	+	backend = "pass" # Use pass for secure secret storage
			15	+
12		[registry_auth]	16		[registry_auth]
13		enabled = true	17		enabled = true
14	-	username = "staging-user"	18	+	type = "token" # Token auth for CI/CD pipelines
15	-	password = "staging-pass-123"	19	+
			20	+	# JWT signing secret stored in pass
			21	+	token_secret = "gordon/staging/token_secret"
			22	+
			23	+	# Generate CI tokens with:
			24	+	# gordon auth token generate --subject ci-staging --scopes push,pull --expiry 0
			25	+	# Tokens are unique to this Gordon instance (different token_secret = incompatible tokens)
			26	+
			27	+	# Alternative: Password auth
			28	+	# type = "password"
			29	+	# username = "staging-user"
			30	+	# password_hash = "gordon/staging/password_hash" # bcrypt hash in pass
16			31
17		# Staging logging configuration	32		# Staging logging configuration
18		[logging]	33		[logging]