Documentation Nexus Repository Manager 3.0

Our documentation site has moved. For the most current version, please see http://help.sonatype.com

Chapter 2. Installation and Running

2.1. Introduction

Nexus Repository Manager is a Java application that requires a Java Runtime Environment. When you run Nexus Repository Manager, you are running a server application with a web-based user interface. The application itself runs with the Eclipse Jetty servlet container and Apache Karaf OSGi-container.

Installation is a simple process. This chapter provides further details to get started and keep the repository manager running successfully in production deployments.

2.2. Downloading

Nexus Repository Manager can be downloaded from Sonatype. Distributions are available for the 64-bit versions for Apple OSX, Microsoft Windows and Unix/Linux. They contain all necessary resources to install and run the repository manager. You can download the plain archive file for your operating system of a specific release version.

The plain archive files are Gzip TAR (TGZ) or ZIP files and are suitable for installation without a graphical user interface purely using command line-based interaction. The file names include operating system qualifiers and are similar to similar to:

nexus-3.0.2-02-mac.tgz
nexus-3.0.2-02-unix.tar.gz
nexus-3.0.2-02-win64.zip

Next steps, after a successful download, depend on the operating system you are using and are documented in Section 2.4, “Installing and Running with the Distribution Archive”.

2.3. Java Runtime Environment

Nexus Repository Manager requires a Java 8 Runtime Environment (JRE) from Oracle. The distributions for OSX and Windows include suitable runtime environments for the specific operating system. The distributions for Unix do not include the runtime environment.

If you prefer to use an external runtime or use a Unix operating system, it is recommended to use the latest version of Java 8 available from the Oracle website. You can choose to install the full JDK or the JRE only.

You can confirm the installed Java version with the java command:

$  java -version
java version "1.8.0_60"
Java(TM) SE Runtime Environment (build 1.8.0_60-b27)
Java HotSpot(TM) 64-Bit Server VM (build 25.60-b23, mixed mode)

When multiple JDK or JRE versions are installed, you need to ensure the correct version is configured by running the above command as the operating system user, that is used to run the repository manager. This allows you to have a dedicated runtime environment for the repository manager installed that is not on the path and not used by other installed applications. It allows you to separate upgrades of the Java runtime used by the repository manager from upgrades of the runtime used by other applications.

[Tip]

OpenJDK or other Java distributions or older Java versions are not supported.

Potentially you need to update the configuration to specify a specific JDK or JRE installation path:

To set the path for a specific Java location open the bin/nexus script and locate the line INSTALL4J_JAVA_HOME_OVERRIDE. Remove the hash and specify the location of your JDK/JRE:

INSTALL4J_JAVA_HOME_OVERRIDE=/usr/lib/jvm/java-8-oracle

The startup script verifies the runtime environment by checking for the existance of the nested bin/java command as well as major and minor version of the runtime to be the required 1.8. If the configured runtime is not suitable, it will proceed with a best effort to locate a suitable runtime configured on the path or via the JAVA_HOME environment variable. If successful, it will start up the repository manager with this JVM.

2.4. Installing and Running with the Distribution Archive

The distribution archives combine the application and all required resources in an archive file. Installing and running Nexus Repository Manager is straightforward. Simply unpack the archive in a directory, to which you have full access.

If you are installing the repository manager on a local workstation to give it a test run, you can install it in your home directory or wherever you like. Nexus Repository Manager doesn’t have any hard-coded directories and will run from any directory.

You can extract the archive ZIP for Windows with any archiving tool like 7zip or on the command line with e.g.

$ 7za.exe e nexus-3.0.2-02-win64.zip

On Windows you should install the repository manager outside Program Files to avoid problems with Windows file registry virtualization. If you plan to run the repository manager as a specific user you can install it into the AppData\Local directory of that users home directory. Otherwise simply use e.g., C:\nexus or something similar, ensuring that the user running the application has full access.

On OSX or Linux the downloaded GZip’d TAR archive can be extracted with:

$ tar xvzf nexus-3.0.2-02-mac.tgz
$ tar xvzf nexus-3.0.2-02-unix.tar.gz

You install the repository manager in a directory other than your users home directory. On a Unix machine common practice is to use /opt.

The extraction process creates a directory with a number of directories inside. This directory is referred to as the installation directory. In contains the application and related resources as well as the data directory for component and repository storage. Further details about these folders can be found in Section 2.10, “Directories”

The bin folder contains the generic startup scripts for Unix-like platforms called nexus. The Windows platform equivalent is called nexus.exe. To start the repository manager from the bin folder on a Unix-like platform like Linux use

