verdaccio

packaged by Chainguard

Chainguard Container for verdaccio

Verdaccio is a lightweight private npm proxy registry that hosts your own packages and caches the ones you install from upstream registries.

Chainguard Containers are regularly-updated, secure-by-default container images.

Download this Container Image

For those with access, this container image is available on cgr.dev:

docker pull cgr.dev/ORGANIZATION/verdaccio:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

Compatibility Notes

The verdaccio image is a drop-in replacement for the upstream Verdaccio image. It keeps the launch contract that upstream image established, so an existing docker run, Compose file, or Helm release keeps working when you swap the reference:

The entrypoint, command, environment variables, working directory, port 4873, and runtime user 10001 are all unchanged, as is the ownership of /verdaccio/storage and /verdaccio/conf, so a volume written by the upstream image stays readable and writable after the switch. The uid_entrypoint shim is kept too, so platforms that assign arbitrary UIDs, such as OpenShift, continue to work.

There are three intentional differences:

• The image is built on Chainguard OS rather than Alpine, and Node.js comes from Chainguard's own package rather than the node:24-alpine base image.
• npm, npx, and corepack are not installed. The upstream image inherits them from its Node.js base image, but Verdaccio does not need a package manager to serve a registry. See the note below if you install plugins.
• openssl is not installed. Upstream includes it so that operators can generate a TLS key pair inside the container, but Verdaccio never invokes it, and Node uses the system OpenSSL libraries. Generate certificates outside the container, or use the -dev variant, which includes a shell and a package manager.

Verdaccio's plugin documentation installs plugins with npm install inside the running container. That does not work here: neither this image nor its -dev variant ships npm, and a plugin installed into a container is lost when the container is replaced in any case.

Install plugins with a package manager in a build stage and copy them in, which also pins them into the image rather than leaving them to be re-fetched at runtime:

cat > Dockerfile <<EOF
FROM cgr.dev/ORGANIZATION/node:24-dev AS plugins
USER root
RUN npm install --prefix /build --global-style --no-bin-links --omit=optional verdaccio-auth-memory

FROM cgr.dev/ORGANIZATION/verdaccio:latest
COPY --from=plugins --chown=10001:0 /build/node_modules /verdaccio/plugins
EOF

Verdaccio resolves a plugin named in its configuration against the plugins directory, mapping a key such as auth-memory to verdaccio-auth-memory on disk. To add one without rebuilding, mount a directory with that same layout at /verdaccio/plugins.

--global-style matters here. Without it npm hoists the plugin's own dependencies alongside it rather than under it, and since /verdaccio/plugins is not a node_modules directory, Node cannot resolve them from the plugin. The builder is pinned to the same Node major the image runs so that a plugin with a native addon is built against the matching ABI.

There is no FIPS variant of this image. Verdaccio's bundled verdaccio-htpasswd authentication plugin hashes passwords with bcrypt. Switching it to PBKDF2 would change the stored-hash format, and htpasswd is an interoperable format operators generate elsewhere and mount in, so existing credential files would stop verifying.

Prerequisites

Verdaccio stores package tarballs, metadata, and its htpasswd file under /verdaccio/storage. Mount a volume there for anything beyond a throwaway registry, otherwise every published package is lost when the container is replaced.

The storage directory is owned by UID 10001. When you mount a host directory rather than a named volume, set its ownership to match, or the registry cannot write to it.

Getting Started

Start a registry with the shipped default configuration:

docker run -d --name verdaccio -p 4873:4873 cgr.dev/ORGANIZATION/verdaccio:latest

Confirm it is serving:

curl -s -w '\nHTTP status: %{http_code}\n' http://localhost:4873/-/ping

Expected result:

{}
HTTP status: 200

The web UI is served on the same port. Open localhost:4873 in a browser to browse published packages, search, and sign in.

Publishing requires an account. The default configuration lets anyone register one:

npm adduser --registry http://localhost:4873

Publish a package from a project directory:

npm publish --registry http://localhost:4873

+ @my-org/my-package@1.0.0

Install it back through the registry:

npm install @my-org/my-package --registry http://localhost:4873

Use a scope you own, as above. The default configuration proxies everything it does not hold locally to registry.npmjs.org, so publishing under a name that already exists there is rejected, and installing it would quietly fetch the public package instead of yours.

To persist packages across container replacements, mount a volume at /verdaccio/storage. Replace the container started above, which still holds the name and the port:

