docs: add remote CLI and label-based auto-route documentation

commit: bfe59e6c67b52bb4d39c792097033c1258d8ee4c
author: bnema · 9mo ago · 2026-01-16 20:54 UTC
parent: 5954557
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

2 files · +251 -5

M docs/cli/commands.md +134 -2


@@ -12,6 +12,9 @@ Gordon provides a command-line interface for server management, deployment, and
12	12		\| `gordon logs` \| Display Gordon process logs \|
13	13		\| `gordon version` \| Print version information \|
14	14		\| `gordon auth` \| Manage registry authentication \|
	15	+	\| `gordon routes` \| Manage routes (local or remote) \|
	16	+	\| `gordon secrets` \| Manage secrets (remote only) \|
	17	+	\| `gordon targets` \| Manage remote Gordon targets \|
15	18
16	19		## Quick Reference
17	20

@@ -47,6 +50,22 @@ gordon auth internal
47	50		\| Option \| Description \|
48	51		\|--------\|-------------\|
49	52		\| `-c, --config` \| Path to configuration file \|
	53	+	\| `--target` \| Remote Gordon URL (e.g., `https://gordon.mydomain.com`) \|
	54	+	\| `--token` \| Authentication token for remote target \|
	55	+
	56	+	### Remote Targeting
	57	+
	58	+	The CLI can target remote Gordon instances using the `--target` flag or `GORDON_TARGET` environment variable:
	59	+
	60	+	```bash
	61	+	# Using flags
	62	+	gordon routes list --target https://gordon.mydomain.com --token $TOKEN
	63	+
	64	+	# Using environment variables
	65	+	export GORDON_TARGET=https://gordon.mydomain.com
	66	+	export GORDON_TOKEN=$TOKEN
	67	+	gordon routes list
	68	+	```
50	69
51	70		---
52	71

@@ -529,6 +548,119 @@ password_hash = "gordon/registry/password_hash"
529	548
530	549		---
531	550
	551	+	## gordon routes
	552	+
	553	+	Manage routes on local or remote Gordon instances.
	554	+
	555	+	### Subcommands
	556	+
	557	+	\| Subcommand \| Description \|
	558	+	\|------------\|-------------\|
	559	+	\| `list` \| List all routes \|
	560	+	\| `add` \| Add a new route \|
	561	+	\| `remove` \| Remove a route \|
	562	+	\| `deploy` \| Deploy a specific route \|
	563	+
	564	+	### gordon routes list
	565	+
	566	+	List all configured routes.
	567	+
	568	+	```bash
	569	+	gordon routes list
	570	+	gordon routes list --target https://gordon.mydomain.com --token $TOKEN
	571	+	```
	572	+
	573	+	### gordon routes add
	574	+
	575	+	Add a new route.
	576	+
	577	+	```bash
	578	+	gordon routes add <domain> <image>
	579	+	gordon routes add myapp.example.com myapp:latest
	580	+	```
	581	+
	582	+	### gordon routes remove
	583	+
	584	+	Remove a route.
	585	+
	586	+	```bash
	587	+	gordon routes remove <domain>
	588	+	gordon routes remove myapp.example.com
	589	+	```
	590	+
	591	+	### gordon routes deploy
	592	+
	593	+	Deploy or redeploy a specific route.
	594	+
	595	+	```bash
	596	+	gordon routes deploy <domain>
	597	+	gordon routes deploy myapp.example.com
	598	+	```
	599	+
	600	+	---
	601	+
	602	+	## gordon secrets
	603	+
	604	+	Manage secrets on remote Gordon instances. Requires remote targeting.
	605	+
	606	+	### Subcommands
	607	+
	608	+	\| Subcommand \| Description \|
	609	+	\|------------\|-------------\|
	610	+	\| `list` \| List all secrets \|
	611	+	\| `get` \| Get a secret value \|
	612	+	\| `set` \| Set a secret value \|
	613	+	\| `delete` \| Delete a secret \|
	614	+
	615	+	### Examples
	616	+
	617	+	```bash
	618	+	# List secrets
	619	+	gordon secrets list --target https://gordon.mydomain.com --token $TOKEN
	620	+
	621	+	# Set a secret
	622	+	gordon secrets set DATABASE_URL "postgres://..." --target ... --token ...
	623	+
	624	+	# Get a secret
	625	+	gordon secrets get DATABASE_URL --target ... --token ...
	626	+
	627	+	# Delete a secret
	628	+	gordon secrets delete DATABASE_URL --target ... --token ...
	629	+	```
	630	+
	631	+	---
	632	+
	633	+	## gordon targets
	634	+
	635	+	Manage saved remote Gordon targets for easier CLI usage.
	636	+
	637	+	### Subcommands
	638	+
	639	+	\| Subcommand \| Description \|
	640	+	\|------------\|-------------\|
	641	+	\| `list` \| List saved targets \|
	642	+	\| `add` \| Add a new target \|
	643	+	\| `remove` \| Remove a saved target \|
	644	+	\| `set-default` \| Set default target \|
	645	+
	646	+	### Examples
	647	+
	648	+	```bash
	649	+	# Add a target
	650	+	gordon targets add prod https://gordon.mydomain.com $TOKEN
	651	+
	652	+	# List saved targets
	653	+	gordon targets list
	654	+
	655	+	# Set default target
	656	+	gordon targets set-default prod
	657	+
	658	+	# Now use without --target flag
	659	+	gordon routes list
	660	+	```
	661	+
	662	+	---
	663	+
