Installing on macOS

Install ManualWorks on macOS in the following order.

  1. Install Java.

  2. Download the ManualWorks installation file.

  3. Extract the ManualWorks installation file.

  4. Start ManualWorks from the terminal.

  5. Run the Installation Wizard.

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.

Installing Java

Install Eclipse Temurin 25 with Homebrew. If Homebrew is not installed, install Homebrew first.

brew install --cask temurin@25

You can also download and run the macOS installer from the Adoptium website.

Installing ManualWorks

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

  1. Download the Linux installation file (tar.gz) from the ManualWorks download page. There is no separate installation file for macOS. Use the Linux file as is.

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

  1. 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.

If the Safari setting “Open ‘safe’ files after downloading” is on, Safari extracts the downloaded file automatically. In that case, you get a .tar file or a 3rabbitz directory instead of the .tar.gz file. If a .tar file remains, extract it with tar -xvf 3rabbitz-2025-0845.tar. If the 3rabbitz directory already exists, skip this step.

  1. Remove the macOS quarantine attribute from the extracted 3rabbitz directory. Files downloaded from the internet carry a quarantine attribute (com.apple.quarantine) that can prevent them from running.

xattr -dr com.apple.quarantine 3rabbitz

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

JAVA_HOME=$(/usr/libexec/java_home -v 25)
export JAVA_HOME

The path depends on the Java version and directory location.

Starting ManualWorks

3RABBITZ_HOME refers to the directory where ManualWorks is installed.

Start ManualWorks as follows.

  1. Go to the 3RABBITZ_HOME/bin directory.

  2. Run the following command.

./startup.sh

  1. 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.

  1. Go to the 3RABBITZ_HOME/bin directory.

  2. Run the following command.

./shutdown.sh