Alternative Registries

Overview

Publishing Rust crates to alternative registries beyond crates.io for private packages, enterprise distribution, or specialized ecosystems.

Why Alternative Registries? (explanation)

This section is rationale; the registry catalog and configuration tables below are the reference content.

Private packages - Keep proprietary code internal
Enterprise control - Host on internal infrastructure
Faster builds - Geographic proximity, caching
Compliance - Meet regulatory requirements
Mirrors - Reduce dependency on crates.io

Registry Options

1. Cloudsmith (Hosted SaaS)

Best for: Commercial projects, easy setup

[registries.cloudsmith]
index = "sparse+https://dl.cloudsmith.io/basic/USER/REPO/cargo/index/"
token = "Bearer YOUR_TOKEN"

Publish:

cargo publish --registry cloudsmith

Features:

Hosted solution (no infrastructure)
Multiple package formats (npm, Maven, Docker)
CDN distribution
Access control and auditing
Free tier available

Setup:

Sign up at https://cloudsmith.io/
Create Rust/Cargo repository
Get API token from account settings
Configure .cargo/config.toml

2. Artifactory (JFrog)

Best for: Enterprise with existing JFrog infrastructure

[registries.artifactory]
index = "sparse+https://artifactory.company.com/artifactory/api/cargo/cargo-local/index/"

Publish:

# Set credentials
cargo login --registry artifactory

cargo publish --registry artifactory

Features:

Enterprise-grade security
Advanced access control
Vulnerability scanning
Build promotion
High availability

Setup:

Install/access Artifactory instance
Create Cargo repository
Configure authentication
Set up replication (optional)

3. Freight (Self-Hosted)

Best for: Complete control, on-premise hosting

[registries.freight]
index = "sparse+https://registry.company.com/index/"

Publish:

cargo publish --registry freight

Features:

Open-source (MIT)
Self-hosted
S3-compatible storage
PostgreSQL backend
Docker deployment

Setup:

# Docker Compose
docker-compose up -d

# Configure registry
freight init --storage s3://bucket/path

# Add users
freight user add username --admin

Links: https://github.com/tantaman/freight

4. Kellnr (Self-Hosted)

Best for: Simple self-hosted option, small teams

[registries.kellnr]
index = "sparse+https://kellnr.company.com/api/v1/crates"

Publish:

cargo publish --registry kellnr

Features:

Written in Rust
Simple deployment (single binary)
Web UI
Local cache/mirror
Lightweight

Setup:

# Download binary
wget https://github.com/kellnr/kellnr/releases/latest/download/kellnr

# Run
./kellnr --port 8080

Links: https://kellnr.io/

5. Romt (Read-Only Mirror)

Best for: Offline/air-gapped environments

# Download full crates.io mirror
romt download --crates --index

# Serve locally
romt serve

Configure:

[source.crates-io]
replace-with = "romt-mirror"

[source.romt-mirror]
registry = "sparse+http://localhost:8000/index/"

Features:

Complete crates.io mirror
Offline development
Air-gapped networks
Bandwidth savings

Links: https://github.com/drmikehenry/romt

6. Shipyard (Self-Hosted)

Best for: Kubernetes-native deployments

[registries.shipyard]
index = "sparse+https://shipyard.k8s.company.com/index/"

Deploy:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: shipyard
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: shipyard
        image: shipyard/server:latest
        env:
        - name: STORAGE_BACKEND
          value: s3

Features:

Kubernetes-native
Horizontal scaling
Cloud storage backends
High availability

Configuration

Global Config

~/.cargo/config.toml:

# Define registries
[registries.company]
index = "sparse+https://registry.company.com/index/"
token = "Bearer YOUR_TOKEN"

[registries.staging]
index = "sparse+https://staging-registry.company.com/index/"

# Set default registry
[registry]
default = "company"

# Configure crates.io as backup
[source.crates-io]
registry = "https://github.com/rust-lang/crates.io-index"

Project Config

