at-container-registry/INSTALLATION.md

# Installing ATCR Credential Helper

The ATCR credential helper enables Docker to authenticate with ATCR registries using ATProto device authorization.

## Quick Install (Recommended)

### Using install script

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

Or download and run manually:

```bash
curl -fsSLO https://atcr.io/install.sh
chmod +x install.sh
./install.sh
```

Custom installation directory:

```bash
INSTALL_DIR=$HOME/.local/bin curl -fsSL https://atcr.io/install.sh | bash
```

**Windows (PowerShell as Administrator):**
```powershell
iwr -useb https://atcr.io/install.ps1 | iex
```

Or download and run manually:

```powershell
Invoke-WebRequest -Uri https://atcr.io/install.ps1 -OutFile install.ps1
.\install.ps1
```

### Using Homebrew (macOS)
You can read the full manifest spec here, but the dependencies block is the real interesting bit. Dependencies for your workflow, like Go, Node.js, Python etc. can be pulled in from nixpkgs. Nixpkgs—for the uninitiated—is a vast collection of packages for the Nix package manager. Fortunately, you needn’t know nor care about Nix to use it! Just head to https://search.nixos.org to find your package of choice (I’ll bet 1€ that it’s there1), toss it in the list and run your build. The Nix-savvy of you lot will be happy to know that you can use custom registries too.
```bash
brew tap atcr-io/tap
brew install docker-credential-atcr
```

### Manual Installation

1. **Download the binary** for your platform from [GitHub Releases](https://github.com/atcr-io/atcr/releases)

   - Linux amd64: `docker-credential-atcr_VERSION_Linux_x86_64.tar.gz`
   - Linux arm64: `docker-credential-atcr_VERSION_Linux_arm64.tar.gz`
   - macOS amd64: `docker-credential-atcr_VERSION_Darwin_x86_64.tar.gz`
   - macOS arm64: `docker-credential-atcr_VERSION_Darwin_arm64.tar.gz`
   - Windows amd64: `docker-credential-atcr_VERSION_Windows_x86_64.zip`
   - Windows arm64: `docker-credential-atcr_VERSION_Windows_arm64.zip`

2. **Extract and install**:

   **Linux/macOS:**
   ```bash
   tar -xzf docker-credential-atcr_VERSION_OS_ARCH.tar.gz
   sudo install -m 755 docker-credential-atcr /usr/local/bin/
   ```

   **Windows (PowerShell as Administrator):**
   ```powershell
   Expand-Archive docker-credential-atcr_VERSION_Windows_x86_64.zip
   Move-Item docker-credential-atcr.exe C:\Windows\System32\
   ```

3. **Verify installation**:

   ```bash
   docker-credential-atcr version
   ```

### From Source (requires Go 1.23+)

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

## Configuration

### 1. Configure Docker

Add the credential helper to Docker's config:

```bash
# Create or edit ~/.docker/config.json
cat > ~/.docker/config.json << 'EOF'
{
  "credHelpers": {
    "atcr.io": "atcr"
  }
}
EOF
```

Or add to existing config:

```json
{
  "credHelpers": {
    "atcr.io": "atcr",
    "docker.io": "desktop"
  }
}
```

### 2. Authenticate

The credential helper will automatically trigger authentication when you first push/pull:

```bash
docker push atcr.io/yourhandle/myapp:latest
```

This will:
1. Open your browser for device authorization
2. Display a code to confirm
3. Store credentials in `~/.atcr/device.json`
4. Exchange for registry JWT and proceed with push

### 3. Manual Authentication (optional)

If you prefer to authenticate before pushing:

```bash
# This triggers the device flow manually
echo "atcr.io" | ATCR_AUTO_AUTH=1 docker-credential-atcr get > /dev/null
```

## Usage

Once configured, Docker commands work normally:

```bash
# Push image
docker push atcr.io/alice.bsky.social/myapp:latest

# Pull image
docker pull atcr.io/bob.bsky.social/coolapp:v1.2.3

# Build and push
docker build -t atcr.io/alice.bsky.social/web:latest .
docker push atcr.io/alice.bsky.social/web:latest
```

## Multiple Registries

The credential helper supports multiple ATCR instances (e.g., production + self-hosted):

```json
{
  "credHelpers": {
    "atcr.io": "atcr",
    "registry.mycompany.com": "atcr"
  }
}
```

Credentials are stored per AppView URL in `~/.atcr/device.json`.

## Troubleshooting

### "credential helper not found"

Ensure `docker-credential-atcr` is in your PATH:

```bash
which docker-credential-atcr
```

If not found, add the installation directory to PATH:

```bash
export PATH="/usr/local/bin:$PATH"
```

### "No valid credentials found"

Enable auto-auth and retry:

```bash
docker push atcr.io/yourhandle/myapp:latest
```

### "authorization failed"

Check that you can access the AppView:

```bash
curl -v https://atcr.io/v2/
```

For local development (HTTP):

```json
{
  "insecure-registries": ["localhost:5000"]
}
```

Add to `/etc/docker/daemon.json` and restart Docker:

```bash
sudo systemctl restart docker
```

### Logout

To remove stored credentials:

```bash
echo "atcr.io" | docker-credential-atcr erase
```

Or delete the credentials file:

```bash
rm ~/.atcr/device.json
```

## Uninstall

```bash
# Remove binary
sudo rm /usr/local/bin/docker-credential-atcr

# Remove credentials
rm -rf ~/.atcr

# Remove from Docker config
# Edit ~/.docker/config.json and remove "atcr" from credHelpers
```

## Platform Support

| Platform | Arch | Status |
|----------|------|--------|
| Linux | amd64 | ✅ Supported |
| Linux | arm64 | ✅ Supported |
| macOS | amd64 (Intel) | ✅ Supported |
| macOS | arm64 (Apple Silicon) | ✅ Supported |
| Windows | amd64 | ✅ Supported |
| Windows | arm64 | ✅ Supported |

## Security

- Credentials are stored in `~/.atcr/device.json` with `0600` permissions (owner read/write only)
- Device secrets are issued per-device and can be revoked via the AppView web UI
- Authentication uses ATProto OAuth with device authorization flow
- No passwords are stored locally

## Development

See [CLAUDE.md](./CLAUDE.md#credential-helper-cmd-credential-helper) for development docs.