ATCR AppView#

The registry frontend component of ATCR (ATProto Container Registry)

Overview#

AppView is the frontend server component of ATCR. It serves as the OCI-compliant registry API endpoint and web interface that Docker clients interact with when pushing and pulling container images.

AppView is the orchestration layer that:

• Serves the OCI Distribution API V2 - Compatible with Docker, containerd, podman, and all OCI clients
• Resolves ATProto identities - Converts handles (alice.bsky.social) and DIDs (did:plc:xyz123) to PDS endpoints
• Routes manifests - Stores container image manifests as ATProto records in users' Personal Data Servers
• Routes blobs - Proxies blob (layer) operations to hold services for S3-compatible storage
• Provides web UI - Browse repositories, search images, view tags, track pull counts, manage stars, vulnerability scan results
• Manages authentication - ATProto OAuth with device authorization flow, issues registry JWTs to Docker clients

The ATCR Ecosystem#

AppView is the frontend of a multi-component architecture:

1. AppView (this component) - Registry API + web interface
2. Hold Service - Storage backend with embedded PDS for blob storage
3. Credential Helper - Client-side tool for ATProto OAuth authentication

Data flow:

Docker Client → AppView (resolves identity) → User's PDS (stores manifest)
                    ↓
              Hold Service (stores blobs in S3/Storj/etc.)

Manifests (small JSON metadata) live in users' ATProto PDS, while blobs (large binary layers) live in hold services. AppView orchestrates the routing between these components.

When to Run Your Own AppView#

Most users can simply use https://atcr.io - you don't need to run your own AppView.

Run your own AppView if you want to:

• Host a private/organizational container registry with ATProto authentication
• Run a public registry for a specific community
• Customize the registry UI or policies
• Maintain full control over registry infrastructure

Prerequisites:

• A running Hold service (required for blob storage)
• (Optional) Domain name with SSL/TLS certificates for production
• (Optional) Access to ATProto Jetstream for real-time indexing

Quick Start#

1. Build the Docker image#

docker build -t atcr-appview:latest -f Dockerfile.appview .

This produces a ~30MB scratch image with a statically-linked binary.

2. Generate a config file#

docker run --rm atcr-appview config init > config-appview.yaml

This creates a fully-commented YAML file with all available options and their defaults. You can also generate it from a local binary:

./bin/atcr-appview config init config-appview.yaml

3. Set the required field#

Edit config-appview.yaml and set server.default_hold_did to your hold service's DID:

server:
  default_hold_did: "did:web:127.0.0.1:8080"  # local dev
  # default_hold_did: "did:web:hold01.example.com"  # production

This is the only required configuration field. To find a hold's DID, visit its /.well-known/did.json endpoint.

For production, also set your public URL:

server:
  base_url: "https://registry.example.com"
  default_hold_did: "did:web:hold01.example.com"

4. Run#

docker run -d \
  -v ./config-appview.yaml:/config.yaml:ro \
  -v atcr-data:/var/lib/atcr \
  -p 5000:5000 \
  atcr-appview serve --config /config.yaml

5. Verify#

curl http://localhost:5000/v2/
# Should return: {}

curl http://localhost:5000/health
# Should return: {"status":"ok"}

Configuration#

AppView uses YAML configuration with environment variable overrides. The generated config-appview.yaml is the canonical reference — every field is commented inline with its purpose and default value.

Config loading priority (highest wins)#

1. Environment variables (ATCR_ prefix)
2. YAML config file (--config)
3. Built-in defaults

Environment variable convention#

YAML paths map to env vars with ATCR_ prefix and _ separators:

server.default_hold_did  →  ATCR_SERVER_DEFAULT_HOLD_DID
server.base_url          →  ATCR_SERVER_BASE_URL
ui.database_path         →  ATCR_UI_DATABASE_PATH
jetstream.backfill_enabled → ATCR_JETSTREAM_BACKFILL_ENABLED

Config sections overview#

Auto-generated files#

On first run, AppView auto-generates these under /var/lib/atcr/:

Persist /var/lib/atcr/ across restarts. Losing the auth keys invalidates all active sessions; losing the database loses OAuth state and UI data.

Deployment#

Docker (recommended)#

Dockerfile.appview builds a minimal scratch image (~30MB) containing:

• Static atcr-appview binary (CGO-enabled with embedded SQLite)
• healthcheck binary for container health checks
• CA certificates and timezone data

Port: 5000 (HTTP)

Volume: /var/lib/atcr (auth keys, database, OAuth keys)

Health check: GET /health returns {"status":"ok"}

docker run -d \
  --name atcr-appview \
  -v ./config-appview.yaml:/config.yaml:ro \
  -v atcr-data:/var/lib/atcr \
  -p 5000:5000 \
  --health-cmd '/healthcheck http://localhost:5000/health' \
  --health-interval 30s \
  --restart unless-stopped \
  atcr-appview serve --config /config.yaml

Production with reverse proxy#

AppView serves HTTP on port 5000. For production, put a reverse proxy in front for HTTPS termination. The repository includes a working Caddy + Docker Compose setup at deploy/docker-compose.prod.yml that runs AppView, Hold, and Caddy together with automatic TLS.

A minimal production compose override:

services:
  atcr-appview:
    image: atcr-appview:latest
    command: ["serve", "--config", "/config.yaml"]
    environment:
      ATCR_SERVER_BASE_URL: https://registry.example.com
      ATCR_SERVER_DEFAULT_HOLD_DID: did:web:hold.example.com
    volumes:
      - ./config-appview.yaml:/config.yaml:ro
      - atcr-appview-data:/var/lib/atcr
    healthcheck:
      test: ["CMD", "/healthcheck", "http://localhost:5000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s

volumes:
  atcr-appview-data:

Systemd (bare metal)#

For non-Docker deployments, see the systemd service templates in deploy/upcloud/ which include security hardening (dedicated user, filesystem protection, private tmp).

Deployment Scenarios#

Public Registry#

Open to all ATProto users:

# config-appview.yaml
server:
  base_url: "https://registry.example.com"
  default_hold_did: "did:web:hold01.example.com"
jetstream:
  backfill_enabled: true

The linked hold service should have server.public: true and registration.allow_all_crew: true.

Private Organizational Registry#

Restricted to crew members only:

# config-appview.yaml
server:
  base_url: "https://registry.internal.example.com"
  default_hold_did: "did:web:hold.internal.example.com"

The linked hold service should have server.public: false and registration.allow_all_crew: false, with an explicit registration.owner_did set to the organization's DID.

Local Development#

# config-appview.yaml
log_level: debug
server:
  default_hold_did: "did:web:127.0.0.1:8080"
  test_mode: true  # allows HTTP for DID resolution

Run a hold service locally with Minio for S3-compatible storage. See hold.md for hold setup.

Web Interface#

The AppView web UI provides:

• Home page - Featured repositories and recent pushes
• Repository pages - Tags, manifests, pull instructions, health status, vulnerability scan results
• Search - Find repositories by owner handle or repository name
• User profiles - View a user's repositories and starred images
• Stars - Favorite repositories (requires login)
• Pull counts - Image pull statistics
• Multi-arch support - Platform-specific manifests (linux/amd64, linux/arm64, etc.)
• Health indicators - Real-time hold service reachability
• Device management - Approve and revoke Docker credential helper pairings
• Settings - Choose default hold, view crew memberships, storage usage