Installing Java

Checking Whether Java Is Installed

To check whether Java is installed, and which version, run the following command in the terminal.

java -version

If the version is earlier than Java 11, install Java.

In line with the Oracle Java license, ManualWorks supports the LTS (Long Term Support) versions 8, 11, 17, 21, and 25. For stability and performance, however, we recommend Java 25.

Installing Java

How to install Java depends on your Linux distribution and version. Install Java in the way that fits your distribution. To install OpenJDK, see Using OpenJDK.

Installing ManualWorks

To install ManualWorks, download the installation file and extract it.

Download the Linux installation file from the ManualWorks download page.
Transfer the downloaded file to the Linux server, for example with FTP.

If the Linux server is connected to the internet, you can download the installation file directly on the server with the following command.

wget https://www.3rabbitz.com/r/home/download/linux --content-disposition

The full path of the installation directory must not contain spaces or special characters (~!@#$%^&*()_+|"<>':`).

Extract the file with the tar command.

tar -xvf 3rabbitz-2025-0845.tar.gz

The installation file name has the form 3rabbitz-2025-BUILD_NUMBER.tar.gz. Replace 0845 in the example with the build number of the file you downloaded.

Product directory structure

Set JAVA_HOME in your Linux user profile (.profile) or in the ManualWorks scripts (3RABBITZ_HOME/bin/startup.sh and 3RABBITZ_HOME/bin/shutdown.sh).

JAVA_HOME=/usr/lib/jvm/jdk-25.0.1
export JAVA_HOME

The path depends on the Java version and directory location.

Configuring the Database

To use a different database, configure the database connection before you start ManualWorks. See the following chapters.

If you use the default database included in the installation file, go to the next step.

To move data from an earlier version that used Apache Derby to H2 or another database, use the database migration feature. To turn it on, place an empty file named migrate in the 3RABBITZ_HOME directory and start ManualWorks. Migrating to H2 requires Java 11 or later. For details, see Migrating the Database.

Starting ManualWorks

3RABBITZ_HOME refers to the directory where ManualWorks is installed.

Start ManualWorks as follows.

Go to the 3RABBITZ_HOME/bin directory.
Run the following command.

./startup.sh

Complete the initial setup with the Installation Wizard.

ManualWorks runs in the background. Its log is written to 3RABBITZ_HOME/logs/catalina.out. If the Installation Wizard does not appear, check this file.

Stopping ManualWorks

Stop ManualWorks as follows.

Go to the 3RABBITZ_HOME/bin directory.
Run the following command.

./shutdown.sh

Running as a Non-root Account

For security, we recommend running ManualWorks with a dedicated non-root account. The following example runs ManualWorks installed in /opt/3rabbitz with the rabbitz account.

Create the account that will run ManualWorks.

sudo useradd -m rabbitz

Change the owner of the installation directory. If the data and backup directories are outside the installation directory, change their owner too.

sudo chown -R rabbitz:rabbitz /opt/3rabbitz

Start ManualWorks as the new account.

sudo -iu rabbitz /opt/3rabbitz/bin/startup.sh

A non-root account cannot open ports below 1024. The default port, 1975, is not affected. To serve ManualWorks on port 80, see Using Port 80 with iptables.

Registering as a systemd Service

To start ManualWorks automatically when the server starts, register it as a systemd service. Create the file /etc/systemd/system/3rabbitz.service with the following content. Replace the installation directory, account, and JAVA_HOME with your actual values.

[Unit]
Description=ManualWorks
After=network.target

[Service]
Type=forking
User=rabbitz
Group=rabbitz
Environment=JAVA_HOME=/usr/lib/jvm/jdk-25.0.1
PIDFile=/opt/3rabbitz/logs/catalina.pid
ExecStart=/opt/3rabbitz/bin/startup.sh
ExecStop=/opt/3rabbitz/bin/shutdown.sh
SuccessExitStatus=143
TimeoutStopSec=330

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now 3rabbitz

shutdown.sh waits up to 300 seconds for ManualWorks to stop, so set TimeoutStopSec to a longer value.