at-container-registry/README.md

# ATCR - ATProto Container Registry

## https://atcr.io

An OCI-compliant container registry that uses the AT Protocol for manifest storage and S3 for blob storage.

## What is ATCR?

ATCR integrates container registries with the AT Protocol ecosystem. Container image manifests are stored as ATProto records in your Personal Data Server (PDS), while layers are stored in S3-compatible storage.

**Image names use your ATProto identity:**
```
atcr.io/alice.bsky.social/myapp:latest
atcr.io/did:plc:xyz123/myapp:latest
```

## Architecture

**Three components:**

1. **AppView** - Registry API + web UI
   - Serves OCI Distribution API (Docker push/pull)
   - Resolves handles/DIDs to PDS endpoints
   - Routes manifests to PDS, blobs to storage
   - Web interface for browsing/search

2. **Hold Service** - Storage service (optional BYOS)
   - Generates presigned URLs for S3/Storj/Minio/etc.
   - Users can deploy their own storage

3. **Credential Helper** - Client authentication
   - ATProto OAuth with DPoP
   - Automatic authentication on first push/pull

**Storage model:**
- Manifests → ATProto records (small JSON)
- Blobs → S3 or BYOS (large binaries)

## Features

- ✅ **OCI-compliant** - Works with Docker, containerd, podman
- ✅ **Decentralized** - You own your manifest data via your PDS
- ✅ **ATProto OAuth** - Secure authentication with DPoP
- ✅ **BYOS** - Deploy your own storage service
- ✅ **Web UI** - Browse, search, star repositories
- ✅ **Multi-backend** - S3, Storj, Minio, Azure, GCS, filesystem

## Quick Start

### Using the Registry

**1. Install credential helper:**
```bash
curl -fsSL https://atcr.io/install.sh | bash
```

**2. Configure Docker** (add to `~/.docker/config.json`):
```json
{
  "credHelpers": {
    "atcr.io": "atcr"
  }
}
```

**3. Push/pull images:**
```bash
docker tag myapp:latest atcr.io/yourhandle/myapp:latest
docker push atcr.io/yourhandle/myapp:latest  # Authenticates automatically
docker pull atcr.io/yourhandle/myapp:latest
```

See **[INSTALLATION.md](./INSTALLATION.md)** for detailed installation instructions.

### Running Your Own AppView

**Using Docker Compose:**
```bash
cp .env.appview.example .env.appview
# Edit .env.appview with your configuration
docker-compose up -d
```

**Local development:**
```bash
# Build
go build -o bin/atcr-appview ./cmd/appview
go build -o bin/atcr-hold ./cmd/hold

# Configure
cp .env.appview.example .env.appview
# Edit .env.appview - set ATCR_DEFAULT_HOLD
source .env.appview

# Run
./bin/atcr-appview serve
```

See **[deploy/README.md](./deploy/README.md)** for production deployment.

## Development

### Building from Source

```bash
# Build all binaries
go build -o bin/atcr-appview ./cmd/appview
go build -o bin/atcr-hold ./cmd/hold
go build -o bin/docker-credential-atcr ./cmd/credential-helper

# Run tests
go test ./...
go test -race ./...
```

### Project Structure

```
cmd/
├── appview/           # Registry server + web UI
├── hold/              # Storage service (BYOS)
└── credential-helper/ # Docker credential helper

pkg/
├── appview/
│   ├── db/            # SQLite database (migrations, queries, stores)
│   ├── handlers/      # HTTP handlers (home, repo, search, auth, settings)
│   ├── jetstream/     # ATProto Jetstream consumer
│   ├── middleware/    # Auth & registry middleware
│   ├── storage/       # Storage routing (hold cache, blob proxy, repository)
│   ├── static/        # Static assets (JS, CSS, install scripts)
│   └── templates/     # HTML templates
├── atproto/           # ATProto client, records, manifest/tag stores
├── auth/
│   ├── oauth/         # OAuth client, server, refresher, storage
│   ├── token/         # JWT issuer, validator, claims
│   └── atproto/       # Session validation
└── hold/              # Hold service (authorization, storage, multipart, S3)
```

## License

MIT

## Contributing

Contributions welcome! Please open an issue or PR.