docker rm -f verdaccio
docker run -d --name verdaccio \
  -p 4873:4873 \
  -v verdaccio-storage:/verdaccio/storage \
  cgr.dev/ORGANIZATION/verdaccio:latest

Configuration

Verdaccio reads a single YAML file, and the default command points at /verdaccio/conf/config.yaml. The shipped default proxies anything it does not hold locally to registry.npmjs.org and caches the result, which is the behavior most teams want from a private registry.

The setting worth changing first is which packages stay private. Scoping your organization's packages to a pattern with no proxy key means Verdaccio never asks a public registry about them, which closes off dependency-confusion attacks where a public package of the same name shadows yours:

cat > config.yaml <<EOF
storage: /verdaccio/storage/data
plugins: /verdaccio/plugins

auth:
  htpasswd:
    file: /verdaccio/storage/htpasswd
    max_users: -1

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

packages:
  '@my-org/*':
    access: \$authenticated
    publish: \$authenticated
    unpublish: \$authenticated

  '**':
    access: \$all
    publish: \$authenticated
    unpublish: \$authenticated
    proxy: npmjs

middlewares:
  audit:
    enabled: true
EOF

Two details in that file matter. max_users: -1 disables self-registration once you have created the accounts you need, so the registry does not accept new users from anyone who can reach it. The @my-org/* block has no proxy key, so those packages are served only from local storage.

Because max_users: -1 refuses new registrations, create the accounts you need before applying this file. The verdaccio-storage volume introduced above is empty, so register against the container that is using it:

npm adduser --registry http://localhost:4873

Accounts live in htpasswd on that volume, so they persist into the container started below.

Mount it over the default and start the container:

docker rm -f verdaccio
docker run -d --name verdaccio \
  -p 4873:4873 \
  -v verdaccio-storage:/verdaccio/storage \
  -v "$(pwd)/config.yaml:/verdaccio/conf/config.yaml:ro" \
  cgr.dev/ORGANIZATION/verdaccio:latest

The listen address is assembled from environment variables, so you can change the port without replacing the command:

docker rm -f verdaccio
docker run -d --name verdaccio \
  -p 8080:8080 \
  -e VERDACCIO_PORT=8080 \
  cgr.dev/ORGANIZATION/verdaccio:latest

To deploy on Kubernetes, use the Verdaccio Helm chart with the image overridden:

cat > values.yaml <<EOF
image:
  repository: cgr.dev/ORGANIZATION/verdaccio
  tag: latest

persistence:
  enabled: true
  size: 8Gi
EOF

helm repo add verdaccio https://charts.verdaccio.org
helm install verdaccio verdaccio/verdaccio --values values.yaml

The chart runs the pod as UID 10001, which is the user this image already ships, so no securityContext override is needed.

Documentation and Resources

• Verdaccio documentation
• Verdaccio configuration reference
• Verdaccio best practices
• Verdaccio source repository
• Chainguard Academy

What are Chainguard Containers?

Chainguard's free tier of Starter container images are built with Wolfi, our minimal Linux undistro.

All other Chainguard Containers are built with Chainguard OS, Chainguard's minimal Linux operating system designed to produce container images that meet the requirements of a more secure software supply chain.

The main features of Chainguard Containers include:

• Minimal design, without unnecessary software bloat
• Daily builds to ensure container images are up-to-date with available security patches
• High quality build-time SBOMs attesting to the provenance of all artifacts within the image
• Verifiable signatures provided by Sigstore
• Reproducible builds with Cosign and apko (read more about reproducibility)

For cases where you need container images with shells and package managers to build or debug, most Chainguard Containers come paired with a development, or -dev, variant.

In all other cases, including Chainguard Containers tagged as :latest or with a specific version number, the container images include only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager.

Although the -dev container image variants have similar security features as their more minimal versions, they include additional software that is typically not necessary in production environments. We recommend using multi-stage builds to copy artifacts from the -dev variant into a more minimal production image.

Need additional packages?

To improve security, Chainguard Containers include only essential dependencies. Need more packages? Chainguard customers can use Custom Assembly to add packages, either through the Console, chainctl, or API.

To use Custom Assembly in the Chainguard Console: navigate to the image you'd like to customize in your Organization's list of images, and click on the Customize image button at the top of the page.

Learn More

Refer to our Chainguard Containers documentation on Chainguard Academy. Chainguard also offers VMs and Libraries — contact us for access.

Trademarks

This software listing is packaged by Chainguard. The trademarks set forth in this offering are owned by their respective companies, and use of them does not imply any affiliation, sponsorship, or endorsement by such companies.