at-container-registry/docs/DISTRIBUTION.md

# Distribution Strategy for ATCR Credential Helper

## Overview

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

## Why Go is Ideal for Credential Helpers

Go is actually the **perfect choice** for Docker credential helpers:

1. **Cross-compilation** - Single command builds for all platforms
2. **Static binaries** - No runtime dependencies (unlike Node.js, Python, Ruby)
3. **Industry standard** - Most Docker credential helpers are written in Go:
   - docker-credential-helpers (official)
   - docker-credential-gcr (Google)
   - docker-credential-ecr-login (AWS)
   - docker-credential-pass (community)

## Supported Platforms

| Platform | Arch | Format | Status |
|----------|------|--------|--------|
| Linux | amd64 | tar.gz | ✅ |
| Linux | arm64 | tar.gz | ✅ |
| macOS | amd64 (Intel) | tar.gz | ✅ |
| macOS | arm64 (Apple Silicon) | tar.gz | ✅ |
| Windows | amd64 | zip | ✅ |
| Windows | arm64 | zip | ✅ |

## Distribution Methods

### 1. GitHub Releases (Automated)

**Trigger:** Push a git tag (e.g., `v1.0.0`)

```bash
git tag v1.0.0
git push origin v1.0.0
```

**What happens:**
1. GitHub Actions runs (`.github/workflows/release.yml`)
2. GoReleaser builds binaries for all platforms
3. Creates GitHub release with:
   - Pre-built binaries (tar.gz/zip)
   - Checksums file
   - Changelog
4. Updates Homebrew tap (if configured)

**Workflow file:** `.github/workflows/release.yml`
**Config file:** `.goreleaser.yaml`

### 2. Install Scripts

**Linux/macOS:** `install.sh`
- Detects OS and architecture
- Downloads latest release from GitHub
- Installs to `/usr/local/bin` (or custom dir)
- Makes executable and verifies installation

**Windows:** `install.ps1`
- Detects architecture
- Downloads latest release
- Installs to `C:\Program Files\ATCR` (or custom dir)
- Adds to system PATH
- Requires Administrator privileges

**Usage:**
```bash
# Linux/macOS
curl -fsSL https://atcr.io/install.sh | bash

# Windows (PowerShell)
iwr -useb https://atcr.io/install.ps1 | iex
```

### 3. Homebrew (macOS)

**Setup required:**
1. Create `atcr-io/homebrew-tap` repository
2. Set `HOMEBREW_TAP_TOKEN` secret in GitHub Actions
3. GoReleaser automatically updates formula on release

**Usage:**
```bash
brew tap atcr-io/tap
brew install docker-credential-atcr
```

**Benefits:**
- Automatic updates via `brew upgrade`
- Handles PATH configuration
- Native macOS experience

### 4. Manual Download

Users can download directly from GitHub Releases:

```bash
# Example: Linux amd64
VERSION=v1.0.0
curl -LO https://github.com/atcr-io/atcr/releases/download/${VERSION}/docker-credential-atcr_${VERSION#v}_Linux_x86_64.tar.gz
tar -xzf docker-credential-atcr_${VERSION#v}_Linux_x86_64.tar.gz
sudo install -m 755 docker-credential-atcr /usr/local/bin/
```

### 5. From Source

For users with Go installed:

```bash
go install atcr.io/cmd/credential-helper@latest
sudo mv $(go env GOPATH)/bin/credential-helper /usr/local/bin/docker-credential-atcr
```

**Note:** This requires Go 1.23+ and compiles locally.

## Release Process

### Creating a New Release

1. **Update version** (if using version consts anywhere)

2. **Commit and tag:**
   ```bash
   git add .
   git commit -m "Release v1.0.0"
   git tag -a v1.0.0 -m "Release v1.0.0"
   git push origin main
   git push origin v1.0.0
   ```

3. **Wait for CI:**
   - GitHub Actions builds and releases automatically
   - Check: https://github.com/atcr-io/atcr/actions

4. **Verify release:**
   - Visit: https://github.com/atcr-io/atcr/releases
   - Test install script:
     ```bash
     ATCR_VERSION=v1.0.0 curl -fsSL https://atcr.io/install.sh | bash
     docker-credential-atcr version
     ```

### Version Information

GoReleaser injects version info at build time:

```go
var (
    version = "dev"       // Set to tag (e.g., "v1.0.0")
    commit  = "none"      // Set to git commit hash
    date    = "unknown"   // Set to build timestamp
)
```

Usage:
```bash
$ docker-credential-atcr version
docker-credential-atcr v1.0.0 (commit: abc123, built: 2025-01-15T10:30:00Z)
```

## Distribution Configuration

### GoReleaser Config (`.goreleaser.yaml`)

Key sections:

**Builds:**
- Binary name: `docker-credential-atcr` (Windows: `.exe` auto-added)
- Targets: Linux, macOS, Windows (amd64, arm64)
- CGO disabled for static binaries
- Ldflags inject version info

