npm Registry (Verdaccio)

Private npm package registry powered by Verdaccio.

URL: npm.registry.hochguertel.work

Features

  • Private npm packages with scoped publishing
  • Proxies to npmjs.org for public packages
  • Authelia OIDC single sign-on
  • Web UI for browsing packages
  • Group-based access control (developers can publish)

Quick Start

npm set registry https://npm.registry.hochguertel.work
npm login --registry https://npm.registry.hochguertel.work
npm publish

Package Scopes

| Scope | Access | Publish | Proxy | |-------|--------|---------|-------| | @copilot-webui/* | Authenticated | developers | No (local only) | | @histoire/* | All | developers | Yes (npmjs fallback) | | @*/* | All | developers | Yes | | ** | All | developers | Yes |

Developer Guide

Configure Registry

# Set as default registry
npm set registry https://npm.registry.hochguertel.work

# Or per-project in .npmrc
echo "registry=https://npm.registry.hochguertel.work" > .npmrc

Login

npm login --registry https://npm.registry.hochguertel.work
# Opens browser → Authelia login → token saved to ~/.npmrc

Verify

npm whoami --registry https://npm.registry.hochguertel.work

Publishing Packages

# Publish a package
npm publish --registry https://npm.registry.hochguertel.work

# Publish a scoped package
npm publish --scope=@copilot-webui --registry https://npm.registry.hochguertel.work

Installing Packages

# Public packages are proxied through Verdaccio
npm install lodash

# Private packages are served directly
npm install @copilot-webui/my-package

Using in CI/CD

Create a .npmrc in your project:

registry=https://npm.registry.hochguertel.work
//npm.registry.hochguertel.work/:_authToken=${NPM_TOKEN}

Set NPM_TOKEN as a CI environment variable.

DevOps Guide

Architecture

Verdaccio runs as a single container with OIDC authentication via Authelia.

  • Image: Custom build from verdaccio/verdaccio:6 with verdaccio-openid-connect plugin
  • Port: 4873 (internal)
  • Storage: Bind mount at data/npm/storage/
  • Config: npm/conf/config.yaml

Management

cd /opt/services/registries

# Start/stop
task up:npm
task down:npm

# Logs
task logs:npm

# Health check
curl -sf https://npm.registry.hochguertel.work/-/ping

Configuration

Edit npm/conf/config.yaml for:

  • Package scopes and access rules
  • Uplink (proxy) configuration
  • Authentication settings
  • Logging level

After changes, restart:

task down:npm && task up:npm

Backup

tar -czf npm-backup-$(date +%Y%m%d).tar.gz data/npm/storage/