Verdaccio npm Registry + LDAP

beginner

Lightweight private npm registry with LDAP authentication.

Overview

Verdaccio is a lightweight private npm registry server that enables organizations to host their own JavaScript packages while maintaining full control over their code distribution. Built on Node.js, Verdaccio acts as both a private package repository and a caching proxy for public npm packages, reducing dependency on external registries and improving installation speeds. This configuration integrates Verdaccio with NGINX as a reverse proxy, providing SSL termination, request routing, and enhanced security features for enterprise environments. The combination of Verdaccio and NGINX creates a production-ready private npm registry infrastructure that can handle authentication, package publishing, and high-traffic scenarios. NGINX serves as the front-facing web server, managing SSL certificates, request compression, and load balancing, while Verdaccio focuses solely on npm registry operations including package storage, version management, and upstream proxy functionality to npmjs.org. This stack is ideal for development teams, enterprises, and organizations that need to maintain private JavaScript packages while ensuring fast, reliable access to both internal and public npm packages. The LDAP authentication integration makes it particularly valuable for companies with existing Active Directory infrastructure who need centralized user management for their development tools.

Key Features

Private npm package publishing and hosting with configurable access controls per package
Upstream proxy to npmjs.org with intelligent caching to reduce external dependencies
LDAP authentication integration for seamless Active Directory and enterprise directory services
Scoped package support for organization-specific namespaces (@company/package-name)
Web UI for package browsing, user management, and repository statistics
Automatic package metadata synchronization with upstream registries
NGINX SSL termination with HTTP/2 support and configurable security headers
Plugin architecture for extending Verdaccio functionality with custom authentication and storage backends

Common Use Cases

1Enterprise development teams maintaining proprietary JavaScript libraries and components
2Organizations requiring offline npm package access in air-gapped environments
3Companies needing LDAP-based authentication for developer tool access control
4Development teams wanting faster npm install times through local package caching
5Organizations publishing internal packages while restricting access to specific user groups
6Companies migrating from hosted npm solutions to self-managed infrastructure
7Development environments requiring package version control and security scanning

Prerequisites

Docker and Docker Compose installed with minimum 512MB available RAM
LDAP server details including bind DN, search base, and connection credentials
SSL certificates for HTTPS access or domain validation for Let's Encrypt integration
Network access to upstream npm registry (npmjs.org) unless running in offline mode
Understanding of npm client configuration for registry URL modification
Basic knowledge of Verdaccio configuration syntax and NGINX proxy setup

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    environment: 
5      - VERDACCIO_PORT=4873
6    volumes: 
7      - verdaccio-storage:/verdaccio/storage
8      - verdaccio-plugins:/verdaccio/plugins
9      - ./config.yaml:/verdaccio/conf/config.yaml:ro
10    ports: 
11      - "4873:4873"
12    networks: 
13      - verdaccio-network
14    restart: unless-stopped
15
16  nginx: 
17    image: nginx:alpine
18    volumes: 
19      - ./nginx.conf:/etc/nginx/nginx.conf:ro
20    ports: 
21      - "80:80"
22      - "443:443"
23    depends_on: 
24      - verdaccio
25    networks: 
26      - verdaccio-network
27    restart: unless-stopped
28
29volumes: 
30  verdaccio-storage: 
31  verdaccio-plugins: 
32
33networks: 
34  verdaccio-network: 
35    driver: bridge

.env Template

.env

1# Verdaccio npm Registry
2# npm set registry http://localhost:4873
3# npm adduser --registry http://localhost:4873
4
5# config.yaml configures authentication and uplinks

Usage Notes

1Registry at http://localhost:4873
2Configure npm client to use registry
3Proxy to npmjs.org for public packages
4HTPASSWD auth by default
5Supports scoped packages

Individual Services(2 services)

Copy individual services to mix and match with your existing compose files.

verdaccio

verdaccio:
  image: verdaccio/verdaccio:latest
  environment:
    - VERDACCIO_PORT=4873
  volumes:
    - verdaccio-storage:/verdaccio/storage
    - verdaccio-plugins:/verdaccio/plugins
    - ./config.yaml:/verdaccio/conf/config.yaml:ro
  ports:
    - "4873:4873"
  networks:
    - verdaccio-network
  restart: unless-stopped

nginx

nginx:
  image: nginx:alpine
  volumes:
    - ./nginx.conf:/etc/nginx/nginx.conf:ro
  ports:
    - "80:80"
    - "443:443"
  depends_on:
    - verdaccio
  networks:
    - verdaccio-network
  restart: unless-stopped

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  verdaccio:
5    image: verdaccio/verdaccio:latest
6    environment:
7      - VERDACCIO_PORT=4873
8    volumes:
9      - verdaccio-storage:/verdaccio/storage
10      - verdaccio-plugins:/verdaccio/plugins
11      - ./config.yaml:/verdaccio/conf/config.yaml:ro
12    ports:
13      - "4873:4873"
14    networks:
15      - verdaccio-network
16    restart: unless-stopped
17
18  nginx:
19    image: nginx:alpine
20    volumes:
21      - ./nginx.conf:/etc/nginx/nginx.conf:ro
22    ports:
23      - "80:80"
24      - "443:443"
25    depends_on:
26      - verdaccio
27    networks:
28      - verdaccio-network
29    restart: unless-stopped
30
31volumes:
32  verdaccio-storage:
33  verdaccio-plugins:
34
35networks:
36  verdaccio-network:
37    driver: bridge
38EOF
39
40# 2. Create the .env file
41cat > .env << 'EOF'
42# Verdaccio npm Registry
43# npm set registry http://localhost:4873
44# npm adduser --registry http://localhost:4873
45
46# config.yaml configures authentication and uplinks
47EOF
48
49# 3. Start the services
50docker compose up -d
51
52# 4. View logs
53docker 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-registry/run | bash

Troubleshooting

npm ERR! 401 Unauthorized: Verify LDAP configuration in config.yaml and test LDAP bind credentials
Package publishing fails with storage errors: Check verdaccio-storage volume permissions and available disk space
NGINX returns 502 Bad Gateway: Ensure Verdaccio container is running and accessible on port 4873
LDAP authentication timeout: Increase LDAP connection timeout values and verify network connectivity to LDAP server
npm install hanging on private packages: Check Verdaccio uplinks configuration and upstream registry connectivity
Web UI not accessible through NGINX: Verify proxy_pass configuration includes trailing slash and proper headers

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

verdaccionginx

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download