docs: add insecure registry and TLS troubleshooting guides

Document Docker/Podman insecure registry config, Gordon CLI
insecure TLS options (flag, env, per-remote, global), and
targets.toml → remotes.toml migration note.

commit: 00c89f2724f8800e86add2b884de77bb7fe0fa62
author: brice · 8mo ago · 2026-02-07 07:41 UTC
parent: 7748089
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

2 files · +86 -0

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


@@ -84,6 +84,8 @@ Docker/Podman clients push to this port:
84	84		docker push registry.mydomain.com:5000/myapp:latest
85	85		```
86	86
	87	+	If the registry is served over plain HTTP (no TLS), clients must be configured to allow insecure access. See [Troubleshooting: insecure registry](../reference/troubleshooting.md#server-gave-http-response-to-https-client) for Docker and Podman instructions.
	88	+
87	89		## Gordon Domain
88	90
89	91		The `gordon_domain` is required and must match your DNS configuration:


@@ -84,6 +84,8 @@ Docker/Podman clients push to this port:
84	docker push registry.mydomain.com:5000/myapp:latest	84		docker push registry.mydomain.com:5000/myapp:latest
85	```	85		```
86		86
		87	+	If the registry is served over plain HTTP (no TLS), clients must be configured to allow insecure access. See [Troubleshooting: insecure registry](../reference/troubleshooting.md#server-gave-http-response-to-https-client) for Docker and Podman instructions.
		88	+
87	## Gordon Domain	89		## Gordon Domain
88		90
89	The `gordon_domain` is required and must match your DNS configuration:	91		The `gordon_domain` is required and must match your DNS configuration:

M docs/reference/troubleshooting.md +84 -0


@@ -48,6 +48,74 @@ Common issues and solutions when using Gordon.
48	48		sudo firewall-cmd --list-ports
49	49		```
50	50
	51	+	### "server gave HTTP response to HTTPS client"
	52	+
	53	+	Cause: Docker/Podman defaults to HTTPS but your registry is serving plain HTTP (common with `localhost:5000` or when TLS is terminated by a reverse proxy).
	54	+
	55	+	Solution — Docker:
	56	+
	57	+	Add the registry to `/etc/docker/daemon.json`:
	58	+
	59	+	```json
	60	+	{
	61	+	"insecure-registries": ["gordon.mydomain.com:5000"]
	62	+	}
	63	+	```
	64	+
	65	+	Then restart Docker:
	66	+
	67	+	```bash
	68	+	sudo systemctl restart docker
	69	+	```
	70	+
	71	+	Solution — Podman:
	72	+
	73	+	Create or edit `~/.config/containers/registries.conf.d/gordon.conf`:
	74	+
	75	+	```toml
	76	+	[[registry]]
	77	+	location = "gordon.mydomain.com:5000"
	78	+	insecure = true
	79	+	```
	80	+
	81	+	No restart needed — Podman reads this on each pull/push.
	82	+
	83	+	> Note: For `localhost:5000`, Docker already allows insecure access by default. This is only needed for remote or domain-based registry access over HTTP.
	84	+
	85	+	### TLS certificate errors with the Gordon CLI
	86	+
	87	+	Cause: The Gordon server uses a self-signed certificate or TLS is terminated elsewhere.
	88	+
	89	+	Solutions (in priority order):
	90	+
	91	+	1. Per-command flag:
	92	+
	93	+	```bash
	94	+	gordon push myapp:latest --insecure
	95	+	```
	96	+
	97	+	2. Environment variable:
	98	+
	99	+	```bash
	100	+	export GORDON_INSECURE=true
	101	+	```
	102	+
	103	+	3. Per-remote in `~/.config/gordon/remotes.toml`:
	104	+
	105	+	```toml
	106	+	[remotes.my-server]
	107	+	url = "https://gordon.mydomain.com"
	108	+	token = "..."
	109	+	insecure_tls = true
	110	+	```
	111	+
	112	+	4. Global default in `~/.config/gordon/gordon.toml`:
	113	+
	114	+	```toml
	115	+	[client]
	116	+	insecure_tls = true
	117	+	```
	118	+
51	119		### "unknown: image not found"
52	120
53	121		Cause: Image was pushed but no route configured.

