diff --git a/documentation/tickets/t00001.md b/documentation/tickets/t00001.md index d15f242..4fffaec 100644 --- a/documentation/tickets/t00001.md +++ b/documentation/tickets/t00001.md @@ -1,49 +1,52 @@ # 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. + +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. + +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. + +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. + +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 +- 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/ + +- [docker docs](https://docs.docker.com/reference/cli/docker/login/#credential-stores) +- [pass docs](https://www.passwordstore.org/) --- @@ -52,29 +55,37 @@ Same limitations as Option B. 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 ``` ### 5. Update `~/.docker/config.json` + Replace the entire file contents with: + ```json { "credsStore": "pass" @@ -82,6 +93,7 @@ Replace the entire file contents with: ``` ### 6. Re-login to registries + ```bash docker login git.lilastudy.com # dev laptop only: @@ -89,7 +101,9 @@ docker login dhi.io ``` ### 7. Verify + ```bash cat ~/.docker/config.json ``` + Should show only `"credsStore": "pass"` with no `auths` block.