Verdaccio

beginner

Lightweight private npm proxy registry.

Overview

Verdaccio is a lightweight, zero-configuration private npm registry proxy built on Node.js that serves as an intermediary between your development environment and public npm registries. Originally forked from the Sinopia project in 2017, Verdaccio has become the de facto solution for organizations needing to host private npm packages while maintaining access to the public npm ecosystem. It automatically caches packages from upstream registries like npmjs.org on first request, reducing bandwidth usage and improving package installation speeds for subsequent requests. This Docker deployment creates a self-contained npm registry server that can proxy public packages, host private packages, and manage user authentication all through a simple web interface. Verdaccio acts as both a private package repository and a smart caching layer, storing frequently used packages locally while transparently fetching new packages from upstream sources. The containerized setup includes persistent storage for packages, configuration files, and plugins, ensuring your registry data survives container restarts and updates. Development teams, DevOps engineers managing Node.js applications, and organizations with strict security requirements will find this setup invaluable for controlling package distribution and reducing external dependencies. Companies needing to publish internal libraries, mirror critical packages for air-gapped environments, or simply speed up CI/CD pipelines by caching npm packages locally can deploy this registry in minutes and immediately start benefiting from faster, more reliable package management.

Key Features

Zero-configuration private npm registry with automatic package proxying from npmjs.org
Built-in web interface for browsing packages, managing users, and viewing registry statistics
Intelligent package caching that stores upstream packages locally after first download
Support for npm, Yarn, and pnpm package managers with standard registry configuration
Flexible authentication system supporting htpasswd, LDAP, and plugin-based user management
Scoped package support for organizing private packages by team or project namespace
Plugin architecture for extending functionality with custom storage backends and authentication providers
Configurable package filtering and access control rules for fine-grained permission management

Common Use Cases

1Private package hosting for proprietary libraries and internal company modules
2Caching npm packages in corporate environments to reduce external bandwidth usage
3Creating air-gapped package registries for secure development environments
4Speeding up CI/CD pipelines by serving cached packages from local network storage
5Managing package versions and preventing supply chain attacks through controlled package distribution
6Development team collaboration with shared private packages across multiple projects
7Offline development environments where internet access to npmjs.org is limited or unreliable

Prerequisites

Docker Engine 20.10+ and Docker Compose V2 for container orchestration
Minimum 512MB RAM available for Verdaccio container and package caching
Port 4873 available on host system for web interface and npm registry access
At least 5GB free disk space for package storage and cache growth
Basic understanding of npm registry configuration and package.json files
Network access to npmjs.org if using upstream package proxying features

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  verdaccio: 
3    image: verdaccio/verdaccio:latest
4    container_name: verdaccio
5    restart: unless-stopped
6    ports: 
7      - "4873:4873"
8    volumes: 
9      - verdaccio_storage:/verdaccio/storage
10      - verdaccio_conf:/verdaccio/conf
11      - verdaccio_plugins:/verdaccio/plugins
12
13volumes: 
14  verdaccio_storage: 
15  verdaccio_conf: 
16  verdaccio_plugins:

.env Template

.env

1# Configure npm to use: npm set registry http://localhost:4873

Usage Notes

1Docs: https://verdaccio.org/docs/what-is-verdaccio
2Access UI at http://localhost:4873
3Configure npm: npm set registry http://localhost:4873
4Create user: npm adduser --registry http://localhost:4873
5Publish: npm publish --registry http://localhost:4873
6Caches upstream npmjs.org packages automatically on first request

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  verdaccio:
5    image: verdaccio/verdaccio:latest
6    container_name: verdaccio
7    restart: unless-stopped
8    ports:
9      - "4873:4873"
10    volumes:
11      - verdaccio_storage:/verdaccio/storage
12      - verdaccio_conf:/verdaccio/conf
13      - verdaccio_plugins:/verdaccio/plugins
14
15volumes:
16  verdaccio_storage:
17  verdaccio_conf:
18  verdaccio_plugins:
19EOF
20
21# 2. Create the .env file
22cat > .env << 'EOF'
23# Configure npm to use: npm set registry http://localhost:4873
24EOF
25
26# 3. Start the services
27docker compose up -d
28
29# 4. View logs
30docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/verdaccio/run | bash

Troubleshooting

npm ERR! 404 Not Found: Verify the package exists in upstream registry and Verdaccio proxy configuration allows fetching
Web interface shows 'Cannot connect to registry': Check container is running and port 4873 is properly mapped to host
npm publish fails with authentication error: Run 'npm adduser --registry http://localhost:4873' to create user account first
Packages not persisting after container restart: Ensure Docker volumes are properly mounted and not using temporary storage
Slow package installation from cache: Check available disk space as Verdaccio may be unable to cache packages when storage is full
Cannot access registry from other machines: Bind to 0.0.0.0:4873 instead of localhost:4873 in npm configuration

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

verdaccio

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download