2.2 KiB
ADR: Docker Credential Helper Setup
Status
Accepted
Date
2026-04-26
Context
Docker credentials for git.lilastudy.com and dhi.io were stored as
base64-encoded strings in ~/.docker/config.json on both the dev laptop
and the VPS. Base64 is not encryption — anyone with read access to the
file can decode the credentials instantly.
Decision
Use pass (GPG-backed password store) as the Docker credential helper
on both machines.
Options considered
Option A — pass (GPG-backed) ✅
Stores credentials encrypted with a GPG key. Works on headless servers and desktops without GNOME. Industry standard for Linux servers.
Option B — secretservice (GNOME keyring)
Uses the desktop keyring daemon. Not suitable for a headless VPS, and
not suitable for an i3 desktop without running gnome-keyring-daemon
manually.
Option C — gnome-libsecret
Same limitations as Option B.
Consequences
- Credentials are now GPG-encrypted at rest on both machines
- Requires GPG passphrase entry when Docker needs to pull credentials in a new session
- Must be set up manually on each machine — not reproducible via the repo
- VPS setup must be repeated if the server is reprovisioned
Affected machines
- Dev laptop (Debian 13, i3)
- VPS (Debian 13, ARM64, headless)
References
- https://docs.docker.com/reference/cli/docker/login/#credential-stores
- https://www.passwordstore.org/
Setup guide
Repeat these steps on each machine.
1. Install dependencies
sudo apt-get install -y pass gnupg2 golang-docker-credential-helpers
2. Generate a GPG key
gpg --full-generate-key
Choose RSA, 4096 bits, no expiry. Set a strong passphrase.
3. Get the key ID
gpg --list-secret-keys --keyid-format LONG
Copy the hex string after the / on the sec line.
4. Initialise pass
pass init <your-key-id>
5. Update ~/.docker/config.json
Replace the entire file contents with:
{
"credsStore": "pass"
}
6. Re-login to registries
docker login git.lilastudy.com
# dev laptop only:
docker login dhi.io
7. Verify
cat ~/.docker/config.json
Should show only "credsStore": "pass" with no auths block.