./nexus run

The equivalent invocation on Windows requires a / in front of the run and any other commands.

nexus.exe /run

Starting the repository manager with the run command will leave it running in the current shell and display the log output.

The repository manager is fully started once you see a message similar to the following in the log:

Started Nexus Repository Manager 3.0.2-02

In order to shut down the repository manager running via the run command, you have to press CTRL-C.

The nexus script can be used to manage the repository manager as a background application on OSX and Unix with the start, stop, restart, force-reload and status commands. The Windows nexus.exe command supports similar commands with a prefix of / e.g., /run.

Once the repository manager is started you can access the user interface as details in Section 2.9, “Accessing the User Interface”.

2.5. Installing with Docker

Available in Nexus Repository OSS and Nexus Repository Pro

Docker automates the deployment of applications inside virtualized Linux containers. You can create a container that supports the installation of Nexus Repository Manager Pro and Nexus Repository Manager OSS.

To install the repository manager with a Docker image, follow the steps at Docker Hub.

2.6. Upgrading

Since the repository manager separates its configuration and data storage from the application, it is easy to upgrade an existing installation.

To keep the upgrade simple schedule downtime to preserve important directories during the process. Follow the steps in the support knowledge base article.

[Note]

Upgrading to Nexus Repository Manager OSS 3.0.0 can only be performed by users who run the milestone 7 release of the repository manager. Be sure to manually back up the milestone 7 data directory to another location. It is a crucial step to properly upgrade the application.

2.7. Configuring as a Service

Available in Nexus Repository OSS and Nexus Repository Pro

When installing Nexus Repository Manager for production usage it has to be configured it to run as a service, so it restarts after the server reboots. It is good practice to run that service or daemon as a specific user that has only the required access rights.

Installation from the distribution archive does not include the configuration of a service. The following sections provide instructions for configuring the service manually. Independent of the operating system the steps are

  • Create operating sytem user with limited access rights dedicated to run the repository manager as a service
  • Ensure suitable Java runtime environment is installed - see Section 2.3, “Java Runtime Environment”
  • Configure the service and ensure it starts as part of the operating sytem boot process
[Warning]

We recommend to avoid running the repository manager as the root user or a similar privileged user, as this practice poses serious, unnecessary security risks to the host operating system. Instead we suggest to follow system administration best practice and use a service specific user with the minimum required access rights only.

2.7.1. Setting up as a Service on Linux

You can configure the repository manager to run as a service with init.d or systemd. Both are startup frameworks used in Linux-based systems such as Ubuntu and CentOS. They are, essentially, initscripts that load commands to manage the repository manager daemon.

Before running the service configure an absolute path for your repository manager files. Then create a nexus user with sufficient access rights to run the service.

Change NEXUS_HOME to the absolute folder location in your .bashrc file, then save.

NEXUS_HOME="/opt/nexus"

In bin/nexus.rc assign the user between the quotes in the line below.

run_as_user="nexus"

If you use init.d instead of systemd, symlink $NEXUS_HOME/bin/nexus to /etc/init.d/nexus:

sudo ln -s $NEXUS_HOME/bin/nexus /etc/init.d/nexus

Running the Service

chkconfig.

This example uses chkconfig, a tool that targets the initscripts in init.d to run the nexus service. Run these commands to activate the service:

cd /etc/init.d
sudo chkconfig --add nexus
sudo chkconfig --levels 345 nexus on
sudo service nexus start

The second command adds nexus as a service to be started and stopped with the command. chkconfig manages the symbolic links in /etc/rc[0-6].d which control the services to be started and stopped when the operating system restarts or transitions between run-levels. The third command adds nexus to run-levels 3, 4, and 5. Then the service command starts the repository manager.

update-rc.d.

This example uses update-rc.d, a tool similar to the chkconfig.

cd /etc/init.d
sudo update-rc.d nexus defaults
sudo service nexus start

In the second line you will run a default priority to add the nexus service before starting it.

systemd.

This example is a script that uses systemd to run the repository manager service. Create a file called nexus.service. Add the following contents, then save the file in the /etc/systemd/system/ directory.

[Unit]
Description=nexus service
After=network.target

[Service]
Type=forking
ExecStart=/opt/nexus/bin/nexus start
ExecStop=/opt/nexus/bin/nexus stop
User=nexus
Restart=on-abort

[Install]
WantedBy=multi-user.target

Activate the service with the following commands:

sudo systemctl daemon-reload
sudo systemctl enable nexus.service
sudo systemctl start nexus.service

After starting the service for any Linux-based operating systems, verify that the service started successfully.

