evan.jarrett.net
A container registry that uses the AT Protocol for manifest storage and S3 for blob storage.
atcr.io
docker
container
atproto
go
1# Distribution Strategy for ATCR Credential Helper
2
3## Overview
4
5The ATCR credential helper is distributed as pre-built binaries for all major platforms using GoReleaser and GitHub Actions. This document outlines the complete distribution pipeline.
6
7## Why Go is Ideal for Credential Helpers
8
9Go is actually the **perfect choice** for Docker credential helpers:
10
111. **Cross-compilation** - Single command builds for all platforms
122. **Static binaries** - No runtime dependencies (unlike Node.js, Python, Ruby)
133. **Industry standard** - Most Docker credential helpers are written in Go:
14 - docker-credential-helpers (official)
15 - docker-credential-gcr (Google)
16 - docker-credential-ecr-login (AWS)
17 - docker-credential-pass (community)
18
19## Supported Platforms
20
21| Platform | Arch | Format | Status |
22|----------|------|--------|--------|
23| Linux | amd64 | tar.gz | ✅ |
24| Linux | arm64 | tar.gz | ✅ |
25| macOS | amd64 (Intel) | tar.gz | ✅ |
26| macOS | arm64 (Apple Silicon) | tar.gz | ✅ |
27| Windows | amd64 | zip | ✅ |
28| Windows | arm64 | zip | ✅ |
29
30## Distribution Methods
31
32### 1. GitHub Releases (Automated)
33
34**Trigger:** Push a git tag (e.g., `v1.0.0`)
35
36```bash
37git tag v1.0.0
38git push origin v1.0.0
39```
40
41**What happens:**
421. GitHub Actions runs (`.github/workflows/release.yml`)
432. GoReleaser builds binaries for all platforms
443. Creates GitHub release with:
45 - Pre-built binaries (tar.gz/zip)
46 - Checksums file
47 - Changelog
484. Updates Homebrew tap (if configured)
49
50**Workflow file:** `.github/workflows/release.yml`
51**Config file:** `.goreleaser.yaml`
52
53### 2. Install Scripts
54
55**Linux/macOS:** `install.sh`
56- Detects OS and architecture
57- Downloads latest release from GitHub
58- Installs to `/usr/local/bin` (or custom dir)
59- Makes executable and verifies installation
60
61**Windows:** `install.ps1`
62- Detects architecture
63- Downloads latest release
64- Installs to `C:\Program Files\ATCR` (or custom dir)
65- Adds to system PATH
66- Requires Administrator privileges
67
68**Usage:**
69```bash
70# Linux/macOS
71curl -fsSL https://atcr.io/install.sh | bash
72
73# Windows (PowerShell)
74iwr -useb https://atcr.io/install.ps1 | iex
75```
76
77### 3. Homebrew (macOS)
78
79**Setup required:**
801. Create `atcr-io/homebrew-tap` repository
812. Set `HOMEBREW_TAP_TOKEN` secret in GitHub Actions
823. GoReleaser automatically updates formula on release
83
84**Usage:**
85```bash
86brew tap atcr-io/tap
87brew install docker-credential-atcr
88```
89
90**Benefits:**
91- Automatic updates via `brew upgrade`
92- Handles PATH configuration
93- Native macOS experience
94
95### 4. Manual Download
96
97Users can download directly from GitHub Releases:
98
99```bash
100# Example: Linux amd64
101VERSION=v1.0.0
102curl -LO https://github.com/atcr-io/atcr/releases/download/${VERSION}/docker-credential-atcr_${VERSION#v}_Linux_x86_64.tar.gz
103tar -xzf docker-credential-atcr_${VERSION#v}_Linux_x86_64.tar.gz
104sudo install -m 755 docker-credential-atcr /usr/local/bin/
105```
106
107### 5. From Source
108
109For users with Go installed:
110
111```bash
112go install atcr.io/cmd/credential-helper@latest
113sudo mv $(go env GOPATH)/bin/credential-helper /usr/local/bin/docker-credential-atcr
114```
115
116**Note:** This requires Go 1.23+ and compiles locally.
117
118## Release Process
119
120### Creating a New Release
121
1221. **Update version** (if using version consts anywhere)
123
1242. **Commit and tag:**
125 ```bash
126 git add .
127 git commit -m "Release v1.0.0"
128 git tag -a v1.0.0 -m "Release v1.0.0"
129 git push origin main
130 git push origin v1.0.0
131 ```
132
1333. **Wait for CI:**
134 - GitHub Actions builds and releases automatically
135 - Check: https://github.com/atcr-io/atcr/actions
136
1374. **Verify release:**
138 - Visit: https://github.com/atcr-io/atcr/releases
139 - Test install script:
140 ```bash
141 ATCR_VERSION=v1.0.0 curl -fsSL https://atcr.io/install.sh | bash
142 docker-credential-atcr version
143 ```
144
145### Version Information
146
147GoReleaser injects version info at build time:
148
149```go
150var (
151 version = "dev" // Set to tag (e.g., "v1.0.0")
152 commit = "none" // Set to git commit hash
153 date = "unknown" // Set to build timestamp
154)
155```
156
157Usage:
158```bash
159$ docker-credential-atcr version
160docker-credential-atcr v1.0.0 (commit: abc123, built: 2025-01-15T10:30:00Z)
161```
162
163## Distribution Configuration
164
165### GoReleaser Config (`.goreleaser.yaml`)
166
167Key sections:
168
169**Builds:**
170- Binary name: `docker-credential-atcr` (Windows: `.exe` auto-added)
171- Targets: Linux, macOS, Windows (amd64, arm64)
172- CGO disabled for static binaries
173- Ldflags inject version info
174
175**Archives:**
176- Format: tar.gz (Linux/macOS), zip (Windows)
177- Naming: `docker-credential-atcr_VERSION_OS_ARCH.tar.gz`
178- Includes: LICENSE, README, INSTALLATION.md
179
180**Homebrew:**
181- Auto-updates tap repository
182- Formula includes version check
183- Installs to Homebrew prefix
184
185**Changelog:**
186- Auto-generated from commits
187- Filters out docs/test/chore commits
188
189## Docker and Docker Desktop
190
191### How Docker Finds Credential Helpers
192
193Docker looks for binaries named `docker-credential-*` in PATH:
194
1951. User types: `docker push atcr.io/alice/app:latest`
1962. Docker reads `~/.docker/config.json`:
197 ```json
198 {
199 "credHelpers": {
200 "atcr.io": "atcr"
201 }
202 }
203 ```
2043. Docker looks for `docker-credential-atcr` in PATH
2054. Calls: `docker-credential-atcr get` (with `atcr.io` on stdin)
2065. Helper returns credentials (JSON on stdout)
207
208### PATH Requirements
209
210**Linux/macOS:**
211- Common locations: `/usr/local/bin`, `/usr/bin`, `$HOME/.local/bin`
212- Check with: `which docker-credential-atcr`
213
214**Windows:**
215- Common locations: `C:\Windows\System32`, `C:\Program Files\ATCR`
216- Check with: `where docker-credential-atcr`
217
218## CI/CD Secrets
219
220### Required GitHub Secrets
221
2221. **`GITHUB_TOKEN`** (automatic)
223 - Provided by GitHub Actions
224 - Used to create releases
225
2262. **`HOMEBREW_TAP_TOKEN`** (manual setup)
227 - Personal access token with `repo` scope
228 - Used to update Homebrew tap
229 - Can skip if not using Homebrew
230
231### Setup Instructions
232
233```bash
234# Create PAT with repo scope at:
235# https://github.com/settings/tokens
236
237# Add to repository secrets:
238# https://github.com/atcr-io/atcr/settings/secrets/actions
239```
240
241## Testing the Distribution
242
243### Before Tagging a Release
244
2451. **Test GoReleaser locally:**
246 ```bash
247 goreleaser build --snapshot --clean
248 ls dist/
249 ```
250
2512. **Test specific platform:**
252 ```bash
253 goreleaser build --snapshot --clean --single-target
254 ./dist/docker-credential-atcr_*/docker-credential-atcr version
255 ```
256
2573. **Test full release (dry run):**
258 ```bash
259 goreleaser release --snapshot --clean --skip=publish
260 ```
261
262### After Release
263
2641. **Test install script:**
265 ```bash
266 # Clean install in fresh environment
267 docker run --rm -it ubuntu:latest bash
268 apt update && apt install -y curl
269 curl -fsSL https://atcr.io/install.sh | bash
270 ```
271
2722. **Test Docker integration:**
273 ```bash
274 echo '{"credHelpers":{"atcr.io":"atcr"}}' > ~/.docker/config.json
275 docker push atcr.io/test/image:latest
276 ```
277
278## Future Enhancements
279
280### Package Managers
281
282**Linux:**
283- `.deb` packages for Debian/Ubuntu (via GoReleaser)
284- `.rpm` packages for RHEL/Fedora/CentOS
285- AUR package for Arch Linux
286
287**macOS:**
288- Official Homebrew core (requires popularity/maturity)
289
290**Windows:**
291- Chocolatey package
292- Scoop manifest
293- Winget package
294
295### Docker Distribution
296
297Could also distribute the credential helper via container:
298
299```bash
300docker run --rm atcr.io/credential-helper:latest version
301
302# Install from container
303docker run --rm -v /usr/local/bin:/install \
304 atcr.io/credential-helper:latest \
305 cp /usr/local/bin/docker-credential-atcr /install/
306```
307
308**Note:** Not recommended as primary method (users want native binaries), but useful for CI/CD pipelines.
309
310## Troubleshooting
311
312### "Binary not in PATH"
313
314**Symptom:** `docker push` fails with "credential helper not found"
315
316**Solution:**
317```bash
318# Check if installed
319which docker-credential-atcr
320# or on Windows:
321where docker-credential-atcr
322
323# If not in PATH, add install dir to PATH
324export PATH="/usr/local/bin:$PATH" # Linux/macOS
325# or add to ~/.bashrc, ~/.zshrc
326```
327
328### "Permission denied"
329
330**Symptom:** Can't execute binary
331
332**Solution:**
333```bash
334chmod +x /usr/local/bin/docker-credential-atcr
335```
336
337### "Wrong architecture"
338
339**Symptom:** `exec format error` or `bad CPU type`
340
341**Solution:** Download correct architecture:
342- x86_64/amd64 for Intel/AMD
343- arm64/aarch64 for Apple Silicon, ARM servers
344
345Check with:
346```bash
347uname -m
348```
349
350## Documentation
351
352- **User installation:** [INSTALLATION.md](../INSTALLATION.md)
353- **Project docs:** [CLAUDE.md](../CLAUDE.md)
354- **README:** [README.md](../README.md)
355
356## References
357
358- [Docker Credential Helpers Spec](https://github.com/docker/docker-credential-helpers)
359- [GoReleaser Documentation](https://goreleaser.com)
360- [GitHub Actions: Publishing](https://docs.github.com/en/actions/publishing-packages)