A container registry that uses the AT Protocol for manifest storage and S3 for blob storage.
atcr.io
docker
container
atproto
go
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**Using Docker Compose:**
81```bash
82cp .env.appview.example .env.appview
83# Edit .env.appview with your configuration
84docker-compose up -d
85```
86
87**Local development:**
88```bash
89# Build
90go build -o bin/atcr-appview ./cmd/appview
91go build -o bin/atcr-hold ./cmd/hold
92
93# Configure
94cp .env.appview.example .env.appview
95# Edit .env.appview - set ATCR_DEFAULT_HOLD
96source .env.appview
97
98# Run
99./bin/atcr-appview serve
100```
101
102See **[deploy/README.md](./deploy/README.md)** for production deployment.
103
104## Development
105
106### Building from Source
107
108```bash
109# Build all binaries
110go build -o bin/atcr-appview ./cmd/appview
111go build -o bin/atcr-hold ./cmd/hold
112go build -o bin/docker-credential-atcr ./cmd/credential-helper
113
114# Run tests
115go test ./...
116go test -race ./...
117```
118
119### Project Structure
120
121```
122cmd/
123├── appview/ # Registry server + web UI
124├── hold/ # Storage service (BYOS)
125└── credential-helper/ # Docker credential helper
126
127pkg/
128├── appview/
129│ ├── db/ # SQLite database (migrations, queries, stores)
130│ ├── handlers/ # HTTP handlers (home, repo, search, auth, settings)
131│ ├── jetstream/ # ATProto Jetstream consumer
132│ ├── middleware/ # Auth & registry middleware
133│ ├── storage/ # Storage routing (hold cache, blob proxy, repository)
134│ ├── static/ # Static assets (JS, CSS, install scripts)
135│ └── templates/ # HTML templates
136├── atproto/ # ATProto client, records, manifest/tag stores
137├── auth/
138│ ├── oauth/ # OAuth client, server, refresher, storage
139│ ├── token/ # JWT issuer, validator, claims
140│ └── atproto/ # Session validation
141└── hold/ # Hold service (authorization, storage, multipart, S3)
142```
143
144## License
145
146MIT
147
148## Contributing
149
150Contributions welcome! Please open an issue or PR.