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 user's PDS, blobs to hold services
   - Web interface for browsing/search

2. **Hold Service** - Storage service with embedded PDS (optional BYOS)
   - Each hold has a full ATProto PDS for access control (captain + crew records)
   - Identified by did:web (e.g., `did:web:hold01.atcr.io`)
   - Generates presigned URLs for S3/Storj/Minio/etc.
   - Users can deploy their own storage and control access via crew membership

3. **Credential Helper** - Client authentication
   - ATProto OAuth (DPoP handled transparently)
   - Automatic authentication on first push/pull

**Storage model:**
- Manifests → ATProto records in user's PDS (small JSON, includes `holdDid` reference)
- Blobs → Hold services via XRPC multipart upload (large binaries, stored in S3/etc.)
- AppView uses service tokens to communicate with holds on behalf of users

## Features

- ✅ **OCI-compliant** - Works with Docker, containerd, podman
- ✅ **Decentralized** - You own your manifest data via your PDS
- ✅ **ATProto OAuth** - Secure authentication (DPoP-compliant)
- ✅ **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

```bash
# Build
go build -o bin/atcr-appview ./cmd/appview

# Generate a config file with all defaults
./bin/atcr-appview config init config-appview.yaml
# Edit config-appview.yaml — set server.default_hold_did at minimum

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

**Using Docker:**
```bash
docker build -f Dockerfile.appview -t atcr-appview:latest .
docker run -d -p 5000:5000 \
  -v ./config-appview.yaml:/config.yaml:ro \
  -v atcr-data:/var/lib/atcr \
  atcr-appview:latest serve --config /config.yaml
```

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

### Running Your Own Hold (BYOS Storage)

See **[docs/hold.md](./docs/hold.md)** for deploying your own storage backend.

## 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
├── oauth-helper/      # OAuth debug tool
├── healthcheck/       # HTTP health check (for Docker)
├── db-migrate/        # SQLite → libsql migration
├── usage-report/      # Hold storage usage report
├── record-query/      # Query ATProto relay by collection
└── s3-test/           # S3 connectivity test

pkg/
├── appview/
│   ├── db/            # SQLite database (migrations, queries, stores)
│   ├── handlers/      # HTTP handlers (home, repo, search, auth, settings)
│   ├── holdhealth/    # Hold service health checker
│   ├── jetstream/     # ATProto Jetstream consumer
│   ├── middleware/    # Auth & registry middleware
│   ├── ogcard/        # OpenGraph image generation
│   ├── readme/        # Repository README fetcher
│   ├── routes/        # HTTP route registration
│   ├── storage/       # Storage routing (blob proxy, manifest store)
│   ├── public/        # Static assets (JS, CSS, install scripts)
│   └── templates/     # HTML templates
├── atproto/           # ATProto client, records, manifest/tag stores
├── auth/
│   ├── oauth/         # OAuth client, refresher, storage
│   ├── token/         # JWT issuer, validator, claims
│   └── holdlocal/     # Local hold authorization
├── config/            # Config marshaling (commented YAML)
├── hold/
│   ├── admin/         # Admin web UI
│   ├── billing/       # Stripe billing integration
│   ├── db/            # Vendored carstore (go-libsql)
│   ├── gc/            # Garbage collection
│   ├── oci/           # OCI upload endpoints
│   ├── pds/           # Embedded PDS (DID, captain, crew, stats, scans)
│   └── quota/         # Storage quotas
├── logging/           # Structured logging + remote shipping
└── s3/                # S3 client utilities
```

## License

MIT

## Contributing

Contributions welcome! Please open an issue or PR.