Documentation Nexus IQ Server 1.23

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

5.1. Installation

Before installation, please check the IQ Server requirements.

After a successful download of the IQ Server bundle archive, you should create an installation directory in the desired location and move the archive into the directory.

cd /opt
mkdir nexus-iq-server
mv ~/Downloads/nexus-iq-server.* nexus-iq-server/
cd nexus-iq-server

Moving into the directory and extracting the archive with either one of the commands:

unzip nexus-iq-server*.zip
tar xfvz nexus-iq-server*.tar.gz

should result in a directory with the following files:

README.txt
config.yml
demo.bat
demo.sh
eula.html
nexus-iq-server-1.23.0-01-bundle.tar.gz
nexus-iq-server-1.23.0-01.jar

5.1.1. Starting the IQ Server

Once the IQ Server is installed, it can be started with:

cd /opt/nexus-iq-server
java -jar nexus-iq-server-*.jar server config.yml

This command will start the server with the IQ Server application using the configuration from the config.yml file and logging any output straight to the console. After a complete start your console should display a message similar to:

... [main] org.eclipse.jetty.server.AbstractConnector - Started InstrumentedBlockingChannelConnector@0.0.0.0:8070
... [main] org.eclipse.jetty.server.AbstractConnector - Started SocketConnector@0.0.0.0:8071

The command to start the server can be modified by adding java configurations parameters such as -Xmx1024m -XX:MaxPermSize=128m to improve performance and adapt to the server hardware.

At this stage you can access the web application at port 8070 of your server via any web browser. Initial startup will display a screen for the Section 5.1.2, “License Installation”.

[Warning]

We recommend always using SSL to ensure confidentiality of report and credential data during transit. This can be done by setting up a proxy server. You can find more details in the HTTPS Configuration section.

5.1.2. License Installation

IQ Server requires a license to be installed. The required license file will be supplied to you by the Sonatype support team in the form of a .lic file.

Open a web browser and navigate to the IQ Server web application at port 8070 to install the license. Opening the URL, e.g. for a localhost deployment at http://localhost:8070, displays the Product License Configuration of the IQ Server shown in Figure 5.1, “Installing a Product License on IQ Server”.

figs/web/clm-server-install-license.png

Figure 5.1. Installing a Product License on IQ Server


Press the Install License button and select the .lic file in the file selector. As a next step you are required to accept the end user license agreement shown in Figure 5.2, “IQ Server End User License Agreement Window” by pressing the I Accept button.

figs/web/clm-server-eula.png

Figure 5.2. IQ Server End User License Agreement Window


After a success message you will be redirected to the Product License page, which will now display the expiry date of the license as visible in Figure 5.3, “Installed Product License on IQ Server”.

figs/web/clm-server-license-installed.png

Figure 5.3. Installed Product License on IQ Server


5.1.3. IQ Server Directories

When the IQ Server first starts, it creates a directory for the storage of all its data and configuration. This directory is configured in config.yml and defaults to ./sonatype-work/clm-server. This path is relative to the location from which the invoking java command is used.

Using the default startup command from the installation directory, causes /sonatype-work/clm-server to be created within it.

If you would like to separate the installation and data directories you can set the sonatypeWork to a different location.

Additionally a log directory is created within the installation directory and the currentLogFilename parameter in config.yml can be used to change the location. Further information on logging configuration can be found in Section 5.2.8, “Logging Configuration”.

5.1.4. Running the IQ Server as a Service

For production usage, we strongly recommend to set up the IQ Server as a service or daemon. This will ensure that any operating system reboots will include starting up the IQ Server.

A dedicated user for running a service is a well known best practice. This user should have reduced access rights as compared to the root user. Configuration of this user will depend on the operating system and security system used.

Once the user is configured, you need to ensure that full access rights to the IQ Server installation directory are granted. An example command to achieve this for a service user with the username iqserver is:

chown -Rv iqserver /opt/nexus-iq-server

If you have configured the sonatypeWork parameter in config.yml to point to a different directory, you have to adjust the access rights for it as well.

The principal command for starting the IQ Server can be used in a simple startup script as displayed in Startup Script. The javaopts variable should be adjusted to suit the hardware used.

Startup Script. 

#! /bin/sh
cd /opt/nexus-iq-server
javaopts="-Xmx1024m -XX:MaxPermSize=128m"
java  $javaopts -jar nexus-iq-server-*.jar server config.yml

A running server can be stopped with a simple shutdown script in Shutdown script.

Shutdown script. 

#!/bin/sh
     pid=`ps aux | grep nexus-iq-server | grep -v grep | awk '{print $2}'`
     kill $pid

Typically these approaches are combined to a service script similar to the script listed in Simplistic Service Script for Unix Systems. Saving this script as e.g. nexus-iq-server allows you to start the server with its log running to the current shell with

./nexus-iq-server console

Starting as a background process can be initiated with:

./nexus-iq-server start

and a running background server can be stopped with:

./nexus-iq-server stop

This example script can be improved to be more robust against repeat invocations, long running stops and potentially work better across different Unix flavors, but shows the principal functionality. A similar script can be used for Windows.

Simplistic Service Script for Unix Systems. 

#!/bin/sh

# The following comment lines are used by the init setup script like the
# chkconfig command for RedHat based distributions. Change as
# appropriate for your installation.

### BEGIN INIT INFO
# Provides:          nexus-iq-server
# Required-Start:    $local_fs $remote_fs $network $time $named
# Required-Stop:     $local_fs $remote_fs $network $time $named
# Default-Start:     3 5
# Default-Stop:      0 1 2 6
# Short-Description: nexus-iq-server service
# Description:       Start the nexus-iq-server service
### END INIT INFO

NEXUS_IQ_SERVER_HOME=/opt/tools/nexus-iq-server
VERSION=1.12.0
JAVA_OPTIONS="-Xmx1024m -XX:MaxPermSize=128m"
# The user ID which should be used to run the IQ Server
# # IMPORTANT - Make sure that the user has the required privileges to write into the IQ Server work directory.
RUN_AS_USER=iqserver

do_start()
{
    cd $NEXUS_IQ_SERVER_HOME
    su -m $RUN_AS_USER -c "java -jar $JAVA_OPTIONS nexus-iq-server-$VERSION.jar server  config.yml > /dev/null 2>&1 &"
    echo "Started nexus-iq-server"
}

do_console()
{
    cd $NEXUS_IQ_SERVER_HOME
    java -jar $JAVA_OPTIONS nexus-iq-server-$VERSION.jar server config.yml
}

do_stop()
{
    pid=`ps aux | grep nexus-iq-server | grep -v grep | awk '{print $2}'`
    kill $pid
    echo "Killed nexus-iq-server - PID $pid"
}

do_usage()
{
    echo "Usage: nexus-iq-server [console|start|stop]"
}

case $1 in
console) do_console
;;
start) do_start
;;
stop) do_stop
;;
*) do_usage
;;
esac

Setting up this script as a startup script will vary between operating systems and distributions depending on the init system used. Generally the script would be copied to a dedicated startup directory and assigned with run-levels and other characteristics for the start up. As an example on a Debian based systems the following commands could be used:

sudo su
cp nexus-iq-server /etc/init.d/
cd /etc/init.d
update-rc.d nexus-iq-server  defaults
service nexus-iq-server  start

Depending on the requirements from your system administrator the scripts will have to be modified to fit into your environment and exact deployment scenario.

[Tip]

Our support team can assist you with operating system and Linux distribution-specific tips and tricks regarding the startup script and installation.