Sonatype Nexus Repository

Sonatype Nexus Repository is a universal binary repository manager: one server that stores every package format a build produces or consumes — Maven jars, npm packages, Docker images, Python wheels, and a dozen others — and caches the public registries those builds pull from, so a team has exactly one internal URL to trust instead of the raw internet. It is the tool most engineers reach for second, right after JFrog Artifactory, and that ordering is telling: the two products solve the same problem in almost the same way, with a genuinely free self-hosted edition as Nexus's calling card and a broader out-of-the-box format catalog as Artifactory's. This page covers what Nexus actually does, the config and API calls you write against it day to day, where it breaks, and an honest comparison that doesn't pretend the choice is bigger than it usually is.

What Nexus Repository is and the problem it solves

☺ Like you're 10: Nexus is the one place your build is allowed to fetch dependencies from and the one place it's required to publish its own — everything else talks to Nexus, not the open internet.

Before a repository manager sits in front of a pipeline, every build talks directly to the public internet for everything it needs: npm install hits npmjs.org, pip install hits PyPI, docker pull hits Docker Hub, and a Maven or Gradle build hits Maven Central. That works fine until the day a public registry has an outage during your release window, a maintainer unpublishes a package version your build depends on, or your org's outbound IP gets rate-limited because forty CI runners are all pulling the same base image at once. It also leaves nowhere obvious to publish artifacts that are yours and yours alone — an internal library, a nightly build, a release candidate nobody outside the company should ever see. A repository manager fixes all of this by becoming the single door: builds resolve dependencies against it, publish artifacts to it, and never talk to the public internet directly at all.

Sonatype's specific claim to this space isn't incidental. The company was founded in 2008 by Jason van Zyl — the creator of Apache Maven — and Sonatype operates the infrastructure behind the Central Repository ("Maven Central"), the public repository nearly every JVM build already resolves against by default. Nexus Repository grew out of that same team's experience running a repository at public-internet scale, which is part of why Maven support in particular still feels like the product's home turf even though it now speaks over a dozen other formats. The current major version, Nexus Repository 3 — a ground-up rewrite of the original Nexus 2 line — has been the actively developed product since 2015; if you inherit an environment still running Nexus 2, treat it as a migration project, not a patch target, since Sonatype's own support and development attention moved on years ago.

Every repository in Nexus, regardless of format, is one of three types, and almost every later section on this page assumes you have these three straight: a hosted repository holds artifacts that exist only in Nexus — your own releases and snapshots; a proxy repository caches one specific upstream (Maven Central, npmjs.org, PyPI, Docker Hub, an internal registry elsewhere) and serves cached copies once it has fetched them; and a group repository has no storage of its own at all — it's an ordered list of member repositories, and clients only ever configure the group's URL, never a specific hosted or proxy repo underneath it.

Where it fits in the pipeline

☺ Like you're 10: Nexus sits between every build and the internet — nothing pulls a dependency or pushes a finished artifact anywhere else.

Dependency resolution during build and test points at a Nexus group URL, not the public registry directly — see CI/CD pipelines for where that fits in the wider stage sequence. Once a build produces something worth keeping, publish or package stages push it to a hosted repository in Nexus — a jar, an npm package, a Docker image — and that publish is what build & artifact management means concretely: an immutable, versioned, retrievable record of exactly what a given commit produced. Downstream, deployment tooling — Argo CD, Helm, a Kubernetes node's kubelet — pulls container images from Nexus's Docker repositories rather than reaching back out to a public registry, closing the loop so the artifact that gets deployed is provably the same bytes the build produced, not a same-tag image that quietly changed underneath it.

The proxy layer earns its keep as a security boundary as much as a performance one. Because every dependency a build ever resolves passes through Nexus on its way in, it's the one place an org can plausibly block a known-malicious package, quarantine a version pending review, or simply keep serving a cached copy of a package a maintainer yanked out from under everyone at 2 a.m. — the "left-pad" failure mode. That's the entry point into Supply-Chain Security & SBOM, which covers the policy side of what a proxy layer like this makes possible in far more depth than this tool page does.