tail -f /opt/nexus/data/log/nexus.log

The tail command verifies that the service has been started successfully. If successful, you should see a message notifying you that it is listening for HTTP.

2.7.2. Running as a Service on Windows

The startup script that runs Nexus Repository Manager Pro and Nexus Repository Manager OSS on Windows platforms is bin/nexus.exe. The script includes standard commands for starting and stopping the service. It also contains commands install and uninstall to create and delete the configuration for the service.

You can create the service configuration with:

nexus.exe /install

The created service is available named nexus in common console application to manage services such as Windows Services. You can start, stop and restart the service there as well as configure it to start as part of a operating system startup.

2.7.3. Running as a Service on Mac OS X

The standard way to run a service on Mac OS X is to use launchd, a program that starts, stops and manages daemons and scripts in Apple OS X environments. To run the service you need to create an XML document called with the file extension .plist to define its properties. An example plist file for the repository manager installed in /opt is shown A sample com.sonatype.nexus.plist file.

A sample com.sonatype.nexus.plist file. 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
    "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.sonatype.nexus</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/nexus/bin/nexus</string>
        <string>start</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

After saving the file as com.sonatype.nexus.plist in /Library/LaunchDaemons/ you have to change the ownership and access rights.

sudo chown root:wheel /Library/LaunchDaemons/com.sonatype.nexus.plist
sudo chmod 644 /Library/LaunchDaemons/com.sonatype.nexus.plist
[Tip]

Consider setting up a different user to run the repository manager and adapt permissions and the RUN_AS_USER setting in the nexus startup script.

With this setup the repository managers, starts as a service at boot time. To manually start it after the configuration you can use

sudo launchctl load /Library/LaunchDaemons/com.sonatype.nexus.plist

2.8. Running Behind a Reverse Proxy

Available in Nexus Repository OSS and Nexus Repository Pro

Nexus Repository Manager is a sophisticated server application with a web-application user interface, answering HTTP requests using the high-performance servlet container Eclipse Jetty.

Organizations are sometimes required to run applications like Nexus Repository Manager behind a reverse proxy. Reasons may include:

  • security and auditing concerns
  • network administrator familiarity
  • organizational policy
  • disparate application consolidation
  • virtual hosting
  • exposing applications on restricted ports
  • SSL termination

This section provides some general guidance on how to configure common reverse proxy servers to work with Nexus Repository Manager. Always consult your reverse proxy administrator to ensure you configuration is secure.

The default webapp context path for the repository manager user interface is 8081. In the instance where the repository manager needs to be proxied at a different base path you must change the default path by editing a property value. In Section 4.2.4, “Base URL Creation” follow the steps to change or update the base URL if you want an alternate server name.

In the following examples, review the sections on changing the HTTP port and context path to properly reverse-proxy the repository manager.

2.8.1. Example: Reverse Proxy on Restricted Ports

Scenario: You need to expose the repository manager on restricted port 80. The repository manager should not be run with the root user. Instead run your reverse proxy on the restricted port 80 and the repository manager on the default port 8081. End users will access the repository manager using the virtual host URL http://www.example.com/nexus instead of http://localhost:8081/nexus.

Ensure your external hostname (www.example.com) routes to your reverse proxy server. In this example use the default content path (/)

Apache httpd.

ProxyRequests Off
ProxyPreserveHost On

<VirtualHost: *:80>
  ServerName www.example.com
  ServerAdmin admin@example.com
  ProxyPass /nexus http://localhost:8081/
  ProxyPassReverse /nexus http://localhost:8081/
  ErrorLog logs/www.example.com/nexus/error.log
  CustomLog logs/www.example.com/nexus/access.log common
</VirtualHost>

nginx.

http {

    proxy_send_timeout 120;
        proxy_read_timeout 300;
        proxy_buffering    off;
        keepalive_timeout  5 5;
        tcp_nodelay        on;

        server {
                listen   *:80;
                server_name  www.example.com;

                # allow large uploads of files - refer to nginx documentation
                client_max_body_size 1G;

                # optimize downloading files larger than 1G - refer to nginx doc before adjusting
                #proxy_max_temp_file_size 2G;

                location /nexus {
                        proxy_pass http://localhost:8081/nexus;
                        proxy_set_header Host $host;
                        proxy_set_header X-Real-IP $remote_addr;
                        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                }
        }
}

2.8.2. Example: Reverse Proxy Virtual Host at Custom Context Path

Scenario: You need to expose the repository manager using a custom host name repo.example.com on a restricted port at a base path of /nexus.

Ensure your external hostname (repo.example.com) routes to your reverse proxy server and edit the webapp path a slash at end (/).

