How to Monitor Verdaccio (Private npm Registry) with Vigilmon

Verdaccio is the go-to self-hosted private npm registry for teams that need to publish internal packages, cache public registry traffic, or air-gap their Node.js dependency pipeline. When Verdaccio goes down, every npm install in your CI pipeline fails — silently, with cryptic "package not found" errors that send engineers chasing phantom dependency issues.

This tutorial shows you how to set up comprehensive monitoring for Verdaccio using Vigilmon, so you catch registry downtime before your developers do.

Why monitoring a private npm registry is non-negotiable

Verdaccio runs as a single-process Node.js application. It has no built-in high-availability mode, no automatic failover, and no alerting when it crashes. In production environments, this means:

• CI pipelines fail mysteriously — npm install exits with a 404 or ECONNREFUSED, and engineers spend 20 minutes debugging before realizing the registry is down
• Publish operations silently fail — developers run npm publish and the package never appears; no error is thrown until the next team member tries to install it
• Storage backend failures go unnoticed — if Verdaccio's underlying filesystem or S3 backend has a permissions error, reads succeed but writes silently discard packages
• Web UI inaccessible during package searches — teams searching for packages via the browser UI get no feedback that the service is degraded

External monitoring gives you an objective, outside-in view of whether the registry is actually serving requests — which is the only thing that matters.

What you'll need

• A running Verdaccio instance (self-hosted, Docker, or Kubernetes)
• A free Vigilmon account — no credit card required

Step 1: Identify your Verdaccio health endpoints

Verdaccio exposes several HTTP endpoints you can use for monitoring:

| Endpoint | Purpose | |----------|---------| | /-/ping | Lightweight health probe — returns {} with HTTP 200 | | / | Web UI root — confirms the interface is rendering | | /-/packages | Lists all packages — confirms storage backend is readable | | /:packageName | Package metadata — confirms a specific package is accessible |

The /-/ping endpoint is the best choice for high-frequency uptime checks — it's fast, lightweight, and returns a deterministic response. For deeper checks that verify storage is working, monitor /-/packages at a lower frequency.

Step 2: Set up HTTP uptime monitoring in Vigilmon

Monitor 1: Registry ping (primary health check)

1. Log in to vigilmon.online and navigate to Monitors → New Monitor
2. Select HTTP / HTTPS as the monitor type
3. Set the URL to your Verdaccio ping endpoint:

   https://registry.your-domain.com/-/ping
   

4. Set the check interval to 1 minute
5. Under Expected response, configure:
   • Status code: 200
   • Response body contains: {}
6. Save the monitor

This check verifies that the Verdaccio process is running and responding to HTTP requests. If the Node.js process crashes or the server runs out of file descriptors, this check will fail within 60 seconds.

Monitor 2: Web UI availability

1. Create a second monitor, HTTP / HTTPS
2. Set the URL to the Verdaccio root:

   https://registry.your-domain.com/
   

3. Expected status code: 200
4. (Optional) Response body contains: Verdaccio or the custom title if you've configured one
5. Set the interval to 5 minutes — the UI changes less frequently than the API

Monitor 3: Package listing endpoint

1. Create a third monitor, HTTP / HTTPS
2. Set the URL to:

   https://registry.your-domain.com/-/packages
   

3. Expected status code: 200
4. Check interval: 5 minutes

This check exercises Verdaccio's storage backend. If packages exist but the storage layer (local filesystem or S3) is broken, this endpoint will return an error while /-/ping still succeeds — so both monitors provide complementary coverage.

Step 3: Monitor the TCP port

HTTP checks verify application-level health. TCP checks verify network-level reachability — useful for catching firewall rule changes, Docker network failures, or port binding issues.

1. In Vigilmon, go to Monitors → New Monitor
2. Choose TCP Port as the type
3. Enter your Verdaccio server's hostname and port (default: 4873):
   • Host: registry.your-domain.com
   • Port: 4873