Architecture: repositories, blob stores, and the datastore

☺ Like you're 10: Nexus is one program that keeps two separate ledgers — where the actual bytes live, and what those bytes are called — and most of its behavior falls out of keeping those two ledgers in sync.

Nexus Repository 3 runs as a single Java web application with an embedded HTTP server — there's no separate agent to install on build machines; clients just speak plain HTTP(S) to it, the same as any other web service. Underneath the repository abstraction sit two genuinely separate stores, and most of the "gotchas" section later on this page traces back to the fact that they don't always update in lockstep.

The blob store holds the actual bytes, content-addressed by checksum, on a filesystem path Nexus manages — or, on Pro, in S3-compatible or other cloud object storage (verify current entitlements on Sonatype's own pricing page, since cloud blob store support has moved between tiers before). The metadata datastore tracks what those bytes are called: component coordinates, versions, checksums, which repository they belong to. Deleting a component from the UI or the REST API removes it from the metadata datastore immediately, but the underlying blob isn't reclaimed until a scheduled cleanup or compaction task runs — "I deleted it and the disk didn't shrink" is the single most common first surprise for anyone new to operating Nexus.

The metadata datastore itself has a real history worth knowing before you inherit an old installation: Nexus 3 originally shipped on an embedded OrientDB database, and Sonatype has since moved newer releases onto a different datastore as OrientDB reached its own end of life upstream. If you're responsible for an instance old enough that you aren't sure which one it's on, that's worth checking and planning around deliberately — Sonatype publishes a dedicated migration guide for exactly this transition, and it is not something to attempt for the first time during a maintenance window nobody's watching. Treat any specific version number you find quoted for this transition as a starting point to verify against Sonatype's current documentation rather than a fact to build a runbook on unread.

Repository formats: what's free and what's Pro

☺ Like you're 10: Nearly every format Nexus understands, the free edition understands too — that's the opposite of how most of its direct competitor's history has drawn the line.

Nexus Repository's format catalog is broad, and — this is the point worth remembering — nearly all of it ships in the free, source-available OSS edition rather than being gated behind the commercial Pro tier. Treat the exact list below as accurate for a current Nexus 3 install and verify against Sonatype's own format-support matrix before depending on an edge-case format, since new formats and edition boundaries do shift between releases.

What's genuinely Pro-only sits at the operational and governance layer, not the format layer: High Availability clustering for multi-node deployments; historically, cloud-backed blob stores; SAML single sign-on (LDAP realms are available in OSS); the staging and promotion workflow for releases (upload to a staging repository, run validation, then promote or drop as one atomic step, mostly a Maven-world concept); and priority support with an SLA. Sitting alongside Nexus Repository entirely — sold and licensed separately, not bundled into Repository Pro — is Sonatype Lifecycle (the product long known as Nexus IQ Server / Nexus Lifecycle), which scans components against known vulnerabilities and license policy and can quarantine a component before it ever reaches a build. That separation matters when comparing prices: "Nexus Repository Pro" alone is not the same purchase as adding automated vulnerability policy enforcement.

The config you actually write

☺ Like you're 10: You mostly write two kinds of files — one telling Nexus what a repository should look like, and several telling every other tool where Nexus's front door is.

Standing up an instance

# official image; verify the current tag on Sonatype's Docker Hub page before pinning it long-term
$ docker volume create nexus-data
$ docker run -d -p 8081:8081 --name nexus \
    -v nexus-data:/nexus-data \
    sonatype/nexus3:3.70.1

# first boot generates a random initial admin password — read it, then rotate it immediately
$ docker exec nexus cat /nexus-data/admin.password

Creating a repository via the REST API

The REST API — documented and versioned under /service/rest/v1/ — is the supported path for repository-as-code today; the older Groovy scripting API that used to do this job is disabled or tightly restricted by default in current releases (more on why in the gotchas section below). A Maven proxy of Central looks like this:

$ curl -u admin:$NEXUS_PASSWORD -X POST \
    -H 'Content-Type: application/json' \
    https://nexus.internal.example.com/service/rest/v1/repositories/maven/proxy \
    -d '{
  "name": "maven-central-proxy",
  "online": true,
  "storage": { "blobStoreName": "default", "strictContentTypeValidation": true },
  "proxy": { "remoteUrl": "https://repo1.maven.org/maven2/", "contentMaxAge": 1440 },
  "negativeCache": { "enabled": true, "timeToLive": 1440 },
  "httpClient": { "blocked": false, "autoBlock": true },
  "maven": { "versionPolicy": "RELEASE", "layoutPolicy": "STRICT" }
}'