**Archives:**
- Format: tar.gz (Linux/macOS), zip (Windows)
- Naming: `docker-credential-atcr_VERSION_OS_ARCH.tar.gz`
- Includes: LICENSE, README, INSTALLATION.md

**Homebrew:**
- Auto-updates tap repository
- Formula includes version check
- Installs to Homebrew prefix

**Changelog:**
- Auto-generated from commits
- Filters out docs/test/chore commits

## Docker and Docker Desktop

### How Docker Finds Credential Helpers

Docker looks for binaries named `docker-credential-*` in PATH:

1. User types: `docker push atcr.io/alice/app:latest`
2. Docker reads `~/.docker/config.json`:
   ```json
   {
     "credHelpers": {
       "atcr.io": "atcr"
     }
   }
   ```
3. Docker looks for `docker-credential-atcr` in PATH
4. Calls: `docker-credential-atcr get` (with `atcr.io` on stdin)
5. Helper returns credentials (JSON on stdout)

### PATH Requirements

**Linux/macOS:**
- Common locations: `/usr/local/bin`, `/usr/bin`, `$HOME/.local/bin`
- Check with: `which docker-credential-atcr`

**Windows:**
- Common locations: `C:\Windows\System32`, `C:\Program Files\ATCR`
- Check with: `where docker-credential-atcr`

## CI/CD Secrets

### Required GitHub Secrets

1. **`GITHUB_TOKEN`** (automatic)
   - Provided by GitHub Actions
   - Used to create releases

2. **`HOMEBREW_TAP_TOKEN`** (manual setup)
   - Personal access token with `repo` scope
   - Used to update Homebrew tap
   - Can skip if not using Homebrew

### Setup Instructions

```bash
# Create PAT with repo scope at:
# https://github.com/settings/tokens

# Add to repository secrets:
# https://github.com/atcr-io/atcr/settings/secrets/actions
```

## Testing the Distribution

### Before Tagging a Release

1. **Test GoReleaser locally:**
   ```bash
   goreleaser build --snapshot --clean
   ls dist/
   ```

2. **Test specific platform:**
   ```bash
   goreleaser build --snapshot --clean --single-target
   ./dist/docker-credential-atcr_*/docker-credential-atcr version
   ```

3. **Test full release (dry run):**
   ```bash
   goreleaser release --snapshot --clean --skip=publish
   ```

### After Release

1. **Test install script:**
   ```bash
   # Clean install in fresh environment
   docker run --rm -it ubuntu:latest bash
   apt update && apt install -y curl
   curl -fsSL https://atcr.io/install.sh | bash
   ```

2. **Test Docker integration:**
   ```bash
   echo '{"credHelpers":{"atcr.io":"atcr"}}' > ~/.docker/config.json
   docker push atcr.io/test/image:latest
   ```

## Future Enhancements

### Package Managers

**Linux:**
- `.deb` packages for Debian/Ubuntu (via GoReleaser)
- `.rpm` packages for RHEL/Fedora/CentOS
- AUR package for Arch Linux

**macOS:**
- Official Homebrew core (requires popularity/maturity)

**Windows:**
- Chocolatey package
- Scoop manifest
- Winget package

### Docker Distribution

Could also distribute the credential helper via container:

```bash
docker run --rm atcr.io/credential-helper:latest version

# Install from container
docker run --rm -v /usr/local/bin:/install \
  atcr.io/credential-helper:latest \
  cp /usr/local/bin/docker-credential-atcr /install/
```

**Note:** Not recommended as primary method (users want native binaries), but useful for CI/CD pipelines.

## Troubleshooting

### "Binary not in PATH"

**Symptom:** `docker push` fails with "credential helper not found"

**Solution:**
```bash
# Check if installed
which docker-credential-atcr
# or on Windows:
where docker-credential-atcr

# If not in PATH, add install dir to PATH
export PATH="/usr/local/bin:$PATH"  # Linux/macOS
# or add to ~/.bashrc, ~/.zshrc
```

### "Permission denied"

**Symptom:** Can't execute binary

**Solution:**
```bash
chmod +x /usr/local/bin/docker-credential-atcr
```

### "Wrong architecture"

**Symptom:** `exec format error` or `bad CPU type`

**Solution:** Download correct architecture:
- x86_64/amd64 for Intel/AMD
- arm64/aarch64 for Apple Silicon, ARM servers

Check with:
```bash
uname -m
```

## Documentation

- **User installation:** [INSTALLATION.md](../INSTALLATION.md)
- **Project docs:** [CLAUDE.md](../CLAUDE.md)
- **README:** [README.md](../README.md)

## References

- [Docker Credential Helpers Spec](https://github.com/docker/docker-credential-helpers)
- [GoReleaser Documentation](https://goreleaser.com)
- [GitHub Actions: Publishing](https://docs.github.com/en/actions/publishing-packages)