formatting

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 
+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.
-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` 
+Uses the desktop keyring daemon. Not suitable for a headless VPS, and not suitable for an i3 desktop without running `gnome-keyring-daemon` manually.
-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 <your-key-id>
 ```
 
 ### 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.