Artifact Management Design and Troubleshooting using Nexus Repository

In modern infrastructure configurations where CI/CD pipeline automation is advancing, it is difficult to fully guarantee deployment consistency and reproducibility through source code management (SCM) optimization alone. Storing binary artifacts (JAR, WAR, npm packages, Docker images, etc.) generated by the build process directly in SCM is considered an anti-pattern as it leads to repository bloat and performance degradation. To centrally manage these build artifacts and external dependency libraries and build a highly reliable delivery line, the introduction of a dedicated artifact repository is essential.

1. The Three Major Topology Designs of Nexus Repository

Nexus Repository achieves efficient package delivery by combining three types of repositories with different roles (Hosted, Proxy, and Group).

• Hosted Repository: An area for storing unique private packages developed and built within the organization. It hosts highly confidential modules that are not made public, as well as build artifacts deployed directly from CI/CD pipelines.
• Proxy Repository: Acts as a cache proxy for public registries such as Maven Central, npmjs.org, and Docker Hub. Once a dependency is downloaded, it is cached in the local Blob Store, reducing traffic to the external network and significantly improving build speeds for subsequent runs.
• Group Repository: A layer that virtually integrates multiple Hosted and Proxy repositories into a single endpoint. Developers and CI/CD clients can transparently access both internal artifacts and external libraries by referencing only this single URL.

2. Client Integration Implementation Details

2.1 Maven Integration Settings (settings.xml)

Configuration for blocking direct external access and routing through the Nexus Group repository during a Maven build.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemalocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
<mirrors>
<mirror>
<id>nexus-group</id>
<mirrorof>*</mirrorof>
<name>Internal Nexus Group Repository</name>
<url>http://nexus.internal.net/repository/maven-public/</url>
</mirror>
</mirrors>
<servers>
<server>
<id>nexus-group</id>
<username>deployment-user</username>
<password>SecurePassword123!</password>
</server>
</servers>
</settings>

2.2 Docker Daemon Integration Settings (daemon.json)

Application of settings for verification environments or proxy mirror specifications when using Nexus as a private Docker registry via HTTP communication.

{
  "registry-mirrors": [
    "https://nexus.internal.net/repository/docker-proxy/"
  ],
  "insecure-registries": [
    "nexus.internal.net:5001"
  ]
}

3. Lifecycle Management and Cleanup Policies

The most frequent issue in artifact repository operations is storage capacity exhaustion caused by “Snapshots” and temporary images generated with every build. Automation of lifecycle management is required to prevent this.

1. Formulation of Component Cleanup Policies

• Snapshot repositories: Automatic deletion of artifacts not updated within the last 14 days that are not release versions.
• Docker registries: Purging of untagged (dangling) images or images exceeding a specific retention period (e.g., 30 days).

2. Blob Store Compaction (Task Scheduling)

• In Nexus, deleting a component does not immediately free up disk space. Configuration of a schedule to periodically run the “Admin - Compact blob store” task is necessary to physically delete logically deleted data.

4. Troubleshooting

💡 Friction Point 1: Write errors due to Blob Store exhaustion (HTTP 500 / Read-only Mode)

• Cause: When disk usage exceeds a threshold (default is 90%), Nexus automatically shifts the Blob Store to Read-only mode to prevent data corruption.
• Countermeasure: Manual deletion of unnecessary metadata or old Snapshots via tasks. Execution of the Blob Store compaction task to release physical disk space.

⚠️ Friction Point 2: SSL handshake errors via Proxy Repository (PKIX path building failed)

• Cause: If an internal proxy or SSL visualization appliance is present, the certificate chain for external registries may be broken, causing the JVM running Nexus to reject the connection.
• Countermeasure: Acquisition of the certificate for the target host from the Nexus administration screen (Security -> SSL Certificates) and addition to the Nexus Truststore.

5. Operational Verification Logs

Simulation of verification terminal logs to confirm normal operability after infrastructure construction.

$ curl -I -u deployment-user:SecurePassword123! http://nexus.internal.net/service/rest/v1/status
HTTP/1.1 200 OK
Date: Thu, 09 Jul 2026 09:00:00 GMT
Server: Nexus/3.68.0-01 (OSS)
X-Content-Type-Options: nosniff
Content-Length: 0

$ docker login nexus.internal.net:5001 -u deployment-user -p SecurePassword123!
WARNING! Using --password via the CLI is insecure. Use --password-stdin.
Login Succeeded

$ docker pull nexus.internal.net:5001/alpine:3.18
3.18: Pulling from alpine
Digest: sha256:48d818124339491250f023456789abcdef1234567890abcdef1234567890ab
Status: Downloaded newer image for nexus.internal.net:5001/alpine:3.18

6. Operational Notes

Integrating Nexus Repository into a CI/CD pipeline goes beyond merely securing storage; it directly leads to faster builds, improved resilience against external failures, and enhanced supply chain security. Correctly understanding the characteristics of Hosted, Proxy, and Group repositories and incorporating appropriate cleanup policies and disk monitoring into the design are the keys to long-term stable operation.