4. Check interval: 1 minute
5. Save the monitor

If you're running Verdaccio behind a reverse proxy (nginx, Caddy, Traefik), also monitor port 443 on the proxy host:

• Host: registry.your-domain.com
• Port: 443

Step 4: Verify your Verdaccio configuration exposes the right endpoints

Make sure your Verdaccio config.yaml has health-check-compatible settings:

# config.yaml

storage: /verdaccio/storage
auth:
  htpasswd:
    file: /verdaccio/conf/htpasswd

uplinks:
  npmjs:
    url: https://registry.npmjs.org/

packages:
  '@mycompany/*':
    access: $authenticated
    publish: $authenticated

  '**':
    access: $all        # Allow unauthenticated access to package metadata
    proxy: npmjs

# Health checks on /-/ping should work without auth
security:
  api:
    jwt:
      sign:
        expiresIn: 29d

listen: 0.0.0.0:4873

# Logging — useful for correlating with downtime alerts
log:
  type: stdout
  format: pretty
  level: http

If your registry requires authentication for all routes (including /-/ping), Vigilmon supports HTTP Basic Auth and Bearer token authentication. Configure this under Advanced settings when creating the monitor:

• Set Authentication to Basic
• Enter a read-only service account username and password

Step 5: Add a Docker health check (if running in Docker)

If you deploy Verdaccio in Docker, add a native health check so container orchestrators can also detect failures:

# Dockerfile or docker-compose.yml override
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:4873/-/ping || exit 1

Or in docker-compose.yml:

services:
  verdaccio:
    image: verdaccio/verdaccio:5
    ports:
      - "4873:4873"
    volumes:
      - verdaccio_storage:/verdaccio/storage
      - ./config.yaml:/verdaccio/conf/config.yaml:ro
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:4873/-/ping"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s
    restart: unless-stopped

volumes:
  verdaccio_storage:

The Docker health check and Vigilmon work in complementary layers: Docker health checks restart the container on failure; Vigilmon alerts your team before, during, and after recovery.

Step 6: Configure alert channels

1. Go to Alert Channels → Add Channel in Vigilmon
2. Choose your notification method:
   • Slack / Discord — instant webhook alerts in your #ops or #devops channel
   • Email — for escalations or on-call rotations
   • PagerDuty / Opsgenie — for 24/7 on-call teams

For a Verdaccio registry, we recommend:

• Immediate Slack alert when the /-/ping check fails (CI pipelines break instantly)
• Email escalation if the outage lasts more than 5 minutes
• Separate alert for the package listing endpoint routed to your storage/infra team

Step 7: Create a status page

If your registry serves multiple teams, a status page lets developers self-diagnose before filing a support ticket.

1. Go to Status Pages → New Status Page
2. Add all your Verdaccio monitors
3. Name each monitor descriptively: "npm Registry API", "Registry Web UI", "Package Storage"
4. Publish the page

Share the status page URL in your internal developer docs so engineers know where to check when npm install fails.

Complete monitor setup summary

| Monitor | Type | URL / Host:Port | Interval | Catches | |---------|------|-----------------|----------|---------| | Registry ping | HTTP | /-/ping | 1 min | Process crash, OOM, startup failure | | Web UI | HTTP | / | 5 min | Template/static asset errors | | Package listing | HTTP | /-/packages | 5 min | Storage backend failures | | Registry port | TCP | :4873 | 1 min | Network, firewall, port binding issues | | Proxy HTTPS | TCP | :443 | 1 min | Reverse proxy failures |

Conclusion

Verdaccio is a critical piece of infrastructure for any team that depends on private npm packages or cached public dependencies. A few minutes of downtime translates directly into broken CI pipelines and frustrated developers.

With Vigilmon's 1-minute checks and instant alert delivery, you'll know about Verdaccio outages before anyone files a bug report. Set it up once and stop worrying about your registry.

Get started free at vigilmon.online — no credit card required.