A hosted Docker repository is where the API surfaces Nexus's one genuinely awkward architectural choice — a dedicated connector port per repository, covered fully below:

$ curl -u admin:$NEXUS_PASSWORD -X POST \
    -H 'Content-Type: application/json' \
    https://nexus.internal.example.com/service/rest/v1/repositories/docker/hosted \
    -d '{
  "name": "docker-hosted",
  "online": true,
  "storage": { "blobStoreName": "default", "strictContentTypeValidation": true, "writePolicy": "ALLOW_ONCE" },
  "docker": { "v1Enabled": false, "forceBasicAuth": true, "httpPort": 8083 }
}'

Pointing every client at it

<!-- ~/.m2/settings.xml — every dependency resolves through the group repo, never Central directly -->
<mirror>
  <id>nexus</id>
  <mirrorOf>*</mirrorOf>
  <url>https://nexus.internal.example.com/repository/maven-public/</url>
</mirror>
<servers>
  <server>
    <id>nexus</id>
    <username>ci-bot</username>
    <password>${env.NEXUS_PASSWORD}</password>
  </server>
</servers>

# .npmrc
registry=https://nexus.internal.example.com/repository/npm-group/
//nexus.internal.example.com/repository/npm-group/:_authToken=${NPM_TOKEN}

# pip.conf
[global]
index-url = https://nexus.internal.example.com/repository/pypi-group/simple

# docker — note the dedicated port; there is no path-based route for a group's Docker member
$ docker login nexus.internal.example.com:8083 -u ci-bot -p $NEXUS_DOCKER_TOKEN
$ docker push nexus.internal.example.com:8083/checkout:1.4.2

Day-to-day operations

☺ Like you're 10: A short list of REST calls covers almost everything: what's in here, find this one thing, put this one thing in, and clean up after yourself on a schedule.

# what repositories exist
$ curl -u admin:$NEXUS_PASSWORD https://nexus.internal.example.com/service/rest/v1/repositories

# search for a specific component
$ curl -u admin:$NEXUS_PASSWORD \
    "https://nexus.internal.example.com/service/rest/v1/search?repository=maven-releases&group=com.acme&name=checkout"

# upload a raw asset (a build report, a tarball, anything without a native format)
$ curl -u ci-bot:$NEXUS_PASSWORD \
    -F "raw.directory=/releases/1.4.2" \
    -F "raw.asset1=@checkout-1.4.2.tar.gz;filename=checkout-1.4.2.tar.gz" \
    "https://nexus.internal.example.com/service/rest/v1/components?repository=raw-hosted"

# trigger a scheduled task on demand (its ID comes from the Tasks admin screen or the tasks endpoint)
$ curl -u admin:$NEXUS_PASSWORD -X POST \
    https://nexus.internal.example.com/service/rest/v1/tasks/<task-id>/run

# blob store disk usage and status
$ curl -u admin:$NEXUS_PASSWORD https://nexus.internal.example.com/service/rest/v1/blobstores/default