Apache httpd.

ProxyRequests Off
ProxyPreserveHost On

<VirtualHost *:80>
  ServerName repo.example.com
  ServerAdmin admin@example.com
  ProxyPass /nexus http://localhost:8081/nexus
  ProxyPassReverse /nexus http://localhost:8081/nexus
  ErrorLog logs/repo.example.com/nexus/error.og
  CustomLog logs/repo.example.com/nexus/access.log common
</VirtualHost>

nginx.

http {

    proxy_send_timeout 120;
        proxy_read_timeout 300;
        proxy_buffering    off;
        keepalive_timeout  5 5;
        tcp_nodelay        on;

        server {
                listen   *:80;
                server_name  repo.example.com;

                # allow large uploads of files - refer to nginx documentation
                client_max_body_size 1G;

                # optimize downloading files larger than 1G - refer to nginx doc before adjusting
                # proxy_max_temp_file_size 2G;

                location / {
                        proxy_pass http://localhost:8081/nexus;
                        proxy_set_header Host $host;
                        proxy_set_header X-Real-IP $remote_addr;
                        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                }
        }
)

2.8.3. Example: Reverse Proxy SSL Termination at Base Path

Scenario: Your organization has standardized a reverse proxy to handle SSL certificates and termination. The reverse proxy virtual host will accept HTTPS requests on the standard port 443 and serve content from the repository manager running on the default non-restricted HTTP port 8081 transparently to end users.

Ensure your external host name (repo.example.com) routes to your reverse proxy server and edit the webapp path to be slash (/).

To test your configuration, review the steps to generate a self-signed SSL certificate for reverse proxy servers.

Apache httpd. Ensure Apache httpd is loading mod_ssl.

Listen 443

ProxyRequests Off
ProxyPreserveHost On

<VirtualHost *:443>
  SSLEngine on

  SSLCertificateFile "example.pem"
  SSLCertificateKeyFile "example.key"

  ServerName repo.example.com
  ServerAdmin admin@example.com
  ProxyPass / http://localhost:8081/
  ProxyPassReverse / http://localhost:8081/
  RequestHeader set X-Forwarded-Proto "https"

  ErrorLog logs/repo.example.com/nexus/error.log
  CustomLog logs/repo.example.com/nexus/access.log common
</VirtualHost>

nginx. Make sure nginx is compiled using the --with-http_ssl_module option.

http {

        proxy_send_timeout 120;
        proxy_read_timeout 300;
        proxy_buffering    off;
        keepalive_timeout  5 5;
        tcp_nodelay        on;

        server {
                listen   *:443;
                server_name  repo.example.com;

                # allow large uploads of files - refer to nginx documentation
                client_max_body_size 1G;

                # optimize downloading files larger than 1G - refer to nginx doc before adjusting
                #proxy_max_temp_file_size 2G;

                ssl on;
                ssl_certificate      example.pem;
                ssl_certificate_key  example.key;

                location / {
                        proxy_pass http://localhost:8081/;
                        proxy_set_header Host $host;
                        proxy_set_header X-Real-IP $remote_addr;
                        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                        proxy_set_header X-Forwarded-Proto "https";
                }
        }
}
[Note]

Consult your reverse proxy product documentation for details: Apache httpd (mod_proxy, mod_ssl), nginx (ngx_http_proxy_module, ssl compatibility)

2.9. Accessing the User Interface

Once the repository manager is started, the application is listening on the configured IP address range and port. By default any IP address and port 8081 are used. To access the web application user interface, fire up a web browser and type in the URL http://serveripaddress:port e.g. http://localhost:8081/. If the repository manager started up successfully and network settings allow you to connect to the server, the user interface looks similar to Figure 2.1, “Initial User Interface”.

figs/web/ui-overview-anonymous.png

Figure 2.1. Initial User Interface


While the documentation uses localhost throughout, you may need to use the IP Loopback Address of 127.0.0.1, the IP address or the DNS hostname assigned to the machine running the repository manager.

The user interface shows the features available to an anonymous user. The repository manager installation includes an administrative user with full access. Its username is admin and the password is admin123. You can sign in with the button on the top right corner of the user interface.

Next steps after successfully accessing the user interface are detailed in Chapter 3, Using the User Interface, Chapter 4, Configuration and following chapters about various repository formats and tools such as:

More information about security related topics can be found in Chapter 5, Security.

2.10. Directories

There are two main directories created and used by the repository manager.