532	664		## Exit Codes
533	665
534	666		\| Code \| Meaning \|

@@ -542,8 +674,8 @@ password_hash = "gordon/registry/password_hash"
542	674		Gordon reads configuration from environment variables:
543	675
544	676		```bash
545		-	GORDON_SERVER_PORT=8080 gordon start
546		-	GORDON_LOGGING_LEVEL=debug gordon start
	677	+	GORDON_SERVER_PORT=8080 gordon serve
	678	+	GORDON_LOGGING_LEVEL=debug gordon serve
547	679		```
548	680
549	681		Pattern: `GORDON_SECTION_KEY` (uppercase, underscores)


@@ -12,6 +12,9 @@ Gordon provides a command-line interface for server management, deployment, and
12		\| `gordon logs` \| Display Gordon process logs \|	12		\| `gordon logs` \| Display Gordon process logs \|
13		\| `gordon version` \| Print version information \|	13		\| `gordon version` \| Print version information \|
14		\| `gordon auth` \| Manage registry authentication \|	14		\| `gordon auth` \| Manage registry authentication \|
			15	+	\| `gordon routes` \| Manage routes (local or remote) \|
			16	+	\| `gordon secrets` \| Manage secrets (remote only) \|
			17	+	\| `gordon targets` \| Manage remote Gordon targets \|
15			18
16		## Quick Reference	19		## Quick Reference
17			20

@@ -47,6 +50,22 @@ gordon auth internal
47		\| Option \| Description \|	50		\| Option \| Description \|
48		\|--------\|-------------\|	51		\|--------\|-------------\|
49		\| `-c, --config` \| Path to configuration file \|	52		\| `-c, --config` \| Path to configuration file \|
			53	+	\| `--target` \| Remote Gordon URL (e.g., `https://gordon.mydomain.com`) \|
			54	+	\| `--token` \| Authentication token for remote target \|
			55	+
			56	+	### Remote Targeting
			57	+
			58	+	The CLI can target remote Gordon instances using the `--target` flag or `GORDON_TARGET` environment variable:
			59	+
			60	+	```bash
			61	+	# Using flags
			62	+	gordon routes list --target https://gordon.mydomain.com --token $TOKEN
			63	+
			64	+	# Using environment variables
			65	+	export GORDON_TARGET=https://gordon.mydomain.com
			66	+	export GORDON_TOKEN=$TOKEN
			67	+	gordon routes list
			68	+	```
