1. Deploy Nexus with Docker

# Search for official Nexus 3 image
docker search sonatype/nexus3

# Pull the latest Nexus OSS image
docker pull sonatype/nexus3

# Create persistent storage directory
mkdir -p /opt/sonatype-nexus/data
chmod 777 -R /opt/sonatype-nexus/data

# Start Nexus container
docker run -d --name nexus-oss -p 8081:8081 --restart always -v /opt/sonatype-nexus/data:/nexus-data sonatype/nexus3

# View startup logs to confirm deployment
docker logs -f nexus-oss

Wait until the log outputs Started Sonatype Nexus OSS to confirm the service is fully running.

2. Access Nexus Web Console

Open a browser and navigate to http://your-server-ip:8081 to access the management interface. The default admin account password is stored in the persistent storage directory:

cat /opt/sonatype-nexus/data/admin.password

3. Basic Nexus Repository Overview

Default built-in repositories:

• maven-central: Proxy for the official Maven Central repository, pulling artifacts from https://repo1.maven.org/maven2/ by default
• maven-releases: Hosted repository for stable release artifacts, set Deployment Policy to Allow redeploy on first setup
• maven-snapshots: Hosted repository for snapshot (development) artifacts
• maven-public: Repository group that combines the above three repositories for unified external access, used in local Maven settings.xml or project pom.xml

Nexus repository type definitions:

• hosted: Local repository for storing your organization's internal artifacts or third-party jars
• proxy: Caching proxy for remote public repositories, reducing repeated downloads from external sources
• group: Aggregates multiple hosted and proxy repositories into a single access endpoint, simplifying client configuration

4. Create Blob Stores

Before creating custom repositories, you can set up Blob Stores to manage artifact storage locations uniformly. If you do not create a custom Blob Store, the default default storage will be used. Custom Blob Stores will be stored under /opt/sonatype-nexus/blobs/ by default.

5. Create Proxy Repository

Select the maven2 (proxy) repository type when creating a new proxy repo. Configure the remote repository URL, with other options left as default for now (you can adjust them later). Common public proxy repository URLs include:

• JBoss Central: https://repository.jboss.org/nexus/content/groups/public/
• Alibaba Maven Mirror: https://maven.aliyun.com/repository/public/
• Apache Maven Central: https://repo.maven.apache.org/maven2/

6. Create Hosted Repository

Hosted repositories support three deployment modes:

• Releases: For stable, officially released artifacts
• Snapshot: For ongoing development build artifacts
• Mixed: Supports both release and snapshot artifacts

Deployment policy options:

• Allow redeploy: Permits overwriting artifacts with the same version number, using timestamps to distinguish revisions
• Disable redeploy: Blocks overwriting existing artifacts with the same version
• Read-Only: Disables all artifact uploads

The default maven-releases uses Disable redeploy, while maven-snapshots uses Allow redeploy.

7. Create Repository Group

A repository group combines multiple hosted and proxy repositories into a single access URL, so clients only need to configure one group endpoint instead of multiple individual repositories. Add your previously created proxy and hosted repositories to the group for unified access.

8. Configure Mavan for Nexus Usage

First install and configure Maven:

# Download Maven 3.9.9 distribution
wget https://mirrors.tuna.tsinghua.edu.cn/apache/maven/maven-3/3.9.9/binaries/apache-maven-3.9.9-bin.tar.gz --no-check-certificate

# Extract archive to /opt
tar -zxvf apache-maven-3.9.9-bin.tar.gz -C /opt/

# Add Maven to system PATH
echo "export MAVEN_HOME=/opt/apache-maven-3.9.9" >> /etc/profile
echo "export PATH=$MAVEN_HOME/bin:$PATH" >> /etc/profile
source /etc/profile

# Verify Maven installation
mvn -v

Maven uses two configuration files: settings.xml (global system-wide settings) and pom.xml (project-specific settings). Project-level configurations take priority over global settings.

Update your settings.xml to use the Nexus repository group:

<!-- Server authentication for Nexus, ID matches the repository group name -->
<servers>
    <server>
        <id>my-nexus-group</id>
        <username>admin</username>
        <password>your-admin-password</password>
    </server>
</servers>

<!-- Mirror all central repository requests to the Nexus group -->
<mirrors>
    <mirror>
        <id>my-nexus-group</id>
        <name>Private Maven Mirror</name>
        <url>http://10.0.0.10:8081/repository/my-nexus-group/</url>
        <mirrorOf>central</mirrorOf>
    </mirror>
</mirrors>