Installation directory
This directory is contains the Nexus Repository Manager application and all the required additional components such as Java libraries and configuration files. The name of the directory by default uses nexus- and is appended with the version name. In this documentation it is referred to as $install-dir in any code segments.
Data Directory
This directory contains all the repositories, components and other data that is being stored and managed by the repository manager. It is located within the installation directory by default for archive-based installs and called data. In this documentation it is referred to as $data-dir in any code segments.

2.10.1. Installation Directory

The installation directory includes a number of nested directories:

$ ls -1 nexus-3.0.2-02
LICENSE.txt
NOTICE.txt
bin
data
deploy
etc
lib
public
system
LICENSE.txt and NOTICE.txt
contain legal details about the license and copyright notices.
bin
contains the nexus startup script itself as well as startup-related configuration files.
data
This data directory contains all of the repository and configuration data. By default, from a distribution archive install, this directory is nested within the installation directory. More details can be found Section 2.10.2, “Data Directory”.
etc
contains configuration files.
lib
contains binary libraries related to Apache Karaf.
public
contains public resources of the application.
system
contains all components and plugins that constitute the application.

2.10.2. Data Directory

The data directory contains subdirectories such as blobs, db, elasticsearch and others. These contain all the components, repository, configuration and other data presented by the repository manager.

2.11. Configuring the Runtime Environment

Configuring the specifics of the repository manager runtime involves configuration for all components in various configuration files and startup scripts. This section details these and provides recipes for specific tasks.

The startup of the JVM running the repository manager is managed via files in the $install-dir/bin directory within the installation. The application startup is performed with the JVM configuration in the file $install-dir/bin/nexus.vmoptions :

-Xms1200M
-Xmx1200M
-XX:+UnlockDiagnosticVMOptions
-XX:+UnsyncloadClass
-Djava.net.preferIPv4Stack=true
-Dkaraf.home=.
-Dkaraf.base=.
-Dkaraf.etc=etc
-Djava.util.logging.config.file=etc/java.util.logging.properties
-Dkaraf.data=data
-Djava.io.tmpdir=data/tmp
-Dkaraf.startLocalConsole=false

The main location for configuration files is the etc directory. The directory includes:

config.properties
The main configuration for the Apache Karaf runtime. This file should not be modified.
custom.properties
Customizable configuration used by Apache Karaf. This file can be used to pass additional parameters to the Apache Karaf container.
jetty-*.xml
A number of configuration files for Eclipse Jetty
org.apache.* and org.ops4j.*
Various Karaf and OSGi related configuration files.
org.sonatype.nexus.cfg
Main configuration file for the application allowing you to configure aspects such as ports used for HTTP and HTTPS access, location of the data and configuration storage as well as the context path and host.
system.properties
Configuration parameters used for the JVM and application start up.

2.11.1. Updating Memory Allocation and other JVM Paramaters

The default and maximum heap sizes for the repository manager are a value of 1200M, suitable for most usage patterns. As a Java application running on the JVM the repository manager is using JVM configuration parameters for numerous settings as part of the startup parameters for the JVM. These values are defined in the configuration file $install-dir/bin/nexus.vmoptions. Increased memory configuration can be set with e.g. :

-Xms1500M
-Xmx2G

Other JVM parameters such as GC algorithm can be configured in the same location.

2.11.2. Changing the HTTP Port

The default value for the HTTP port used to access the repository manager user interface and resources is 8081. Therefore the user interface would be available at http://localhost:8081/. To change or update the port locate the line application-port=8081 in $install-dir/etc/org.sonatype.nexus.cfg, then edit the number. Here is an example where you would change the port to 9081:

application-port=9081

Therefore, the exposed URL will be http://localhost:9081/.

2.11.3. Changing the Context Path

To change or update the context path in the instance you want point to a specific webapp or component, locate the nexus-context-path=/ line in $install-dir/etc/org.sonatype.nexus.cfg. Here is an example where you expose the user interface to a components directory.

nexus-context-path=/components/

Therefore, if the port is set to 9081, the exposed URL will be http://localhost:9081/components/.

2.11.4. Configuring the Data Directory Location

Distribution archive installation of the repository manager configures the location of the data directory to be nested inside the application directory.

The configuration of this folder is located in $install-dir/bin/nexus.vmoptions. For example, if you want to use the absolute path /opt/repository/storage/, you have to change to:

-Dkaraf.data=/opt/repository/storage
-Djava.io.tmpdir=/opt/repository/storage/tmp
[Note]

Find out more about upgrading this version of Nexus Repository Manager to 3.1.0 in the dedicated support article.

2.12. Uninstalling

To uninstall the repository manager from an archive installation, remove the service configuration and delete the entire directory.