Custom Registry Configuration

Prism supports using custom npm registries and unpkg CDN URLs for air-gapped environments, corporate proxies, or custom package hosting.

Configuration Methods

Set environment variables before running the installer:

# Custom npm registry
export PRISM_NPM_REGISTRY=https://npm.mycompany.com

# Custom unpkg CDN
export PRISM_UNPKG_URL=https://cdn.mycompany.com/npm

# Now run installer
python3 install.py

2. CLI Arguments

Specify registries directly when running commands:

# List packages from custom registry
python3 scripts/npm_package_fetcher.py list \
  --registry https://npm.mycompany.com

# Fetch package from custom CDN
python3 scripts/npm_package_fetcher.py fetch @prism-dx/prism-config \
  --unpkg https://cdn.mycompany.com/npm

# Run installer with custom registry
python3 install.py \
  --npm-registry https://npm.mycompany.com \
  --unpkg-url https://cdn.mycompany.com/npm

3. Combined Approach

CLI arguments override environment variables:

# Set defaults via env vars
export PRISM_NPM_REGISTRY=https://npm.mycompany.com

# Override for specific command
python3 install.py --npm-registry https://registry.npmjs.org

Use Cases

Corporate Environments

Many companies use private npm registries (Artifactory, Nexus, Verdaccio):

# Point to corporate Artifactory
export PRISM_NPM_REGISTRY=https://artifactory.company.com/artifactory/api/npm/npm-virtual
export PRISM_UNPKG_URL=https://artifactory.company.com/artifactory/npm-virtual

python3 install.py

Air-Gapped Environments

For environments without internet access, host packages internally:

# Point to internal mirror
export PRISM_NPM_REGISTRY=https://internal-npm.company.local
export PRISM_UNPKG_URL=https://internal-cdn.company.local

python3 install.py

Development/Testing

Test with local registry during development:

# Use local Verdaccio instance
export PRISM_NPM_REGISTRY=http://localhost:4873
export PRISM_UNPKG_URL=http://localhost:4873

python3 scripts/npm_package_fetcher.py list

Registry Requirements

npm Registry

Must support standard npm registry API:

Compatible registries:

unpkg CDN

Must serve package files at:

{CDN_URL}/{package}@{version}/{file}

Examples:

Compatible CDNs:

Setting Up Custom Registry

Option 1: Artifactory

  1. Create npm repository in Artifactory
  2. Configure proxy to npmjs.org (or use local only)
  3. Publish Prism packages to your instance:
# Configure npm to use Artifactory
npm config set registry https://artifactory.company.com/artifactory/api/npm/npm-local/

# Login
npm login

# Publish packages
cd prisms/prism.prism
npm publish
  1. Point Prism installer to Artifactory:
export PRISM_NPM_REGISTRY=https://artifactory.company.com/artifactory/api/npm/npm-local
export PRISM_UNPKG_URL=https://artifactory.company.com/artifactory/npm-local

Option 2: Verdaccio (Lightweight)

  1. Install Verdaccio:
npm install -g verdaccio
verdaccio
  1. Configure npm:
npm set registry http://localhost:4873
  1. Publish packages:
cd prisms/prism.prism
npm publish
  1. Use with Prism:
export PRISM_NPM_REGISTRY=http://localhost:4873
export PRISM_UNPKG_URL=http://localhost:4873

Option 3: GitHub Packages

  1. Configure npm:
echo "@prism-dx:registry=https://npm.pkg.github.com" >> .npmrc
echo "//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}" >> .npmrc
  1. Publish packages:
cd prisms/prism.prism
npm publish
  1. Use with Prism:
export PRISM_NPM_REGISTRY=https://npm.pkg.github.com
# GitHub Packages doesn't provide unpkg-style CDN, use fallback
python3 install.py --local  # Use local packages

Fallback Behavior

Prism has robust fallback:

  1. Try custom unpkg CDN (if configured)
  2. Try custom npm registry (if configured)
  3. Try public unpkg.com (if custom fails)
  4. Try public registry.npmjs.org (if custom fails)
  5. Use local packages (if all network fetches fail)

This ensures Prism works even with partial network failures!

Troubleshooting

Check Current Configuration

# Show what Prism will use
python3 scripts/npm_package_fetcher.py list
# First line shows: "Registry Configuration: ..."

Test Registry Connection

# Test npm registry
curl https://npm.mycompany.com/@prism-dx/prism-config

# Test unpkg CDN
curl https://cdn.mycompany.com/npm/@prism-dx/prism-config@latest/package.yaml

Common Issues

“Connection refused”

“401 Unauthorized”

“404 Not Found”

“Package not found, using local”

Environment Variable Reference

Variable Description Default
PRISM_NPM_REGISTRY npm registry URL for package metadata https://registry.npmjs.org
PRISM_UNPKG_URL unpkg CDN URL for package files https://unpkg.com

Complete Example: Corporate Setup

#!/bin/bash
# File: setup_prism_corporate.sh

# Corporate registry configuration
export PRISM_NPM_REGISTRY="https://artifactory.mycompany.com/artifactory/api/npm/npm-virtual"
export PRISM_UNPKG_URL="https://artifactory.mycompany.com/artifactory/npm-virtual"

# Optional: Set proxy if needed
export HTTP_PROXY="http://proxy.mycompany.com:8080"
export HTTPS_PROXY="http://proxy.mycompany.com:8080"

# Install Prism
git clone https://github.com/andersonwilliam85/prism.git
cd prism

# List available packages (will use corporate registry)
python3 scripts/npm_package_fetcher.py list

# Run installer
python3 install.py --prism fortune500

Security Considerations

HTTPS Only

Always use HTTPS for production registries:

# Good
export PRISM_NPM_REGISTRY=https://npm.company.com

# Bad (only for local dev!)
export PRISM_NPM_REGISTRY=http://localhost:4873

Authentication

For private registries requiring auth:

# Configure npm authentication first
npm login --registry https://npm.company.com

# Then run Prism (inherits npm auth)
python3 install.py

Certificate Validation

For self-signed certs, you may need:

# Disable SSL verification (not recommended for production!)
export NODE_TLS_REJECT_UNAUTHORIZED=0

# Better: Add CA cert to system trust store

Questions?

Contact: Will Anderson andersonwilliam85@gmail.com
Repo: https://github.com/andersonwilliam85/prism
Issues: https://github.com/andersonwilliam85/prism/issues