The task that keeps Nexus from growing without bound is a cleanup policy (age, last-downloaded date, or version count) attached to a repository, paired with the built-in "Cleanup service" scheduled task that deletes anything the policy matches. Proxy repositories separately enforce a contentMaxAge / metadataMaxAge before revalidating a cached copy against upstream, so a proxy cache does age out its own content even without a cleanup policy — but snapshot and hosted repositories will happily grow forever without one, which is where most disk-full incidents actually come from in practice.

Gotchas and failure modes

☺ Like you're 10: Most of the pain comes from four habits: one Docker repo needing its own door, disk not shrinking right after a delete, nobody ever telling old snapshots to leave, and the front door being left unlocked by default.

Docker needs one connector port per repository. The Docker Registry HTTP API v2 has no concept of a path prefix telling a client "resolve this image against repository X" the way Nexus's other formats route by URL path — so a Docker hosted, proxy, or group repository in Nexus that you want to talk to with the plain docker CLI needs its own dedicated HTTP and/or HTTPS connector port (8083, 8084, and so on), configured on the repository itself and exposed through your reverse proxy or load balancer. This is the single most-cited operational annoyance Nexus has relative to Artifactory, whose reverse-proxy configuration generator maps Docker repositories by path instead. It's a real cost, not a myth — budget for it in your networking design rather than discovering it mid-rollout.

Deleting a component doesn't shrink disk immediately. The metadata reference disappears the moment you delete it, but the blob itself stays in the blob store until a compaction or reconciliation task runs — expect a lag, and schedule that task rather than assuming disk usage tracks deletions in real time.

Unbounded growth without cleanup policies. A proxy cache with no contentMaxAge discipline and a snapshot repository with no cleanup policy both grow without limit — the classic failure mode is a CI runner that fails a deploy with "no space left on device" months after nobody thought to configure retention, because nothing about a default install stops it from happening.

The old scripting API was a real attack surface. Nexus Repository 3's Groovy scripting endpoint has been the source of legitimate, publicly disclosed remote-code-execution advisories in past versions — check Sonatype's own security advisories for the specific CVEs and affected version ranges rather than trusting a number repeated secondhand, since the details matter for whether a given install is actually exposed. The practical takeaway holds regardless of the exact CVE: stay current on patch releases, and prefer the versioned REST API over ad hoc Groovy scripts for anything you're automating today.

Nexus vs. Artifactory: the honest comparison

☺ Like you're 10: These two do almost the exact same job almost the exact same way — the real decision usually comes down to which one your org already knows how to run, not which one has one extra feature.

It's worth saying plainly: for the large majority of teams, Nexus Repository and JFrog Artifactory are close enough in what they actually do day to day that a feature-by-feature bake-off rarely produces a decisive winner. Both give you hosted/proxy/group-style repositories across most of the same formats, both have a real REST API, both integrate with every mainstream CI tool, and both have paying enterprise customers running them at real scale. Where genuine differences exist, they're worth naming honestly rather than dressed up as bigger than they are.

The pragmatic heuristic most teams actually land on: if you're greenfield with no existing licensing relationship on either side and you want a fully-featured, self-hosted product that's free to start with, Nexus OSS is usually the easier "yes" — you aren't negotiating a Pro contract just to get Docker or npm support. If your org is already a JFrog customer — already paying for Xray, already running Artifactory somewhere, already has support contacts on speed dial — staying with Artifactory is almost always cheaper than a migration would be, features aside. What's rarely worth it either direction is ripping out a working, well-understood artifact layer to chase a feature gap that shows up on a comparison chart but doesn't actually block anything your team does today. Team familiarity, existing support relationships, and sunk operational knowledge are legitimate decision factors here, not a cop-out — they're often the correctly weighted ones.

Put the proxy-cache and cleanup-policy habits from this page into practice in Capstone Part 1 — Pipeline Foundation, and go lock down a default-open repository in Drill — Secure a Vulnerable Pipeline.