.cargo/config.toml:

[registries.internal]
index = "sparse+https://internal.company.com/index/"

# Publish to internal registry by default
[registry]
default = "internal"

# Allow dependencies from multiple registries
[source.crates-io]
registry = "https://github.com/rust-lang/crates.io-index"

Dependency Sources

[dependencies]
# From crates.io (default)
serde = "1.0"

# From alternative registry
internal-lib = { version = "0.1", registry = "company" }

# From Git
custom = { git = "https://github.com/user/custom.git" }

# From local path
dev-tool = { path = "../dev-tool" }

Publishing Workflow

Manual Publishing

# Login to registry
cargo login --registry company

# Publish
cargo publish --registry company

# Verify
cargo search --registry company my-crate

CI/CD Publishing

GitHub Actions:

- name: Publish to internal registry
  env:
    CARGO_REGISTRIES_COMPANY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
  run: |
    cargo publish --registry company --token $CARGO_REGISTRIES_COMPANY_TOKEN

Environment Variables:

export CARGO_REGISTRIES_COMPANY_TOKEN="your-token"
cargo publish --registry company

Registry Mirror/Cache

Use Case: Reduce crates.io Load

[source.crates-io]
replace-with = "company-mirror"

[source.company-mirror]
registry = "sparse+https://mirror.company.com/crates.io/"

Benefits:

Faster builds (geographic proximity)
Reduced external bandwidth
Continued access during crates.io outages
Compliance with network policies

Implement Mirror

With Romt:

# Sync crates.io daily
romt download --crates --index --update

# Serve via nginx/apache
romt serve --host 0.0.0.0 --port 8080

With Cloudsmith:

Configure upstream proxy
Automatic caching
CDN distribution

Security Considerations

1. Authentication

# Token-based
[registries.secure]
index = "sparse+https://registry.company.com/index/"
token = "Bearer YOUR_TOKEN"

# Credential provider
[registries.secure]
credential-provider = "cargo:token"

2. TLS/HTTPS

# Enforce HTTPS
[registries.company]
index = "sparse+https://registry.company.com/index/"  # ✅

# Never use HTTP for sensitive data
index = "sparse+http://registry.company.com/index/"   # ❌

3. Access Control

Most registries support:

User authentication
Team-based permissions
Read/write separation
IP allowlists
Audit logging

4. Package Signing

# Sign package
cargo package --sign

# Verify signature
cargo verify my-crate-0.1.0.crate

Migration Strategies

From crates.io to Private Registry

Phase 1: Parallel Publishing

# Publish to both
cargo publish  # crates.io
cargo publish --registry company  # private

Phase 2: Update Dependencies

[dependencies]
my-crate = { version = "0.2", registry = "company" }

Phase 3: Deprecate Public

Archive crates.io package
Update README with migration notice

From Private to Public

Checklist:

Troubleshooting

Authentication Fails

# Check token
cargo login --registry company

# Debug
CARGO_LOG=cargo::ops::registry=trace cargo publish --registry company

Index Not Found

# Verify index URL
curl https://registry.company.com/index/

# Check network
ping registry.company.com

Slow Publish

# Check package size
cargo package --list | wc -l

# Exclude unnecessary files
# .cargo/config.toml
[package]
exclude = [
    "tests/fixtures/*",
    "*.tmp",
]

Cost Comparison

Registry	Hosting	Cost	Best For
crates.io	Public	Free	Open source
Cloudsmith	SaaS	$50+/mo	Commercial
Artifactory	Self/Cloud	$$$$	Enterprise
Kellnr	Self-hosted	Free	Small teams
Freight	Self-hosted	Free	Control freaks
Romt	Self-hosted	Free	Air-gapped

Best Practices

Use sparse index - Faster than git index
Mirror crates.io - Reduce external dependencies
Automate publishing - CI/CD integration
Version carefully - Follow semver strictly
Document privately - Internal registry docs
Test thoroughly - Before publishing
Backup regularly - Registry data