NebulaCR — Cloud-Native OCI Container Registry

Everything You Need for Container Images

From development to production, NebulaCR covers the entire container image lifecycle.

📦

OCI Distribution API

Full implementation of the OCI Distribution Specification. Compatible with Docker, Podman, Buildah, containerd, and any OCI-compliant client.

Manifest push/pull/delete (v2 schema)
Chunked and monolithic blob uploads
Multi-tenant with tenant/project/repo hierarchy
Tag listing and catalog API
Content-addressable storage by digest

🌍

Multi-Region Replication

Async replication of manifests and blobs across regions. Circuit breaker and retry logic ensure resilience during network partitions.

Async event-driven replication
Circuit breaker with configurable thresholds
Exponential backoff with jitter
Health check loop with failover
Read failover to healthy regions

🔒

Enterprise Authentication

OIDC Authorization Code flow with PKCE for Azure AD, Okta, and Google. Group-based role mapping, robot accounts, and token rotation.

OIDC/AD SSO with group-to-role mapping
CI/CD OIDC federation (GitHub, GitLab, K8s)
Robot accounts for machine identity
Refresh tokens with revocation
Short-lived JWT tokens (5 min default)

🔍

Pull-Through Cache

Mirror upstream registries (Docker Hub, GHCR, Quay) with automatic caching. Reduce bandwidth costs and improve pull latency.

Configurable upstream registries
Automatic manifest and blob caching
TTL-based cache invalidation
Transparent to Docker clients
Authenticated upstream support

📊

Real-Time Dashboard

Embedded web dashboard with live metrics. Browse images, search repositories, monitor replication health, and track push/pull activity.

Image browser with wildcard search
CPU, RAM, disk usage monitoring
HA region health status
Audit log with filtering
Identity and access management

🛡

Security & Compliance

JWT-based auth with RS256/EdDSA signing. Rate limiting, network policies, audit logging, and Vault integration for key management.

HashiCorp Vault integration (Transit + KV)
Per-tenant rate limiting
Kubernetes NetworkPolicy templates
Full audit trail (push/pull/delete)
Webhook notifications for events

☸

Kubernetes Native

Helm chart with CRDs for Tenant, Project, AccessPolicy, and TokenPolicy. Horizontal autoscaling, pod anti-affinity, and service monitors.

Helm chart with comprehensive values
Custom Resource Definitions (CRDs)
HPA for registry and auth pods
Ingress with TLS termination
ServiceMonitor for Prometheus

💾

Flexible Storage

Store images on local filesystem, Amazon S3, Google Cloud Storage, or Azure Blob Storage. Object store abstraction via the object_store crate.

Filesystem with persistent volumes
Amazon S3 and S3-compatible (MinIO)
Google Cloud Storage
Azure Blob Storage
Configurable storage backends per deployment

Built-In Dashboard

A dark-themed operations dashboard with real-time metrics, image browsing, and identity management — embedded in the registry binary.

📊

System Metrics

CPU, RAM, disk usage with color-coded thresholds. HA region health with latency and failure counts.

📦

Image Browser

Search and browse all repositories with wildcard support. View tags, tag counts, and repository details.

📝

Activity & Audit Log

Real-time event feed: pushes, pulls, deletes. Filter by event type, user, or repository.

👥

Identity & Access

Users, groups, and service accounts. View SSO logins, group-role mappings, and robot account status.

Enterprise-Ready Identity

Zero static credentials. Seamless integration with your existing identity infrastructure.

🏢

Active Directory / Azure AD

OIDC Authorization Code flow with PKCE. Login with "Sign in with Azure AD" or any OIDC provider. Auto-provision users on first login with group sync.

👥

Group-Based Access Control

Map AD groups to NebulaCR roles: nebulacr-admins to Admin, nebulacr-devs to Maintainer, nebulacr-viewers to Reader. Per-tenant and per-project granularity.

🤖

Machine Identity

CI/CD OIDC federation for GitHub Actions, GitLab CI, and Kubernetes service accounts. No static secrets. Short-lived, scoped tokens auto-expire in 5-15 minutes.

🔄

Token Rotation & Revocation

Refresh token flow for long-lived sessions. Instant token revocation via API. Robot accounts with configurable expiry for automation pipelines.

📋

SCIM 2.0 Provisioning — Automated User Lifecycle

NebulaCR implements the SCIM 2.0 protocol (RFC 7644), enabling Azure AD, Okta, and OneLogin to automatically provision and deprovision users. When someone joins your org, SCIM pre-creates their registry access instantly — no first-login delay. When they leave, access is revoked in seconds, not minutes. Group membership changes sync immediately without requiring a new login.

Scenario	Without SCIM	With SCIM
New hire	Must login first	Pre-provisioned instantly
Team change	Next login syncs	Immediate role update
Offboarding	Token expires in 5 min	Instant revocation
Audit "who has access?"	Only logged-in users	All entitled users
500+ developers	Works but blind spots	Full visibility

How It Works

From deployment to pushing your first image in four steps.

Deploy Registry

