Skip to main content

Run as a Service

When installing Nexus RepositoryTM for production usage it has to be configured 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 an operating system user with limited access rights dedicated to running the repository manager as a service

  • Ensure a suitable Java runtime environment is installed

  • Configure the service and ensure it starts as part of the operating system boot process

Linux

Configure Nexus Repository 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, init scripts that load commands to manage the service daemon. Before running the service configure an absolute path for your server files. Then create a nexus user with sufficient access rights to run the service.

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

run_as_user="nexus"

Symlink the $installdir to /opt/sonatype/nexus:

ln -s /opt/sonatype/nexus-3.78-1-01 /opt/sonatype/nexus

Adjust the location (shown above as "/opt/nexus-3.78-1-01'") as needed for your installation location. Ensure the user running Nexus Repository has appropriate permissions on this path.

chkconfig

This example uses chkconfig, a tool that targets the init scripts 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 Nexus Repository.

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 Nexus Repository 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
LimitNOFILE=65536
ExecStart=/opt/sonatype/nexus/bin/nexus start
ExecStop=/opt/sonatype/nexus/bin/nexus stop

User=nexus
Restart=on-abort
TimeoutSec=600
  
[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 system, verify that the service started successfully.

tail -f /opt/sonatype-work/nexus3/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.

Warning

Assign the appropriate permissions to the user running the nexus service.

PID File

This section is only applicable for Nexus Repository versions up to 3.77.2. It does not apply for versions 3.78.0 and beyond.

When started as a service on Linux, Nexus Repository will create a file that holds a process ID in the operating system /tmp directory. This file will have the name of the form:

  • prefix: "i4jdaemon_"

  • suffix: the absolute path to the nexus start script with path part separators replaced with underscores

    Example: Temporary directory is /tmp and the path to start the script is at /opt/nexus/nexus-3.14.0-04/bin/nexus, then the file created will be at "/tmp/i4jdaemon__opt_nexus_nexus-3.14.0-04_bin_nexus".

If the service pid file cannot be written the service startup will silently fail, without any logging statements written to the nexus.log.

If the Nexus Repository process is already stopped, and the service is failing to start, first confirm there is no log output being added to the nexus.log file. If not, then check for a pre-existing pid file. If that file is present, delete it first before trying to start the service.

The directory this file is created in can optionally be changed by editing $install-dir/bin/nexus.vmoptions and adding a line like this:

-Dinstall4j.pidDir=/some/absolute/path/to/a/directory

The directory specified by the property must already exist for the property to work - the directory will not be created automatically.

Native Linux Installers from the community

There are community-provided native installers for Linux available here: nexus-repository-installer

These installers set up Nexus Repository to run as a service. These are provided by the community, and not officially supported.

Configuring an External JDK

Sonatype provides distributions with runtime environments for each specific operating system. To use an external runtime, set the path for a specific Java location in the APP_JAVA_HOME environment variable.

The reference to this variable is found in the bin/nexus script.

# Priority list of jvm location
# APP_JAVA_HOME environment variable

Windows

The startup script that runs Nexus Repository on Windows platforms is bin\nexus.exe. The script includes standard commands for starting and stopping the service.

Use the install-nexus-service.bat located in the bin directory to install and update Nexus Repository on your Windows server. When upgrading from a version prior to Nexus Repository 3.79.1, uninstall the previous version before running this script.

cd C:\path\to\bin
install-nexus-service.bat

To customize the data directory path, include the path when running the install command:

install-nexus-service.bat C:\my-sonatype-work

To delete the service, run the following command:

sc delete SonatypeNexusRepository

Starting Nexus Repository as a Windows Service

Once the service is installed, you can start and stop it using the Windows Services Control Panel.

To stop the service from the command line, run the following command:

nexus.exe stop SonatypeNexusRepository

To start the service from the command line, run the command:

nexus.exe start SonatypeNexusRepository

Using a Different Java Runtime

The Nexus Repository binary is package the recommended Java runtime, however, this may be modified to use a another supported runtime. Use either of the following two options:

  • Set the environment variable APP_JAVA_HOME to the absolute path of the JDK you want to use.

  • Modify the nexus.rc file, and specify the absolute path to the JDK you want to use in the app_java_home variable.

    #app_java_home=C:\Path\To\Some\Alternate\JDK17\install

Configuring Memory for Nexus Repository Service on Windows

When running Nexus Repository 3 as a Windows service, you can adjust JVM memory settings using the -Xms (initial heap) and -Xmx (maximum heap) options within the nexus.vmoptions file.

The Windows service manager only accepts memory values in megabytes (MB) using the 'm' suffix. Using 'g' or other units will cause errors. This example sets an initial heap size of 1GB and a maximum heap size of 4GB.

-Xms1024m
-Xmx4096m

See Configuring the Runtime Environment

Nexus.exe Commands Before Release 3.78.0

Release 3.78.0 includes many changes to the way Nexus Repository is built. The tooling to build the nexus.exe package requires an alternate configuration as listed above.

Use the following command for version before 3.78.0.

start, stop, run, restart, force-reload, status

The service is named nexus by default. It is available in the Windows 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 an operating system startup. Alternatively, you can manage the service on the command line:

nexus.exe /start <optional-service-name>
nexus.exe /stop <optional-service-name>
nexus.exe /uninstall <optional-service-name>

The <optional-service-name> parameter with a value of e.g. nexus3 can be used.

Mac OS

The standard way to run a service on Mac OS 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 here:

<!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

Consider setting up a different user to run Nexus Repository and adapt permissions and the RUN_AS_USER setting in the nexus startup script. With this setup, the Nexus Repository 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