Installing and Using Nexus Repository for Artifact Storage
In software development, "artifact" is a component of a developed software product. Artifacts include executable and binary files, software packages, and more.
As the product's architecture and functionality increase, the number of artifacts grows exponentially, and you need a reliable storage solution that can manage large volumes of artifacts efficiently.
One such solution is Nexus Repository by Sonatype.
Nexus supports over 15 artifact formats, including APT, Docker, Go, Helm, Maven, npm, PyPi, and more.
There are two versions of Nexus Repository:
Free version – Includes essential repository management features.
Commercial version – Offers customer support and a broader range of supported artifact types.
In this guide, we will install the free version of Nexus Repository.
Prerequisites
You can install Nexus Repository on a Linux, Windows, or MacOS machine.
In this guide, we will use a Hostman cloud server running Ubuntu.
The server must meet the following minimum requirements:
4-core CPU. 8-core or higher is recommended.
8 GB RAM
50 GB of free disk space (excluding OS and other installed software). If there is insufficient space, Nexus will not start.
The official Sonatype website provides recommended system requirements based on the number of repositories and stored artifacts.
Installing Nexus Repository
Step 1: Install Java
First, update the package list:
sudo apt update
Then, install Java 8 using OpenJDK:
sudo apt -y install openjdk-8-jre-headless
After installation, verify Java's version:
java -version
If you have multiple Java versions installed, switch to Java 8:
sudo update-alternatives --config java
Select the correct version using the TAB key and confirm with Enter.
Step 2: Download and Extract Nexus
We will install Nexus in the /opt directory.
Download the latest Nexus archive:
sudo wget https://download.sonatype.com/nexus/3/latest-unix.tar.gz
Extract the archive to /opt:
sudo tar -zxvf latest-unix.tar.gz -C /opt
Rename the extracted directory (for easier management):
sudo mv /opt/nexus-3.61.0-02 /opt/nexus
Make sure to specify the correct version number in your case.
Step 3: Create a Dedicated User for Nexus
Create a new user named nexus:
sudo adduser nexus
Disable direct login for this user:
sudo usermod nexus -s
Set the correct ownership for Nexus directories:
sudo chown -R nexus:nexus /opt/nexus /opt/sonatype-work
Step 4: Configure Nexus
Edit the Nexus configuration file:
sudo nano /opt/nexus/bin/nexus.rc
Uncomment (remove #) and set the user as nexus:
run_as_user="nexus"
Save and exit the file.
Step 5: Create a Systemd Service for Nexus
Create a new service file:
sudo nano /etc/systemd/system/nexus.service
Add the following content:
[Unit]
Description=Nexus Repository Manager
After=network.target
[Service]
Type=forking
LimitNOFILE=65536
ExecStart=/opt/nexus/bin/nexus start
ExecStop=/opt/nexus/bin/nexus stop
User=nexus
Restart=on-abort
[Install]
WantedBy=multi-user.target
Save and exit the file.
Step 6: Start and Enable Nexus
Start Nexus:
sudo systemctl start nexus
Check Nexus status:
systemctl status nexus
If the status is active, Nexus is running successfully.
Enable Nexus to start on boot:
sudo systemctl enable nexus
Step 7: Verify Nexus Startup
Nexus takes 2-3 minutes to fully start. To check the logs:
tail -f /opt/sonatype-work/nexus3/log/nexus.log
Once you see:
Started Sonatype Nexus OSS
Nexus is ready.
By default, the Nexus web interface is accessible on port 8081:
http://your-server-ip:8081
Initial Setup of Nexus Repository
Step 1: Log into Nexus
Open the Nexus web interface.
Click the Sign in button (top-right corner).
Retrieve the default admin password by running:
cat /opt/sonatype-work/nexus3/admin.password
Use this password to log in as admin.
Step 2: Initial Configuration
Set a new password for the admin user.
Enable or disable anonymous access:
Enabled: Any user with the repository URL can browse/download artifacts without authentication.
Disabled: Authentication (login/password) is required.
Nexus is now ready to use.
Creating a Docker Repository in Nexus
Step 1: Create a Docker Repository
Log in as admin.
Go to Server Administration and Configuration (gear icon).
In the left menu, select Repositories.
Click Create repository.
Choose docker (hosted).
Step 2: Configure the Repository
Nexus supports three types of repositories:
Hosted: Stores artifacts directly in Nexus.
Proxy: Fetches artifacts from remote repositories (e.g., APT).
Group: Combines multiple repositories into one unified endpoint.
For a Docker repository:
Set a repository name, e.g., docker-images.
Enable HTTP access (check the box).
Assign a port number (e.g., 8083).
Save the settings.
Step 3: Configure Docker to Work with Nexus
By default, Docker does not allow HTTP connections. To enable HTTP access:
Edit or create the Docker daemon configuration file:
sudo nano /etc/docker/daemon.json
Add the following configuration:
{
"insecure-registries": ["166.1.227.189:8083"]
}
(Replace 166.1.227.189:8083 with your Nexus server IP and port.)
Save and exit the file.
Restart the Docker service:
sudo systemctl restart docker
Warning: Restarting Docker affects running containers. Containers without the --restart=always flag may not restart automatically.
Step 4: Push a Docker Image to Nexus
Log in to Nexus via Docker:
docker login 166.1.227.189:8083
You can use the admin username and the password you set earlier.
Tag an image (e.g., alpine):
docker tag alpine:latest 166.1.227.189:8083/alpine-test
Verify the new tag:
docker images
Push the image to Nexus:
docker push 166.1.227.189:8083/alpine-test
Confirm the upload:
Open the Nexus web interface.
Go to the docker-images repository.
The alpine-test image should be listed.
Your Nexus repository is now set up for Docker image storage!
HTTPS Configuration
The correct approach when working with Docker repositories is to use the HTTPS protocol. To configure HTTPS in Nexus, follow these steps:
Navigate to the /opt/nexus/etc/ssl directory:
cd /opt/nexus/etc/ssl
Use keytool to generate a self-signed certificate:
sudo keytool -genkeypair -keystore keystore.jks -storepass test12345 -keypass test12345 -alias jetty -keyalg RSA -keysize 2048 -validity 1000 -dname "CN=*.${NEXUS_DOMAIN}, OU=test, O=test1, L=Unspecified, ST=Unspecified, C=RU" -ext "SAN=DNS:nexus-repo.com,IP:166.1.227.189" -ext "BC=ca:true"
Replace the following values with your own:
-keystore keystore.jks — Name of the file where the key will be stored, using the .jks format.
-storepass test12345 — Password for accessing the key store.
-keypass test12345 — Password for accessing the private key.
-ext "SAN=DNS:nexus-repo.com,IP:166.1.227.189" — Specifies your Nexus server's domain name and IP address.
If a local domain is used, it must be added to the /etc/hosts file (for Linux) or C:\Windows\System32\drivers\etc\hosts in Windows.
Next, extract the server certificate from the generated keystore.jks file using the following command:
sudo keytool -export -alias jetty -keystore keystore.jks -rfc -file nexus.cert
The output will be a certificate file named nexus.cert.
Now, edit the Nexus configuration file nexus-default.properties located in /opt/nexus/etc:
sudo nano /opt/nexus/etc/nexus-default.properties
Find the section with the comment # Jetty section, and add the following parameter:
application-port-ssl=8443
This specifies the port where HTTPS will be available.
In the same section, add this line:
nexus-args=${jetty.etc}/jetty.xml,${jetty.etc}/jetty-http.xml,${jetty.etc}/jetty-https.xml,${jetty.etc}/jetty-requestlog.xml
Next, edit the jetty-https.xml file located in /opt/nexus/etc/jetty:
sudo nano /opt/nexus/etc/jetty/jetty-https.xml
Locate the block named sslContextFactory.
In the fields KeyStorePassword, KeyManagerPassword, TrustStorePassword, enter the password used during certificate generation. In this example, the password is test12345.
In the parameters KeyStorePath and TrustStorePath, specify the name of the generated certificate.
After making these changes, restart the Nexus service:
sudo systemctl restart nexus
Installing the Certificate on Linux
In Linux, we must install the certificate at the OS level. Otherwise, when trying to authenticate to the repository using the docker login command, the following error may occur:
x509: certificate signed by unknown authority
To install the certificate on Ubuntu/Debian, follow these steps:
Install the ca-certificates package:
sudo apt -y install ca-certificates
The certificate must be in .crt format, as other formats are not supported. Since the certificate was generated as .cert, rename it to .crt:
sudo mv nexus.cert nexus.crt
Copy the certificate to /usr/local/share/ca-certificates:
sudo cp nexus.crt /usr/local/share/ca-certificates
Install the certificate using the following command:
sudo update-ca-certificates
Configuring HTTPS in the Nexus Repository
To configure HTTPS in the repository:
Open the Nexus web interface and log in as an administrator.
Navigate to the Server Administration and Configuration section (gear icon).
In the left menu, select Repositories, find the required repository, check the box next to HTTPS, and specify a port that is not already in use on the server, such as 8344.
4 Save the changes.
On the server, run the docker login command, specifying the repository address and HTTPS port:
docker login nexus-repo.com:8344
You can log in using the admin account.
Pushing an Image to the Repository
To test pushing an image, let's use nginx:
Assign a tag to the image. The format for Docker image tags is as follows:
image:tag registry_address:repository_port/image_name
Example:
docker tag nginx:latest nexus-repo.com:8344/nginx-test
Verify that the new image exists:
docker images
Push the image to the repository:
docker push nexus-repo.com:8344/nginx-test
Open the Nexus web interface, navigate to the repository, and confirm that the image was successfully uploaded.
Conclusion
Nexus Repository is an excellent solution for storing and managing artifacts. Supporting a wide range of artifact formats, it is suitable for both small development teams and larger enterprises.
11 March 2025 · 8 min to read