50			69
51		---	70		---
52			71

@@ -529,6 +548,119 @@ password_hash = "gordon/registry/password_hash"
529			548
530		---	549		---
531			550
			551	+	## gordon routes
			552	+
			553	+	Manage routes on local or remote Gordon instances.
			554	+
			555	+	### Subcommands
			556	+
			557	+	\| Subcommand \| Description \|
			558	+	\|------------\|-------------\|
			559	+	\| `list` \| List all routes \|
			560	+	\| `add` \| Add a new route \|
			561	+	\| `remove` \| Remove a route \|
			562	+	\| `deploy` \| Deploy a specific route \|
			563	+
			564	+	### gordon routes list
			565	+
			566	+	List all configured routes.
			567	+
			568	+	```bash
			569	+	gordon routes list
			570	+	gordon routes list --target https://gordon.mydomain.com --token $TOKEN
			571	+	```
			572	+
			573	+	### gordon routes add
			574	+
			575	+	Add a new route.
			576	+
			577	+	```bash
			578	+	gordon routes add <domain> <image>
			579	+	gordon routes add myapp.example.com myapp:latest
			580	+	```
			581	+
			582	+	### gordon routes remove
			583	+
			584	+	Remove a route.
			585	+
			586	+	```bash
			587	+	gordon routes remove <domain>
			588	+	gordon routes remove myapp.example.com
			589	+	```
			590	+
			591	+	### gordon routes deploy
			592	+
			593	+	Deploy or redeploy a specific route.
			594	+
			595	+	```bash
			596	+	gordon routes deploy <domain>
			597	+	gordon routes deploy myapp.example.com
			598	+	```
			599	+
			600	+	---
			601	+
			602	+	## gordon secrets
			603	+
			604	+	Manage secrets on remote Gordon instances. Requires remote targeting.
			605	+
			606	+	### Subcommands
			607	+
			608	+	\| Subcommand \| Description \|
			609	+	\|------------\|-------------\|
			610	+	\| `list` \| List all secrets \|
			611	+	\| `get` \| Get a secret value \|
			612	+	\| `set` \| Set a secret value \|
			613	+	\| `delete` \| Delete a secret \|
			614	+
			615	+	### Examples
			616	+
			617	+	```bash
			618	+	# List secrets
			619	+	gordon secrets list --target https://gordon.mydomain.com --token $TOKEN
			620	+
			621	+	# Set a secret
			622	+	gordon secrets set DATABASE_URL "postgres://..." --target ... --token ...
			623	+
			624	+	# Get a secret
			625	+	gordon secrets get DATABASE_URL --target ... --token ...
			626	+
			627	+	# Delete a secret
			628	+	gordon secrets delete DATABASE_URL --target ... --token ...
			629	+	```
			630	+
			631	+	---
			632	+
			633	+	## gordon targets
			634	+
			635	+	Manage saved remote Gordon targets for easier CLI usage.
			636	+
			637	+	### Subcommands
			638	+
			639	+	\| Subcommand \| Description \|
			640	+	\|------------\|-------------\|
			641	+	\| `list` \| List saved targets \|
			642	+	\| `add` \| Add a new target \|
			643	+	\| `remove` \| Remove a saved target \|
			644	+	\| `set-default` \| Set default target \|
			645	+
			646	+	### Examples
			647	+
			648	+	```bash
			649	+	# Add a target
			650	+	gordon targets add prod https://gordon.mydomain.com $TOKEN
			651	+
			652	+	# List saved targets
			653	+	gordon targets list
			654	+
			655	+	# Set default target
			656	+	gordon targets set-default prod
			657	+
			658	+	# Now use without --target flag
			659	+	gordon routes list
			660	+	```
			661	+
			662	+	---
			663	+
532		## Exit Codes	664		## Exit Codes
533			665
534		\| Code \| Meaning \|	666		\| Code \| Meaning \|

