A container registry that uses the AT Protocol for manifest storage and S3 for blob storage.
1# ATCR - ATProto Container Registry
2
3## https://atcr.io
4
5An OCI-compliant container registry that uses the AT Protocol for manifest storage and S3 for blob storage.
6
7## What is ATCR?
8
9ATCR 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.
10
11**Image names use your ATProto identity:**
12```
13atcr.io/alice.bsky.social/myapp:latest
14atcr.io/did:plc:xyz123/myapp:latest
15```
16
17## Architecture
18
19**Three components:**
20
211. **AppView** - Registry API + web UI
22 - Serves OCI Distribution API (Docker push/pull)
23 - Resolves handles/DIDs to PDS endpoints
24 - Routes manifests to user's PDS, blobs to hold services
25 - Web interface for browsing/search
26
272. **Hold Service** - Storage service with embedded PDS (optional BYOS)
28 - Each hold has a full ATProto PDS for access control (captain + crew records)
29 - Identified by did:web (e.g., `did:web:hold01.atcr.io`)
30 - Generates presigned URLs for S3/Storj/Minio/etc.
31 - Users can deploy their own storage and control access via crew membership
32
333. **Credential Helper** - Client authentication
34 - ATProto OAuth (DPoP handled transparently)
35 - Automatic authentication on first push/pull
36
37**Storage model:**
38- Manifests → ATProto records in user's PDS (small JSON, includes `holdDid` reference)
39- Blobs → Hold services via XRPC multipart upload (large binaries, stored in S3/etc.)
40- AppView uses service tokens to communicate with holds on behalf of users
41
42## Features
43
44- ✅ **OCI-compliant** - Works with Docker, containerd, podman
45- ✅ **Decentralized** - You own your manifest data via your PDS
46- ✅ **ATProto OAuth** - Secure authentication (DPoP-compliant)
47- ✅ **BYOS** - Deploy your own storage service
48- ✅ **Web UI** - Browse, search, star repositories
49- ✅ **Multi-backend** - S3, Storj, Minio, Azure, GCS, filesystem
50
51## Quick Start
52
53### Using the Registry
54
55**1. Install credential helper:**
56```bash
57curl -fsSL https://atcr.io/install.sh | bash
58```
59
60**2. Configure Docker** (add to `~/.docker/config.json`):
61```json
62{
63 "credHelpers": {
64 "atcr.io": "atcr"
65 }
66}
67```
68
69**3. Push/pull images:**
70```bash
71docker tag myapp:latest atcr.io/yourhandle/myapp:latest
72docker push atcr.io/yourhandle/myapp:latest # Authenticates automatically
73docker pull atcr.io/yourhandle/myapp:latest
74```
75
76See **[INSTALLATION.md](./INSTALLATION.md)** for detailed installation instructions.
77
78### Running Your Own AppView
79
80```bash
81# Build
82go build -o bin/atcr-appview ./cmd/appview
83
84# Generate a config file with all defaults
85./bin/atcr-appview config init config-appview.yaml
86# Edit config-appview.yaml — set server.default_hold_did at minimum
87
88# Run
89./bin/atcr-appview serve --config config-appview.yaml
90```
91
92**Using Docker:**
93```bash
94docker build -f Dockerfile.appview -t atcr-appview:latest .
95docker run -d -p 5000:5000 \
96 -v ./config-appview.yaml:/config.yaml:ro \
97 -v atcr-data:/var/lib/atcr \
98 atcr-appview:latest serve --config /config.yaml
99```
100
101See **[deploy/README.md](./deploy/README.md)** for production deployment.
102
103### Running Your Own Hold (BYOS Storage)
104
105See **[docs/hold.md](./docs/hold.md)** for deploying your own storage backend.
106
107## Development
108
109### Building from Source
110
111```bash
112# Build all binaries
113go build -o bin/atcr-appview ./cmd/appview
114go build -o bin/atcr-hold ./cmd/hold
115go build -o bin/docker-credential-atcr ./cmd/credential-helper
116
117# Run tests
118go test ./...
119go test -race ./...
120```
121
122### Project Structure
123
124```
125cmd/
126├── appview/ # Registry server + web UI
127├── hold/ # Storage service (BYOS)
128├── credential-helper/ # Docker credential helper
129├── oauth-helper/ # OAuth debug tool
130├── healthcheck/ # HTTP health check (for Docker)
131├── db-migrate/ # SQLite → libsql migration
132├── usage-report/ # Hold storage usage report
133├── record-query/ # Query ATProto relay by collection
134└── s3-test/ # S3 connectivity test
135
136pkg/
137├── appview/
138│ ├── db/ # SQLite database (migrations, queries, stores)
139│ ├── handlers/ # HTTP handlers (home, repo, search, auth, settings)
140│ ├── holdhealth/ # Hold service health checker
141│ ├── jetstream/ # ATProto Jetstream consumer
142│ ├── middleware/ # Auth & registry middleware
143│ ├── ogcard/ # OpenGraph image generation
144│ ├── readme/ # Repository README fetcher
145│ ├── routes/ # HTTP route registration
146│ ├── storage/ # Storage routing (blob proxy, manifest store)
147│ ├── public/ # Static assets (JS, CSS, install scripts)
148│ └── templates/ # HTML templates
149├── atproto/ # ATProto client, records, manifest/tag stores
150├── auth/
151│ ├── oauth/ # OAuth client, refresher, storage
152│ ├── token/ # JWT issuer, validator, claims
153│ └── holdlocal/ # Local hold authorization
154├── config/ # Config marshaling (commented YAML)
155├── hold/
156│ ├── admin/ # Admin web UI
157│ ├── billing/ # Stripe billing integration
158│ ├── db/ # Vendored carstore (go-libsql)
159│ ├── gc/ # Garbage collection
160│ ├── oci/ # OCI upload endpoints
161│ ├── pds/ # Embedded PDS (DID, captain, crew, stats, scans)
162│ └── quota/ # Storage quotas
163├── logging/ # Structured logging + remote shipping
164└── s3/ # S3 client utilities
165```
166
167## License
168
169MIT
170
171## Contributing
172
173Contributions welcome! Please open an issue or PR.