@@ -261,6 +329,22 @@ gordon reload
261	329		gordon reload
262	330		```
263	331
	332	+	### Stale `targets.toml` in config directory
	333	+
	334	+	Cause: Gordon renamed `targets.toml` to `remotes.toml` in v2.9. The old file is ignored but may cause confusion.
	335	+
	336	+	Solution: Delete the old file and use `remotes.toml`:
	337	+
	338	+	```bash
	339	+	rm ~/.config/gordon/targets.toml
	340	+	```
	341	+
	342	+	If you had remotes configured in `targets.toml`, recreate them:
	343	+
	344	+	```bash
	345	+	gordon remotes add my-server https://gordon.mydomain.com --token YOUR_TOKEN
	346	+	```
	347	+
264	348		### "failed to read config file"
265	349
266	350		Cause: TOML syntax error.


@@ -48,6 +48,74 @@ Common issues and solutions when using Gordon.
48	sudo firewall-cmd --list-ports	48		sudo firewall-cmd --list-ports
49	```	49		```
50		50
		51	+	### "server gave HTTP response to HTTPS client"
		52	+
		53	+	Cause: Docker/Podman defaults to HTTPS but your registry is serving plain HTTP (common with `localhost:5000` or when TLS is terminated by a reverse proxy).
		54	+
		55	+	Solution — Docker:
		56	+
		57	+	Add the registry to `/etc/docker/daemon.json`:
		58	+
		59	+	```json
		60	+	{
		61	+	"insecure-registries": ["gordon.mydomain.com:5000"]
		62	+	}
		63	+	```
		64	+
		65	+	Then restart Docker:
		66	+
		67	+	```bash
		68	+	sudo systemctl restart docker
		69	+	```
		70	+
		71	+	Solution — Podman:
		72	+
		73	+	Create or edit `~/.config/containers/registries.conf.d/gordon.conf`:
		74	+
		75	+	```toml
		76	+	[[registry]]
		77	+	location = "gordon.mydomain.com:5000"
		78	+	insecure = true
		79	+	```
		80	+
		81	+	No restart needed — Podman reads this on each pull/push.
		82	+
		83	+	> Note: For `localhost:5000`, Docker already allows insecure access by default. This is only needed for remote or domain-based registry access over HTTP.
		84	+
		85	+	### TLS certificate errors with the Gordon CLI
		86	+
		87	+	Cause: The Gordon server uses a self-signed certificate or TLS is terminated elsewhere.
		88	+
		89	+	Solutions (in priority order):
		90	+
		91	+	1. Per-command flag:
		92	+
		93	+	```bash
		94	+	gordon push myapp:latest --insecure
		95	+	```
		96	+
		97	+	2. Environment variable:
		98	+
		99	+	```bash
		100	+	export GORDON_INSECURE=true
		101	+	```
		102	+
		103	+	3. Per-remote in `~/.config/gordon/remotes.toml`:
		104	+
		105	+	```toml
		106	+	[remotes.my-server]
		107	+	url = "https://gordon.mydomain.com"
		108	+	token = "..."
		109	+	insecure_tls = true
		110	+	```
		111	+
		112	+	4. Global default in `~/.config/gordon/gordon.toml`:
		113	+
		114	+	```toml
		115	+	[client]
		116	+	insecure_tls = true
		117	+	```
		118	+
51	### "unknown: image not found"	119		### "unknown: image not found"
52		120
53	Cause: Image was pushed but no route configured.	121		Cause: Image was pushed but no route configured.

@@ -261,6 +329,22 @@ gordon reload
261	gordon reload	329		gordon reload
262	```	330		```
263		331
		332	+	### Stale `targets.toml` in config directory
		333	+
		334	+	Cause: Gordon renamed `targets.toml` to `remotes.toml` in v2.9. The old file is ignored but may cause confusion.
		335	+
		336	+	Solution: Delete the old file and use `remotes.toml`:
		337	+
		338	+	```bash
		339	+	rm ~/.config/gordon/targets.toml
		340	+	```
		341	+
		342	+	If you had remotes configured in `targets.toml`, recreate them:
		343	+
		344	+	```bash
		345	+	gordon remotes add my-server https://gordon.mydomain.com --token YOUR_TOKEN
		346	+	```
		347	+
264	### "failed to read config file"	348		### "failed to read config file"
265		349
266	Cause: TOML syntax error.	350		Cause: TOML syntax error.