@@ -542,8 +674,8 @@ password_hash = "gordon/registry/password_hash"
542		Gordon reads configuration from environment variables:	674		Gordon reads configuration from environment variables:
543			675
544		```bash	676		```bash
545	-	GORDON_SERVER_PORT=8080 gordon start	677	+	GORDON_SERVER_PORT=8080 gordon serve
546	-	GORDON_LOGGING_LEVEL=debug gordon start	678	+	GORDON_LOGGING_LEVEL=debug gordon serve
547		```	679		```
548			680
549		Pattern: `GORDON_SECTION_KEY` (uppercase, underscores)	681		Pattern: `GORDON_SECTION_KEY` (uppercase, underscores)

M docs/config/auto-route.md +117 -3

@@ -1,6 +1,9 @@
1	1		# Auto Route Configuration
2	2
3		-	Automatically create routes from image names that contain domains.
	3	+	Gordon supports two methods for automatic route creation:
	4	+
	5	+	1. Image Name Detection - Routes from domain-like image names
	6	+	2. Image Labels - Routes from Dockerfile labels (recommended)
4	7
5	8		## Configuration
6	9

@@ -152,14 +155,125 @@ enabled = true
152	155		# Other services can use auto-route
153	156		```
154	157
155		-	## Limitations
	158	+	## Limitations (Image Name Detection)
156	159
157	160		- Auto-routes always use the pushed image tag
158	161		- No support for HTTP-only routes (all HTTPS)
159	162		- No automatic attachment configuration
160	163		- Cannot pin versions (always uses pushed tag)
161	164
162		-	For more control, define routes manually in `[routes]`.
	165	+	For more control, define routes manually in `[routes]` or use image labels.
	166	+
	167	+	---
	168	+
	169	+	## Image Labels (Recommended)
	170	+
	171	+	The preferred method for automatic routing uses Dockerfile labels. This gives you full control over routing behavior directly in your application.
	172	+
	173	+	### Supported Labels
	174	+
	175	+	\| Label \| Description \| Example \|
	176	+	\|-------\|-------------\|---------\|
	177	+	\| `gordon.domains` \| Comma-separated list of domains \| `app.example.com,www.app.example.com` \|
	178	+	\| `gordon.port` \| Container port to proxy \| `3000` \|
	179	+	\| `gordon.health` \| Health check endpoint path \| `/health` \|
	180	+	\| `gordon.env-file` \| Path to .env file in image \| `/app/.env.example` \|
	181	+
	182	+	### Dockerfile Example
	183	+
	184	+	```dockerfile
	185	+	FROM node:20-alpine
	186	+	WORKDIR /app
	187	+	COPY . .
	188	+	RUN npm install
	189	+
	190	+	# Gordon routing labels
	191	+	LABEL gordon.domains="myapp.example.com,www.myapp.example.com"
	192	+	LABEL gordon.port="3000"
	193	+	LABEL gordon.health="/api/health"
	194	+	LABEL gordon.env-file="/app/.env.example"
	195	+
	196	+	EXPOSE 3000
	197	+	CMD ["npm", "start"]
	198	+	```
	199	+
	200	+	### How It Works
	201	+
	202	+	When you push an image with Gordon labels:
	203	+
	204	+	1. Gordon reads the `gordon.domains` label
	205	+	2. Creates routes for each domain automatically
	206	+	3. Uses `gordon.port` for the proxy target (or first EXPOSE port)
	207	+	4. Configures health checks if `gordon.health` is set
	208	+	5. Extracts environment variables from `gordon.env-file` if specified
	209	+
	210	+	### Label Priority
	211	+
	212	+	Labels take precedence over image name detection:
	213	+
	214	+	1. Labels present → Use `gordon.domains` for routing
	215	+	2. No labels → Fall back to image name detection (if enabled)
	216	+	3. Manual routes → Always take highest priority
	217	+
	218	+	### Multi-Domain Example
	219	+
	220	+	```dockerfile
	221	+	# Single image serving multiple domains
	222	+	LABEL gordon.domains="api.example.com,api.staging.example.com"
	223	+	```
	224	+
	225	+	Both domains will route to the same container.
	226	+
	227	+	### Environment File Extraction
	228	+
	229	+	The `gordon.env-file` label tells Gordon where to find a template `.env` file:
	230	+
	231	+	```dockerfile
	232	+	# Include a .env.example in your image
	233	+	COPY .env.example /app/.env.example
	234	+	LABEL gordon.env-file="/app/.env.example"
	235	+	```
	236	+
	237	+	Gordon will:
	238	+	1. Extract the file from the image
	239	+	2. Store it in the env directory
	240	+	3. Use the variables for container deployment
	241	+
	242	+	### Best Practices
	243	+
	244	+	1. Always set `gordon.port` - Don't rely on EXPOSE detection
	245	+	2. Use `gordon.health` - Enables reliable deployment verification
	246	+	3. Include `.env.example` - Self-documenting environment requirements
	247	+	4. Separate domains with commas - No spaces around commas
	248	+
	249	+	### Example: Complete Setup
	250	+
	251	+	```dockerfile
	252	+	FROM golang:1.21-alpine AS builder
	253	+	WORKDIR /app
	254	+	COPY . .
	255	+	RUN go build -o server
	256	+
	257	+	FROM alpine:3.19
	258	+	WORKDIR /app
	259	+	COPY --from=builder /app/server .
	260	+	COPY .env.example .
	261	+
	262	+	# Gordon labels
	263	+	LABEL gordon.domains="api.mycompany.com"
	264	+	LABEL gordon.port="8080"
	265	+	LABEL gordon.health="/health"
	266	+	LABEL gordon.env-file="/app/.env.example"
	267	+
	268	+	EXPOSE 8080
	269	+	CMD ["./server"]
	270	+	```
	271	+
	272	+	```bash
	273	+	# Push and Gordon handles everything
	274	+	docker push registry.mycompany.com/api:latest
	275	+	# Route automatically created: api.mycompany.com → container:8080
	276	+	```
163	277
164	278		## Related
165	279

@@ -1,6 +1,9 @@
1		# Auto Route Configuration	1		# Auto Route Configuration
2			2
3	-	Automatically create routes from image names that contain domains.	3	+	Gordon supports two methods for automatic route creation:
			4	+
			5	+	1. Image Name Detection - Routes from domain-like image names
			6	+	2. Image Labels - Routes from Dockerfile labels (recommended)
4			7
5		## Configuration	8		## Configuration
6			9

@@ -152,14 +155,125 @@ enabled = true
152		# Other services can use auto-route	155		# Other services can use auto-route
153		```	156		```
154			157
155	-	## Limitations	158	+	## Limitations (Image Name Detection)
156			159
157		- Auto-routes always use the pushed image tag	160		- Auto-routes always use the pushed image tag
158		- No support for HTTP-only routes (all HTTPS)	161		- No support for HTTP-only routes (all HTTPS)
159		- No automatic attachment configuration	162		- No automatic attachment configuration
160		- Cannot pin versions (always uses pushed tag)	163		- Cannot pin versions (always uses pushed tag)
161			164
162	-	For more control, define routes manually in `[routes]`.	165	+	For more control, define routes manually in `[routes]` or use image labels.
			166	+
			167	+	---
			168	+
			169	+	## Image Labels (Recommended)
			170	+
			171	+	The preferred method for automatic routing uses Dockerfile labels. This gives you full control over routing behavior directly in your application.
			172	+
			173	+	### Supported Labels
			174	+
			175	+	\| Label \| Description \| Example \|
			176	+	\|-------\|-------------\|---------\|
			177	+	\| `gordon.domains` \| Comma-separated list of domains \| `app.example.com,www.app.example.com` \|
			178	+	\| `gordon.port` \| Container port to proxy \| `3000` \|
			179	+	\| `gordon.health` \| Health check endpoint path \| `/health` \|
			180	+	\| `gordon.env-file` \| Path to .env file in image \| `/app/.env.example` \|
			181	+
			182	+	### Dockerfile Example
			183	+
			184	+	```dockerfile
			185	+	FROM node:20-alpine
			186	+	WORKDIR /app
			187	+	COPY . .
			188	+	RUN npm install
			189	+
			190	+	# Gordon routing labels
			191	+	LABEL gordon.domains="myapp.example.com,www.myapp.example.com"
			192	+	LABEL gordon.port="3000"
			193	+	LABEL gordon.health="/api/health"
			194	+	LABEL gordon.env-file="/app/.env.example"
			195	+
			196	+	EXPOSE 3000
			197	+	CMD ["npm", "start"]
			198	+	```
			199	+
			200	+	### How It Works
			201	+
			202	+	When you push an image with Gordon labels:
			203	+
			204	+	1. Gordon reads the `gordon.domains` label
			205	+	2. Creates routes for each domain automatically
			206	+	3. Uses `gordon.port` for the proxy target (or first EXPOSE port)
			207	+	4. Configures health checks if `gordon.health` is set
			208	+	5. Extracts environment variables from `gordon.env-file` if specified
			209	+
			210	+	### Label Priority
			211	+
			212	+	Labels take precedence over image name detection:
			213	+
			214	+	1. Labels present → Use `gordon.domains` for routing
			215	+	2. No labels → Fall back to image name detection (if enabled)
			216	+	3. Manual routes → Always take highest priority
			217	+
			218	+	### Multi-Domain Example
			219	+
			220	+	```dockerfile
			221	+	# Single image serving multiple domains
			222	+	LABEL gordon.domains="api.example.com,api.staging.example.com"
			223	+	```
			224	+
			225	+	Both domains will route to the same container.
			226	+
			227	+	### Environment File Extraction
			228	+
			229	+	The `gordon.env-file` label tells Gordon where to find a template `.env` file:
			230	+
			231	+	```dockerfile
			232	+	# Include a .env.example in your image
			233	+	COPY .env.example /app/.env.example
			234	+	LABEL gordon.env-file="/app/.env.example"
			235	+	```
			236	+
			237	+	Gordon will:
			238	+	1. Extract the file from the image
			239	+	2. Store it in the env directory
			240	+	3. Use the variables for container deployment
			241	+
			242	+	### Best Practices
			243	+
			244	+	1. Always set `gordon.port` - Don't rely on EXPOSE detection
			245	+	2. Use `gordon.health` - Enables reliable deployment verification
			246	+	3. Include `.env.example` - Self-documenting environment requirements
			247	+	4. Separate domains with commas - No spaces around commas
			248	+
			249	+	### Example: Complete Setup
			250	+
			251	+	```dockerfile
			252	+	FROM golang:1.21-alpine AS builder
			253	+	WORKDIR /app
			254	+	COPY . .
			255	+	RUN go build -o server
			256	+
			257	+	FROM alpine:3.19
			258	+	WORKDIR /app
			259	+	COPY --from=builder /app/server .
			260	+	COPY .env.example .
			261	+
			262	+	# Gordon labels
			263	+	LABEL gordon.domains="api.mycompany.com"
			264	+	LABEL gordon.port="8080"
			265	+	LABEL gordon.health="/health"
			266	+	LABEL gordon.env-file="/app/.env.example"
			267	+
			268	+	EXPOSE 8080
			269	+	CMD ["./server"]
			270	+	```
			271	+
			272	+	```bash
			273	+	# Push and Gordon handles everything
			274	+	docker push registry.mycompany.com/api:latest
			275	+	# Route automatically created: api.mycompany.com → container:8080
			276	+	```
163			277
164		## Related	278		## Related
165			279