xRegistry - Common Package Registry Proxies

This project contains a set of read-only xRegistry server implementations that proxy several popular package registries (NPM, PyPI, Maven, NuGet, OCI, MCP) behind a unified xRegistry-compliant API.

In addition, the project contains a bridge service that merges the individual registries into a single API endpoint, providing a consolidated view of all package metadata.

This shows how the CNCF xRegistry model can be used to create a unified metadata graph for dependency management across multiple package ecosystems for polyglot applications.

The API and model declarations follow the official xRegistry specification that is being developed as a CNCF sandbox project at https://github.com/xregistry/spec

Overview

• Unified API: Single endpoint for all package registries
• xRegistry Compliant: Follows the official xRegistry specification
• Multi-Registry Support: NPM, PyPI, Maven, NuGet, and OCI registries
• Docker Ready: Containerized deployment with Docker Compose
• Azure Integration: Deploy to Azure Container Apps with GitHub Actions
• Bridge Architecture: Intelligent proxy routing to backend services

Quick Start

Prerequisites

• Node.js v16 or later
• Docker (optional, for containerized deployment)
• Git

Installation

# Clone the repository
git clone https://github.com/xregistry/xrproxy.git
cd xrproxy

# Install dependencies
npm install

Running the Services

Option 1: All-in-One Script (Recommended)

For Windows:

# Command Prompt
start-servers-dynamic.bat

# PowerShell
.\start-servers.ps1

Option 2: Docker Compose

# Start all services
docker-compose up

# Start in background
docker-compose up -d

# Start specific services
docker-compose up npm pypi

Option 3: Individual Services

# Start NPM registry
npm run start:npm

# Start PyPI registry
npm run start:pypi

# Start unified bridge (requires other services running)
npm run start:bridge

Web UI (xRegistry Viewer)

The bridge server can optionally serve the xRegistry Viewer web interface:

# PowerShell (Windows)
.\start-bridge-with-viewer.ps1

# Bash (Linux/Mac)
./start-bridge-with-viewer.sh

Access the viewer at: http://localhost:8080/viewer/

Features:

• Web-based UI for browsing xRegistry services
• Visualize package metadata across all registries
• Built-in CORS proxy for external xRegistry endpoints
• Flexible routing (API at root or /registry/)

See bridge/VIEWER.md for complete documentation.

📡 API Endpoints

Once running, the unified bridge provides these endpoints at http://localhost:8080:

Core xRegistry Endpoints

• GET / - Root document with all registry information
• GET /model - Unified data model from all registries
• GET /capabilities - Combined capabilities from all services

Registry-Specific Endpoints

• GET /noderegistries - NPM packages (Node.js)
• GET /pythonregistries - PyPI packages (Python)
• GET /javaregistries - Maven packages (Java)
• GET /dotnetregistries - NuGet packages (.NET)
• GET /containerregistries - OCI images (Containers)
• GET /mcpproviders - MCP packages (Model Context Protocol)

Example Usage

# Get unified model showing all registry types
curl http://localhost:8080/model

# Browse NPM packages
curl http://localhost:8080/noderegistries

# Get capabilities from all registries
curl http://localhost:8080/capabilities

🏗️ Architecture

The project uses a bridge architecture where:

1. Individual Registry Services run on separate ports:

   • NPM: 3000
   • PyPI: 3100
   • Maven: 3200
   • NuGet: 3300
   • OCI: 3400
   • MCP: 3600

2. Unified Bridge Service (port 8080) provides:

   • Single API endpoint
   • Model and capability merging
   • Intelligent request routing
   • Authentication management

🧪 Testing the Installation

Quick Health Check

# Test unified bridge
curl http://localhost:8080/

# Check all registries are merged
curl http://localhost:8080/model | jq '.groups | keys'
# Should return: ["containerregistries", "dotnetregistries", "javaregistries", "noderegistries", "pythonregistries"]

🐳 Docker Deployment

