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 and Linux)

```bash
# Add the ATCR tap
brew tap atcr-io/tap

# Install the credential helper
brew install docker-credential-atcr
```

The Homebrew formula supports:
- **macOS**: Intel (x86_64) and Apple Silicon (arm64)
- **Linux**: x86_64 and arm64

Homebrew will automatically download the correct binary for your platform.

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