# 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.