# Verdaccio npm Registry + LDAP

> Lightweight private npm registry with LDAP authentication.

- Category: DevOps & CI/CD
- Difficulty: beginner
- Components: verdaccio, nginx
- Tags: verdaccio, npm, registry, javascript, nodejs
- Source: https://docker.recipes/devops/verdaccio-registry

## 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.

## 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

## Use cases

- Enterprise development teams maintaining proprietary JavaScript libraries and components
- Organizations requiring offline npm package access in air-gapped environments
- Companies needing LDAP-based authentication for developer tool access control
- Development teams wanting faster npm install times through local package caching
- Organizations publishing internal packages while restricting access to specific user groups
- Companies migrating from hosted npm solutions to self-managed infrastructure
- Development 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

## docker-compose.yml

```yaml
services:
  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:
    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

volumes:
  verdaccio-storage:
  verdaccio-plugins:

networks:
  verdaccio-network:
    driver: bridge
```

## .env

```bash
# Verdaccio npm Registry
# npm set registry http://localhost:4873
# npm adduser --registry http://localhost:4873

# config.yaml configures authentication and uplinks
```

## Usage notes

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

## 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