Quick Start with Docker

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Production Deployment

Azure Container Apps Deployment

The xRegistry Package Registries project includes fully automated deployment to Azure Container Apps:

# Set variables
RG_NAME="rg-xregistry-prod"
LOCATION="eastus"
ACR_NAME="xregistryacr"
ACA_ENV_NAME="cae-xregistry-prod"
ACA_NAME="ca-xregistry-unified"

# Create resource group and resources
az group create --name $RG_NAME --location $LOCATION
az acr create --resource-group $RG_NAME --name $ACR_NAME --sku Standard --admin-enabled true
az containerapp env create --name $ACA_ENV_NAME --resource-group $RG_NAME --location $LOCATION

CI/CD Integration:

• Automated deployments via GitHub Actions workflows
• Multi-platform container builds (AMD64/ARM64)
• Security scanning and health verification

Monitoring and Health:

• Built-in health check endpoints
• Application Insights integration
• Container logs accessible via Azure CLI

Scaling and Updates:

# Configure auto-scaling
az containerapp update --name $ACA_NAME --resource-group $RG_NAME \
  --min-replicas 1 --max-replicas 10

# View revisions for rollback
az containerapp revision list --name $ACA_NAME --resource-group $RG_NAME

Resource Optimization:

• Optimized container configuration (1.75 CPU + 3.5GB memory)
• Resource sharing across registry services
• Non-root container execution for security
• HTTPS-only ingress for secure communications

See DEPLOYMENT.md for comprehensive details on:

• Azure Container Apps deployment
• GitHub Actions CI/CD setup
• Production configuration options
• Monitoring and health checks
• Scaling and auto-scaling options
• Security and resource optimization

🔧 Configuration

Environment Variables

Variable	Default	Description
XREGISTRY_PORT	8080	Bridge server port
XREGISTRY_ENABLE	npm,pypi,maven,nuget,oci	Enabled registries
XREGISTRY_BASEURL	Auto-detected	Base URL for responses
XREGISTRY_API_KEY	None	Global API key
NODE_ENV	development	Environment mode

Registry-Specific Ports

Each registry can be configured individually:

# Custom ports
XREGISTRY_NPM_PORT=5000 npm run start:npm
XREGISTRY_PYPI_PORT=5001 npm run start:pypi

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• Development setup
• Coding standards
• Testing guidelines
• Pull request process

Development Quick Start

# Set up development environment
npm install

# Start services for development
cd test/integration
node run-docker-integration-tests.js

# In another terminal, start bridge
cd bridge
npm run build
PORT=8080 node dist/proxy.js

See DEVELOPMENT.md for detailed development documentation.

📚 Documentation

• DEVELOPMENT.md - Comprehensive development guide
• DEPLOYMENT.md - Production deployment guide
• CONTRIBUTING.md - Contribution guidelines
• CHANGELOG.md - Project change history
• bridge/VIEWER.md - xRegistry Viewer integration guide
• xRegistry Specification - See the official xRegistry specification for standard compliance details

🔍 Troubleshooting

Common Issues

Port conflicts:

# Use dynamic port assignment
.\start-servers-dynamic.bat

Services not starting:

# Check dependencies
npm install

# Verify Node.js version
node --version  # Should be v16+

Bridge not connecting:

# Rebuild bridge
cd bridge && npm run build

# Check backend services are running
curl http://localhost:3000/noderegistries
curl http://localhost:3100/pythonregistries

Getting Help

• 📝 Check existing issues in the GitHub repository
• 🐛 Report bugs with detailed steps to reproduce
• 💡 Request features through GitHub Discussions
• 📖 Read the docs in the linked guides above

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🌟 Acknowledgments

• Built following the xRegistry specification
• Supports NPM, PyPI, Maven, NuGet, and OCI registries
• Designed for cloud-native deployment on Azure Container Apps

---

Ready to get started? Use Docker Compose (docker-compose up) or the startup scripts to launch all services!