107 lines
2.2 KiB
Markdown
107 lines
2.2 KiB
Markdown
# 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
|
|
|
|
- [docker docs](https://docs.docker.com/reference/cli/docker/login/#credential-stores)
|
|
- [pass docs](https://www.passwordstore.org/)
|
|
|
|
---
|
|
|
|
## Setup guide
|
|
|
|
Repeat these steps on each machine.
|
|
|
|
### 1. Install dependencies
|
|
|
|
```bash
|
|
sudo apt-get install -y pass gnupg2 golang-docker-credential-helpers
|
|
```
|
|
|
|
### 2. Generate a GPG key
|
|
|
|
```bash
|
|
gpg --full-generate-key
|
|
```
|
|
|
|
Choose RSA, 4096 bits, no expiry. Set a strong passphrase.
|
|
|
|
### 3. Get the key ID
|
|
|
|
```bash
|
|
gpg --list-secret-keys --keyid-format LONG
|
|
```
|
|
|
|
Copy the hex string after the `/` on the `sec` line.
|
|
|
|
### 4. Initialise pass
|
|
|
|
```bash
|
|
pass init <your-key-id>
|
|
```
|
|
|
|
### 5. Update `~/.docker/config.json`
|
|
|
|
Replace the entire file contents with:
|
|
|
|
```json
|
|
{ "credsStore": "pass" }
|
|
```
|
|
|
|
### 6. Re-login to registries
|
|
|
|
```bash
|
|
docker login git.lilastudy.com
|
|
# dev laptop only:
|
|
docker login dhi.io
|
|
```
|
|
|
|
### 7. Verify
|
|
|
|
```bash
|
|
cat ~/.docker/config.json
|
|
```
|
|
|
|
Should show only `"credsStore": "pass"` with no `auths` block.
|