docs(wiki): add pass secrets backend setup for containers

Add section explaining how to use pass secrets backend when running
Gordon in a container, including custom Dockerfile, volume mounts
for GPG keys and password store, and troubleshooting tips.

commit: b8937bb241c3e866d981c761f11a0ffc1310693b
author: brice · 9mo ago · 2026-01-16 06:36 UTC
parent: f1c63af
signature: unsigned

1 file · +125 -0

M wiki/guides/running-in-container.md +125 -0


@@ -227,6 +227,131 @@ All configuration options can be set via environment variables with `GORDON_` pr
227	227
228	228		> Note: For registry passwords, using plain `password` is deprecated. Use `password_hash` with a secrets backend instead. See [Registry Auth](/docs/config/registry-auth.md) for secure setup.
229	229
	230	+	## Using Pass Secrets Backend
	231	+
	232	+	To use the `pass` secrets backend in a container, you need to mount GPG keys and the password store.
	233	+
	234	+	### Prerequisites on Host
	235	+
	236	+	```bash
	237	+	# Install pass and initialize (if not already done)
	238	+	sudo apt install pass gnupg
	239	+	gpg --gen-key
	240	+	pass init <your-gpg-key-id>
	241	+
	242	+	# Store Gordon secrets
	243	+	pass insert gordon/registry/password_hash
	244	+	pass insert gordon/registry/token_secret
	245	+	```
	246	+
	247	+	### Custom Dockerfile
	248	+
	249	+	The default Gordon image doesn't include `pass`. Create a custom Dockerfile:
	250	+
	251	+	```dockerfile
	252	+	FROM ghcr.io/bnema/gordon:latest
	253	+
	254	+	USER root
	255	+	RUN apk add --no-cache pass gnupg
	256	+	USER gordon
	257	+	```
	258	+
	259	+	Build it:
	260	+
	261	+	```bash
	262	+	docker build -t gordon-with-pass .
	263	+	```
	264	+
	265	+	### Docker Run with Pass
	266	+
	267	+	```bash
	268	+	docker run -d \
	269	+	--name gordon \
	270	+	-p 80:8080 \
	271	+	-p 5000:5000 \
	272	+	-v /var/run/docker.sock:/var/run/docker.sock \
	273	+	-v gordon-data:/data \
	274	+	-v $HOME/.gnupg:/home/gordon/.gnupg:ro \
	275	+	-v $HOME/.password-store:/home/gordon/.password-store:ro \
	276	+	-v $(pwd)/gordon.toml:/etc/gordon/gordon.toml:ro \
	277	+	gordon-with-pass
	278	+	```
	279	+
	280	+	### Docker Compose with Pass
	281	+
	282	+	```yaml
	283	+	services:
	284	+	gordon:
	285	+	build:
	286	+	context: .
	287	+	dockerfile: Dockerfile.gordon
	288	+	container_name: gordon
	289	+	restart: unless-stopped
	290	+	ports:
	291	+	- "80:8080"
	292	+	- "5000:5000"
	293	+	volumes:
	294	+	- /var/run/docker.sock:/var/run/docker.sock
	295	+	- gordon-data:/data
	296	+	- ./gordon.toml:/etc/gordon/gordon.toml:ro
	297	+	# GPG and pass mounts
	298	+	- ~/.gnupg:/home/gordon/.gnupg:ro
	299	+	- ~/.password-store:/home/gordon/.password-store:ro
	300	+	environment:
	301	+	- GORDON_SECRETS_BACKEND=pass
	302	+
	303	+	volumes:
	304	+	gordon-data:
	305	+	```
	306	+
	307	+	### Configuration
	308	+
	309	+	```toml
	310	+	[secrets]
	311	+	backend = "pass"
	312	+
	313	+	[registry_auth]
	314	+	enabled = true
	315	+	type = "token"
	316	+	username = "admin"
	317	+	password_hash = "gordon/registry/password_hash"
	318	+	token_secret = "gordon/registry/token_secret"
	319	+	```
	320	+
	321	+	### GPG Agent (Optional)
	322	+
	323	+	For GPG keys with passphrases, you may need to forward the GPG agent socket:
	324	+
	325	+	```bash
	326	+	-v $(gpgconf --list-dirs agent-socket):/home/gordon/.gnupg/S.gpg-agent:ro
	327	+	```
	328	+
	329	+	Or use a passphrase-less GPG key for automated deployments.
	330	+
	331	+	### Troubleshooting Pass
	332	+
	333	+	"gpg: decryption failed: No secret key"
	334	+
	335	+	The GPG private key isn't accessible. Verify mounts:
	336	+
	337	+	```bash
	338	+	docker exec gordon gpg --list-secret-keys
	339	+	```
	340	+
	341	+	"pass: command not found"
	342	+
	343	+	Use the custom Dockerfile with pass installed.
	344	+
	345	+	Permission denied on .gnupg
	346	+
	347	+	Ensure the gordon user (UID 1000) can read the mounted directories:
	348	+
	349	+	```bash
	350	+	# On host, check permissions
	351	+	ls -la ~/.gnupg
	352	+	ls -la ~/.password-store
	353	+	```
	354	+