Deploy NebulaCR via Helm chart to Kubernetes, Docker Compose, or as a native binary on bare metal. Single binary, no runtime dependencies.

Configure Auth

Connect your OIDC provider (Azure AD, Okta, Google). Map AD groups to roles. Enable CI/CD OIDC federation for GitHub Actions or GitLab.

Push Images

Login with docker login using SSO or robot account credentials. Push images to your multi-tenant registry with automatic replication.

Monitor & Scale

Use the built-in dashboard to monitor health, browse images, and manage access. Prometheus metrics for alerting. Scale with HPA.

Installation

Three ways to get started with NebulaCR.

Deploy to Kubernetes with Helm

# Install NebulaCR
helm install nebulacr deploy/helm/nebulacr \
  -n nebulacr --create-namespace \
  -f values-production.yaml

# Verify
kubectl -n nebulacr get pods
curl https://registry.example.com/health

# Push your first image
docker login registry.example.com
docker push registry.example.com/myteam/myapp:latest

# Open dashboard
open https://registry.example.com/dashboard

Run with Docker

# Pull and run NebulaCR
docker run -d --name nebulacr \
  -p 5000:5000 -p 5001:5001 \
  -v nebulacr-data:/var/lib/nebulacr/data \
  ghcr.io/bwalia/nebulacr:latest

# Push an image
docker tag myapp:latest localhost:5000/demo/default/myapp:latest
docker push localhost:5000/demo/default/myapp:latest

# Open dashboard
open http://localhost:5000/dashboard

Build from Source (Rust 1.80+)

# Clone and build
git clone https://github.com/bwalia/nebulacr.git
cd nebulacr
cargo build --release

# Generate JWT keys
openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -pubout -out public.pem

# Run the registry
./target/release/nebula-registry --config=config.yaml

# Run the auth service
./target/release/nebula-auth --config=config.yaml

Architecture

NebulaCR is composed of modular Rust crates, each handling a specific concern.

                          Docker / Podman / containerd
                                    |
                         OCI Distribution API (HTTPS)
                                    |
                    +---------------+----------------+
                    |                                |
              nebula-registry (:5000)          nebula-auth (:5001)
              /    |     |     \                /    |    \
         Manifests Blobs Tags Dashboard    OIDC  JWT  Robot
            |       |     |      |          |     |    Accounts
         Storage  Audit  Webhook Mirror   Vault  JWKS  CI/CD
            |                    |                      OIDC
      +-----+------+     +------+------+
      | filesystem | ... | S3 / GCS   |
      +------------+     +------------+

              nebula-replication
              /        |        \
         Events    Circuit     Failover
                   Breaker     Manager
                      |
            +----+----+----+
            |    |    |    |
          Region1  Region2  Region3  ...

   Metrics: Prometheus at :9090/metrics
   Dashboard: embedded at :5000/dashboard

API Endpoints

Endpoint	Description
`GET /v2/`	OCI version check
`GET/PUT/DELETE /v2/{t}/{p}/{n}/manifests/{ref}`	Manifest operations (push/pull/delete)
`POST/PATCH/PUT /v2/{t}/{p}/{n}/blobs/uploads/`	Blob upload (chunked or monolithic)
`GET /v2/_catalog`	Repository catalog listing
`GET/POST /auth/token`	Docker-compatible token exchange
`GET /auth/oidc/login`	OIDC SSO login redirect
`POST /auth/ci/token`	CI/CD OIDC token exchange
`GET /dashboard`	Web dashboard
`GET /api/images?q=search`	Image browser API
`GET/POST /scim/v2/Users`	SCIM 2.0 user provisioning
`GET/POST /scim/v2/Groups`	SCIM 2.0 group management
`GET /health`	Health check
`GET /metrics`	Prometheus metrics

Project Structure

nebulacr/
  crates/
    nebula-registry/       # OCI registry + dashboard
    nebula-auth/           # Auth service (OIDC, JWT, RBAC)
    nebula-common/         # Shared models, config, storage
    nebula-replication/    # Multi-region replication
    nebula-mirror/         # Pull-through cache
    nebula-resilience/     # Circuit breaker + retry
    nebula-controller/     # Kubernetes CRD controller
  deploy/
    helm/nebulacr/         # Helm chart
    ansible/               # Native deployment playbooks
  docs/landing/            # This landing page

Your Images.
Your Infrastructure.
Zero Compromise.

Everything You Need for Container Images

Built-In Dashboard

Enterprise-Ready Identity

How It Works

Installation

Deploy to Kubernetes with Helm

Run with Docker

Build from Source (Rust 1.80+)

Architecture

API Endpoints

Project Structure

Ready to Own Your Container Registry?

Your Images.Your Infrastructure.Zero Compromise.

Everything You Need for Container Images

Built-In Dashboard

Enterprise-Ready Identity

How It Works

Installation

Deploy to Kubernetes with Helm

Run with Docker

Build from Source (Rust 1.80+)

Architecture

API Endpoints

Project Structure

Ready to Own Your Container Registry?

Your Images.
Your Infrastructure.
Zero Compromise.