Run a project build with the -U flag to force update snapshot dependencies:

mvn clean compile -U

9. Upload Third-Party Jars to Nexus

Web UI Upload

Upload local third-party jars that are not available in public repositories to your hosted repository. After upload, the artifacts will be available in both the target hosted repository and the aggregated group repository.

Command Line Upload

First add a server entry for your hosted repository in settings.xml:

<server>
    <id>my-hosted-repo</id>
    <username>admin</username>
    <password>your-admin-password</password>
</server>

Use the following Maven command to upload a local jar file:

mvn deploy:deploy-file -DgroupId=com.company.internal -DartifactId=internal-auth-lib -Dversion=1.0.0 -Dpackaging=jar -Dfile=/path/to/local/auth-lib.jar -Durl=http://10.0.0.10:8081/repository/my-hosted-repo/ -DrepositoryId=my-hosted-repo

Command breakdown:

• -DgroupId: Custom group ID for the artifact
• -DartifactId: Custom artifact ID
• -Dversion: Artifact version number
• -Dpackaging: Package type (jar, pom, etc.)
• -Dfile: Local path to the artifact file
• -Durl: URL of the target hosted repository
• -DrepositoryId: Must match the server ID configured in settings.xml

Example for snapshot artifacts:

mvn deploy:deploy-file -Dmaven.test.skip=true -Dfile=./internal-common-1.2.0-SNAPSHOT.jar -DgroupId=com.company.internal -DartifactId=internal-common -Dversion=1.2.0-SNAPSHOT -Dpackaging=jar -DrepositoryId=my-snapshots-repo -Durl=http://10.0.0.10:8081/repository/my-snapshots-repo/

10. Deploy Project Artifacts to Nexus

Release vs Snapshot Versions

• SNAPSHOT: Unstable development versions, automatically appends a timestamp to the version number when uploaded, and Maven will fetch the latest snapshot version on each build if configured
• RELEASE: Stable production versions, only one artifact per exact version number is allowed

Configure separate hosted repositories for releases and snapshots, then add both to your repository group. Ensure each hosted repository uses the correct deployment policy (set Allow redeploy for snapshot repos).

Update your project's pom.xml to specify deployment targets:

<!-- Configure remote repositories for dependency resolution -->
<repositories>
    <repository>
        <id>my-nexus-group</id>
        <name>Nexus Private Repository</name>
        <url>http://10.0.0.10:8081/repository/my-nexus-group/</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
        <releases>
            <enabled>true</enabled>
        </releases>
    </repository>
</repositories>
<pluginRepositories>
    <pluginRepository>
        <id>my-nexus-group</id>
        <name>Nexus Plugin Repository</name>
        <url>http://10.0.0.10:8081/repository/my-nexus-group/</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
        <releases>
            <enabled>true</enabled>
        </releases>
    </pluginRepository>
</pluginRepositories>

<!-- Configure deployment targets for built artifacts -->
<distributionManagement>
    <repository>
        <id>my-releases-repo</id>
        <name>Nexus Release Repository</name>
        <url>http://10.0.0.10:8081/repository/my-releases-repo/</url>
    </repository>
    <snapshotRepository>
        <id>my-snapshots-repo</id>
        <name>Nexus Snapshot Repository</name>
        <url>http://10.0.0.10:8081/repository/my-snapshots-repo/</url>
    </snapshotRepository>
</distributionManagement>

Add matching server entries for the release and snapshot repositories in settings.xml:

<servers>
    <server>
        <id>my-releases-repo</id>
        <username>admin</username>
        <password>your-admin-password</password>
    </server>
    <server>
        <id>my-snapshots-repo</id>
        <username>admin</username>
        <password>your-admin-password</password>
    </server>
</servers>

Build and deploy your project with:

mvn clean deploy -Dmaven.test.skip=true

11. Troubleshooting

Common Network Error

If you see the following error in Nexus logs:

UNKNOWN com.sonatype.nexus.plugins.outreach.internal.outreach.SonatypeOutreach - Could not download page bundle
java.net.SocketException: Network is unreachable (connect failed)

Fix this by disabling the Outreach service:

1. Log in to the Nexus admin console at http://10.0.0.10:8081
2. Navigate to Settings > Capabilities
3. Select Outreach: Management from the list of capabilities
4. Click the Disable button to turn off the service

Alternative, you can override the Outreach content URL in the Settings > Outreach tab using one of the allowed URLs:

• https://links.sonatype.com
• https://download.sonatype.com
• https://sonatype-download.global.ssl.fastly.net