230	355		## Security Considerations
231	356
232	357		### Docker Socket Access


@@ -227,6 +227,131 @@ All configuration options can be set via environment variables with `GORDON_` pr
227		227
228	> Note: For registry passwords, using plain `password` is deprecated. Use `password_hash` with a secrets backend instead. See [Registry Auth](/docs/config/registry-auth.md) for secure setup.	228		> Note: For registry passwords, using plain `password` is deprecated. Use `password_hash` with a secrets backend instead. See [Registry Auth](/docs/config/registry-auth.md) for secure setup.
229		229
		230	+	## Using Pass Secrets Backend
		231	+
		232	+	To use the `pass` secrets backend in a container, you need to mount GPG keys and the password store.
		233	+
		234	+	### Prerequisites on Host
		235	+
		236	+	```bash
		237	+	# Install pass and initialize (if not already done)
		238	+	sudo apt install pass gnupg
		239	+	gpg --gen-key
		240	+	pass init <your-gpg-key-id>
		241	+
		242	+	# Store Gordon secrets
		243	+	pass insert gordon/registry/password_hash
		244	+	pass insert gordon/registry/token_secret
		245	+	```
		246	+
		247	+	### Custom Dockerfile
		248	+
		249	+	The default Gordon image doesn't include `pass`. Create a custom Dockerfile:
		250	+
		251	+	```dockerfile
		252	+	FROM ghcr.io/bnema/gordon:latest
		253	+
		254	+	USER root
		255	+	RUN apk add --no-cache pass gnupg
		256	+	USER gordon
		257	+	```
		258	+
		259	+	Build it:
		260	+
		261	+	```bash
		262	+	docker build -t gordon-with-pass .
		263	+	```
		264	+
		265	+	### Docker Run with Pass
		266	+
		267	+	```bash
		268	+	docker run -d \
		269	+	--name gordon \
		270	+	-p 80:8080 \
		271	+	-p 5000:5000 \
		272	+	-v /var/run/docker.sock:/var/run/docker.sock \
		273	+	-v gordon-data:/data \
		274	+	-v $HOME/.gnupg:/home/gordon/.gnupg:ro \
		275	+	-v $HOME/.password-store:/home/gordon/.password-store:ro \
		276	+	-v $(pwd)/gordon.toml:/etc/gordon/gordon.toml:ro \
		277	+	gordon-with-pass
		278	+	```
		279	+
		280	+	### Docker Compose with Pass
		281	+
		282	+	```yaml
		283	+	services:
		284	+	gordon:
		285	+	build:
		286	+	context: .
		287	+	dockerfile: Dockerfile.gordon
		288	+	container_name: gordon
		289	+	restart: unless-stopped
		290	+	ports:
		291	+	- "80:8080"
		292	+	- "5000:5000"
		293	+	volumes:
		294	+	- /var/run/docker.sock:/var/run/docker.sock
		295	+	- gordon-data:/data
		296	+	- ./gordon.toml:/etc/gordon/gordon.toml:ro
		297	+	# GPG and pass mounts
		298	+	- ~/.gnupg:/home/gordon/.gnupg:ro
		299	+	- ~/.password-store:/home/gordon/.password-store:ro
		300	+	environment:
		301	+	- GORDON_SECRETS_BACKEND=pass
		302	+
		303	+	volumes:
		304	+	gordon-data:
		305	+	```
		306	+
		307	+	### Configuration
		308	+
		309	+	```toml
		310	+	[secrets]
		311	+	backend = "pass"
		312	+
		313	+	[registry_auth]
		314	+	enabled = true
		315	+	type = "token"
		316	+	username = "admin"
		317	+	password_hash = "gordon/registry/password_hash"
		318	+	token_secret = "gordon/registry/token_secret"
		319	+	```
		320	+
		321	+	### GPG Agent (Optional)
		322	+
		323	+	For GPG keys with passphrases, you may need to forward the GPG agent socket:
		324	+
		325	+	```bash
		326	+	-v $(gpgconf --list-dirs agent-socket):/home/gordon/.gnupg/S.gpg-agent:ro
		327	+	```
		328	+
		329	+	Or use a passphrase-less GPG key for automated deployments.
		330	+
		331	+	### Troubleshooting Pass
		332	+
		333	+	"gpg: decryption failed: No secret key"
		334	+
		335	+	The GPG private key isn't accessible. Verify mounts:
		336	+
		337	+	```bash
		338	+	docker exec gordon gpg --list-secret-keys
		339	+	```
		340	+
		341	+	"pass: command not found"
		342	+
		343	+	Use the custom Dockerfile with pass installed.
		344	+
		345	+	Permission denied on .gnupg
		346	+
		347	+	Ensure the gordon user (UID 1000) can read the mounted directories:
		348	+
		349	+	```bash
		350	+	# On host, check permissions
		351	+	ls -la ~/.gnupg
		352	+	ls -la ~/.password-store
		353	+	```
		354	+
230	## Security Considerations	355		## Security Considerations
231		356
232	### Docker Socket Access	357		### Docker Socket Access