| FazBrowse GitHub Viewer | Trending | | Home |
| Tools: [Download Repo ZIP] [Original HTTPS Page] |
| Name | Name | Last commit date | ||
|---|---|---|---|---|
High-performance package manager proxy/mirror server supporting 7 package managers
Edition: Community (Open Source - AGPL-3.0)
ProxyND Core is the community edition of ProxyND, providing essential package manager proxy functionality with modern authentication, flexible caching, and production-ready features.
Mount Point: /maven
# Configure Maven to use ProxyND
<mirror>
<id>proxynd</id>
<url>http://localhost:8080/maven/central</url>
<mirrorOf>central</mirrorOf>
</mirror>Features:
Mount Point: /npm
# Configure NPM to use ProxyND
npm config set registry http://localhost:8080/npm/registry
# Or use .npmrc
registry=http://localhost:8080/npm/registryFeatures:
Mount Point: /apt
# Configure APT sources
deb http://localhost:8080/apt/ubuntu focal main
deb http://localhost:8080/apt/ubuntu focal-updates mainFeatures:
Mount Point: /docker
# Configure Docker daemon
{
"registry-mirrors": ["http://localhost:8080/docker"]
}Features:
Mount Point: /pypi
# Configure pip
pip config set global.index-url http://localhost:8080/pypi/simple
# Or use pip.conf
[global]
index-url = http://localhost:8080/pypi/simpleFeatures:
Mount Point: /yum
# Configure YUM repository
[proxynd]
name=ProxyND YUM Mirror
baseurl=http://localhost:8080/yum/centos/8/
enabled=1Features:
Mount Point: /apk
# Configure APK repository
echo "http://localhost:8080/apk/alpine/v3.18/main" > /etc/apk/repositoriesFeatures:
# Clone repository
git clone https://github.com/yourusername/proxynd.git
cd proxynd/proxynd-core
# Install dependencies
make dev-prepare
# Setup configuration
make dev-setup
# Run development server (with hot reload)
make dev-run# Build binary
make build
# Binary location: tmp/bin/proxynd
./tmp/bin/proxynd --version# Build Docker image
make docker-build
# Run container
make docker-run
# Or use docker-compose
docker-compose up -d# Using Helm chart
helm install proxynd ./charts/core \
--set config.storage.path=/data \
--set config.cache.backend=s3
# Or using kubectl
kubectl apply -f k8s/core/# config.minimal.yaml
server:
port: 8080
host: 0.0.0.0
storage:
path: ./storage
cache:
backend: filesystem
ttl: 24h
proxies:
- type: maven
enabled: true
upstream: https://repo1.maven.org/maven2
- type: npm
enabled: true
upstream: https://registry.npmjs.org
auth:
enabled: false# config.production.yaml
server:
port: 8080
host: 0.0.0.0
read_timeout: 30s
write_timeout: 30s
storage:
path: /var/lib/proxynd
cache:
backend: s3
ttl: 168h # 7 days
s3:
bucket: proxynd-cache
region: us-east-1
endpoint: https://s3.amazonaws.com
proxies:
- type: maven
enabled: true
upstream: https://repo1.maven.org/maven2
cache_ttl: 720h # 30 days
- type: npm
enabled: true
upstream: https://registry.npmjs.org
cache_ttl: 168h # 7 days
- type: docker
enabled: true
upstream: https://registry-1.docker.io
cache_ttl: 168h
auth:
enabled: true
providers:
- type: oauth2
provider: github
client_id: ${GITHUB_CLIENT_ID}
client_secret: ${GITHUB_CLIENT_SECRET}
- type: jwt
secret: ${JWT_SECRET}
expiry: 24h
metrics:
enabled: true
path: /metrics
prometheus:
enabled: true
logging:
level: info
format: json
file: /var/log/proxynd/proxynd.log# Required
export CONFIG_DIR=/etc/proxynd
export STORAGE_DIR=/var/lib/proxynd
# Optional
export SERVER_PORT=8080
export LOG_LEVEL=info
export LOG_FORMAT=json
# OAuth2 credentials
export GITHUB_CLIENT_ID=your_client_id
export GITHUB_CLIENT_SECRET=your_client_secret
export JWT_SECRET=your_jwt_secret
# S3 credentials (if using S3 cache)
export AWS_ACCESS_KEY_ID=your_key
export AWS_SECRET_ACCESS_KEY=your_secretProxyND Core follows Hexagonal Architecture (Ports and Adapters) pattern for maintainability and testability.
✅ Migration Complete (2025-11-29): Fully migrated to hexagonal architecture. 87 legacy files removed (25,867 lines). All integration tests passing with 100% clean architecture.
internal/
├── domain/ # Pure business logic (NO external dependencies)
│ ├── types.go # Domain entities
│ └── errors.go # Domain errors
├── usecase/ # Business workflows (framework-independent)
│ ├── proxy_service.go # Core proxy logic
│ ├── cache_strategy.go # Cache management
│ └── health.go # Health checks
├── ports/ # Interface contracts
│ ├── http.go # HTTP server interface
│ ├── pm.go # Package manager interface
│ ├── cache.go # Cache backend interface
│ ├── auth.go # Authentication interface
│ └── observability.go # Metrics/logging interface
└── adapters/ # External system implementations
├── http/fiber/ # Fiber web framework adapter
├── pm/ # Package manager drivers
│ ├── maven/
│ ├── npm/
│ ├── apt/
│ ├── docker/
│ ├── pypi/
│ ├── yum/
│ └── apk/
├── cache/ # Cache backend implementations
│ ├── filesystem/
│ ├── redis/
│ └── s3/
└── auth/ # Authentication implementations
├── oauth2/
├── jwt/
└── apikey/
┌─────────────────────────────────────────┐
│ HTTP Adapter (Fiber) │
│ (adapters/http/fiber) │
└──────────────┬──────────────────────────┘
│ implements
↓
┌─────────────────────────────────────────┐
│ HTTP Port Interface │
│ (ports/http.go) │
└──────────────┬──────────────────────────┘
│ uses
↓
┌─────────────────────────────────────────┐
│ Proxy Service (Usecase) │
│ (usecase/proxy_service.go) │
└──────────────┬──────────────────────────┘
│ uses
↓
┌─────────────────────────────────────────┐
│ Package Manager Port Interface │
│ (ports/pm.go) │
└──────────────┬──────────────────────────┘
│ implemented by
↓
┌─────────────────────────────────────────┐
│ Package Manager Adapters │
│ (adapters/pm/maven, npm, etc.) │
└─────────────────────────────────────────┘
Health Check
GET /health
GET /readyMetrics
GET /metrics # Prometheus formatMaven
GET /maven/{repository}/{group}/{artifact}/{version}/{file}
HEAD /maven/{repository}/{group}/{artifact}/{version}/{file}NPM
GET /npm/registry/{package}
GET /npm/registry/{package}/-/{tarball}Docker
GET /v2/
GET /v2/{name}/manifests/{reference}
GET /v2/{name}/blobs/{digest}PyPI
GET /pypi/simple/{package}/
GET /pypi/packages/{path}Cache Management
GET /api/cache/list # List cached items
DELETE /api/cache/clear # Clear cache
GET /api/cache/stats # Cache statisticsConfiguration
GET /api/config/show # Show current config
POST /api/config/validate # Validate config
POST /api/config/reload # Reload configUser Management
GET /api/users # List users
POST /api/users # Create user
DELETE /api/users/:id # Delete userTesting
GET /api/test/all # Test all proxies
GET /api/test/:proxy # Test specific proxyStatus
GET /api/status # Server statusFor complete API documentation, see API_ENDPOINTS.md.
ProxyND provides proxyndctl CLI for administrative tasks.
# Build CLI tool
make build-cli
# Binary location: tmp/bin/proxyndctl
./tmp/bin/proxyndctl --helpCache Management
# List cache entries
proxyndctl cache list
# Clear cache by type
proxyndctl cache clear --type npm
# Show cache statistics
proxyndctl cache sizeConfiguration Management
# Validate configuration
proxyndctl config validate
# Show current configuration
proxyndctl config show
# Reload configuration
proxyndctl config reloadUser Management
# List users
proxyndctl user list
# Add user
proxyndctl user add john --email john@example.com
# Delete user
proxyndctl user delete johnProxy Testing
# Test all proxies
proxyndctl test all
# Test specific proxy
proxyndctl test --proxy maven
# Test with custom upstream
proxyndctl test --proxy npm --upstream https://registry.npmjs.orgServer Status
# Show server status
proxyndctl status
# Show detailed metrics
proxyndctl status --metricsMaven Extensions
# Build search index
proxyndctl maven-index build
# Create incremental backup
proxyndctl maven-backup createBatch Job Automation
# Run batch script
proxyndctl batch run maintenance.batch
# Validate script syntax
proxyndctl batch validate script.batch
# View job history
proxyndctl batch history --limit 10
# Show job details
proxyndctl batch show job-1638360000123
# Clean old history
proxyndctl batch clean --older-than 30dExample Batch Script (maintenance.batch):
# Daily maintenance automation
echo "Starting maintenance..."
# Clear old cache
cache clear --older-than 30d --force
if last_exit == 0 then
echo "✅ Cache cleared"
else
echo "❌ Failed"
exit 1
fi
# Create backup
maven-backup create --target /backup
echo "✅ Maintenance complete"GitHub
auth:
enabled: true
providers:
- type: oauth2
provider: github
client_id: ${GITHUB_CLIENT_ID}
client_secret: ${GITHUB_CLIENT_SECRET}
redirect_url: http://localhost:8080/auth/github/callbackGitLab
auth:
providers:
- type: oauth2
provider: gitlab
client_id: ${GITLAB_CLIENT_ID}
client_secret: ${GITLAB_CLIENT_SECRET}
redirect_url: http://localhost:8080/auth/gitlab/callbackauth:
providers:
- type: oauth2
provider: google
client_id: ${GOOGLE_CLIENT_ID}
client_secret: ${GOOGLE_CLIENT_SECRET}
redirect_url: http://localhost:8080/auth/google/callbackauth:
providers:
- type: jwt
secret: ${JWT_SECRET}
expiry: 24h
algorithm: HS256Usage:
# Login to get JWT token
curl -X POST http://localhost:8080/auth/login \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"secret"}'
# Use JWT token
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
http://localhost:8080/api/cache/listMFA is implemented in Core but enabled via Enterprise plugin.
TOTP (Time-based One-Time Password)
# Enable TOTP
curl -X POST http://localhost:8080/auth/mfa/totp/enable
# Verify TOTP
curl -X POST http://localhost:8080/auth/mfa/totp/verify \
-d '{"code":"123456"}'WebAuthn (Hardware Keys)
# Register security key
curl -X POST http://localhost:8080/auth/mfa/webauthn/register
# Authenticate with security key
curl -X POST http://localhost:8080/auth/mfa/webauthn/verifyauth:
api_keys:
enabled: true
keys:
- key: ${API_KEY_1}
user: admin
permissions: ["read", "write"]
- key: ${API_KEY_2}
user: readonly
permissions: ["read"]Usage:
curl -H "X-API-Key: YOUR_API_KEY" \
http://localhost:8080/api/cache/listcache:
backend: filesystem
filesystem:
path: /var/cache/proxynd
max_size: 100GB
cleanup_interval: 1hFeatures:
cache:
backend: redis
redis:
host: localhost
port: 6379
password: ${REDIS_PASSWORD}
db: 0
ttl: 24hFeatures:
cache:
backend: s3
s3:
bucket: proxynd-cache
region: us-east-1
endpoint: https://s3.amazonaws.com
access_key: ${AWS_ACCESS_KEY_ID}
secret_key: ${AWS_SECRET_ACCESS_KEY}Compatible Storage:
cache:
backend: multi-tier
tiers:
- backend: memory
ttl: 5m
max_size: 1GB
- backend: filesystem
ttl: 24h
max_size: 50GB
- backend: s3
ttl: 720h # 30 days# Setup development environment
make dev-prepare
make dev-setup
# Run with hot reload (Air)
make dev-run
# Run tests
make test-unit
make test-integration
# Quick validation (format + lint + test)
make quick# Format code
make fmt
# Run linter
make lint
# Run all tests
make test
# Generate coverage report
make coverageThe project uses a modular Makefile structure for better organization:
.make/ ├── build.mk # Build and installation targets ├── clean.mk # Cleanup operations ├── deps.mk # Dependency management ├── dev.mk # Development environment ├── docker.mk # Docker operations ├── quality.mk # Code quality and linting ├── test.mk # Testing and validation └── tools.mk # Tool installation
All targets are accessible through the main Makefile. Use make help to see all available commands, or make help-<category> for category-specific help (e.g., make help-dev, make help-test).
type NewPMAdapter struct {
upstream string
}
func (a *NewPMAdapter) FetchPackage(ctx context.Context, path string) ([]byte, error) {
// Implementation
}type PackageManagerType string
const (
PMTypeNewPM PackageManagerType = "newpm"
)proxies:
- type: newpm
enabled: true
upstream: https://newpm-registry.example.comWrite tests in adapters/pm/newpm/adapter_test.go
Update documentation
For detailed development guide, see docs/05-development/README.md.
Build Image:
make docker-buildRun Container:
docker run -d \
--name proxynd \
-p 8080:8080 \
-e CONFIG_DIR=/etc/proxynd \
-e STORAGE_DIR=/var/lib/proxynd \
-v $(pwd)/config.yaml:/etc/proxynd/config.yaml \
-v proxynd-data:/var/lib/proxynd \
proxynd:latestDocker Compose:
version: '3.8'
services:
proxynd:
image: proxynd:latest
ports:
- "8080:8080"
environment:
CONFIG_DIR: /etc/proxynd
STORAGE_DIR: /var/lib/proxynd
volumes:
- ./config.yaml:/etc/proxynd/config.yaml
- proxynd-data:/var/lib/proxynd
volumes:
proxynd-data:Using Helm:
# Add Helm repository
helm repo add proxynd https://charts.proxynd.io
helm repo update
# Install
helm install proxynd proxynd/core \
--set config.storage.path=/data \
--set config.cache.backend=s3 \
--set config.cache.s3.bucket=proxynd-cacheUsing kubectl:
# Apply manifests
kubectl apply -f k8s/core/namespace.yaml
kubectl apply -f k8s/core/configmap.yaml
kubectl apply -f k8s/core/deployment.yaml
kubectl apply -f k8s/core/service.yamlHelm Chart Values:
# values.yaml
replicaCount: 3
image:
repository: proxynd
tag: latest
pullPolicy: IfNotPresent
resources:
limits:
cpu: 1000m
memory: 2Gi
requests:
cpu: 500m
memory: 1Gi
config:
server:
port: 8080
storage:
path: /data
cache:
backend: s3
s3:
bucket: proxynd-cache
region: us-east-1
persistence:
enabled: true
size: 100Gi
storageClass: standardmodule "proxynd" {
source = "./terraform/modules/proxynd"
environment = "production"
region = "us-east-1"
instance_type = "t3.large"
storage_size = 100
config = {
cache_backend = "s3"
s3_bucket = "proxynd-cache-prod"
}
}ProxyND provides a comprehensive REST API for enterprise features including RBAC, audit logging, analytics, and security scanning.
| Category | Endpoints | Description |
|---|---|---|
| RBAC | 12 | Role-based access control, permissions, user assignments |
| Audit | 8 | Event logging, compliance reports, audit trail export |
| Analytics | 10 | Usage stats, performance metrics, cost analysis |
| Security | 8 | Vulnerability scanning, license compliance, malware detection |
| Alerts | 5 | Alert management and notification rules |
| License | 4 | License validation and feature management |
# Start development server
make dev-run
# Test all enterprise endpoints
make test-enterprise-integration
# Test specific categories
make test-enterprise-rbac
make test-enterprise-audit
make test-enterprise-analyticsList Roles (RBAC)
curl http://localhost:8080/api/v1/enterprise/rbac/rolesGet Audit Events
curl http://localhost:8080/api/v1/enterprise/audit/events?page=1&per_page=20Analytics Overview
curl http://localhost:8080/api/v1/enterprise/analytics/overviewList Vulnerabilities
curl http://localhost:8080/api/v1/enterprise/security/vulnerabilitiesAll endpoints follow a consistent response structure:
{
"success": true,
"data": { ... },
"pagination": {
"page": 1,
"per_page": 20,
"total": 150,
"total_pages": 8
},
"metadata": {
"timestamp": "2025-01-17T10:30:00Z",
"request_id": "uuid"
}
}Enterprise API endpoints require a valid enterprise license:
# Run integration tests
./tmp/scripts/test-webui-integration.sh all
# Run contract tests
go test -tags=contract ./tests/contract/enterprise_api_test.go
# Generate Swagger documentation
make swagger
# View API documentation
cat tmp/plan/README.mdProxyND provides interactive API documentation via Swagger UI:
# Generate Swagger documentation from code annotations
make swagger
# Start the server
make dev-run
# Access Swagger UI (interactive API explorer)
open http://localhost:8080/swagger/index.html
# Or via API endpoint alias
open http://localhost:8080/api/v1/docsThe Swagger documentation includes:
Documentation Files:
Complete Postman collection with all 47 endpoints for easy API testing:
Files (in postman/ directory):
Quick Import:
The collection includes:
ProxyND Enterprise API is designed for high performance with strict targets:
Performance Targets:
Run Benchmarks:
# Standard benchmark (100 iterations)
make test-benchmark-enterprise
# Quick test (25 iterations)
make test-benchmark-enterprise-quick
# Stress test (500 iterations, 50 concurrent)
make test-benchmark-enterprise-stress
# Custom configuration
ITERATIONS=200 CONCURRENT=30 ./scripts/benchmark-enterprise-api.shThe benchmark suite tests 13 representative endpoints across all categories with:
Additional Resources:
| Feature | Core (Community) | Enterprise | Cloud |
|---|---|---|---|
| Package Managers | 7 (Maven, NPM, APT, Docker, PyPI, YUM, APK) | ✅ | ✅ |
| OAuth2 (GitHub, GitLab, Google) | ✅ | ✅ | ✅ |
| JWT Tokens | ✅ | ✅ | ✅ |
| MFA (TOTP/WebAuthn) | ✅ (Implementation) | ✅ (Enabled) | ✅ |
| API Keys | ✅ | ✅ | ✅ |
| Filesystem Cache | ✅ | ✅ | ✅ |
| Redis Cache | ✅ (Single) | ✅ (Cluster) | ✅ |
| S3 Cache | ✅ | ✅ | ✅ |
| RBAC | ❌ | ✅ | ✅ |
| Audit Logging | ❌ | ✅ | ✅ |
| LDAP/SAML | ❌ | ✅ (Upcoming) | ✅ |
| Multi-Tenancy | ❌ | ❌ | ✅ |
| Usage Billing | ❌ | ❌ | ✅ |
| Quota Management | ❌ | ❌ | ✅ |
| License | AGPL-3.0 | Commercial | Commercial |
We welcome contributions! See CONTRIBUTING.md for guidelines.
ProxyND Core is dual-licensed:
For more details, see LICENSING.md.
ℹ️ For detailed configuration and usage, refer to the documentation.
| Back | FazBrowse Home | New Git URL |