Install on Linux Domino server

On Linux, the installer installs the Domino REST APIs for use with an HCL Domino server. It's strongly recommended to use the default directories on Linux.

Note

Don't install using the java executable in /opt/hcl/domino/bin/. If your system doesn't have Java installed, you can use the java executable in the /opt/hcl/domino/notes/latest/linux/jvm/bin/ directory.

Before you begin

Extract the installer jar file from the downloaded tar file by running the following command:

tar xvf ./<installer file name> --no-same-owner --no-same-permissions

Example:

tar xvf ./Domino_REST_API_V1.0.9_R14_Installer.tar.gz --no-same-owner --no-same-permissions

You may ignore any warning starting with Ignoring unknown extended header keyword while decompressing the tar file.

Important

Starting Domino REST API version 1.0.7, the installer jar filename now includes the Domino version, for example, restapiInstall-r12.jar.
Starting Domino REST API version 1.0.9, there will be two installer jar files:
- For Domino 14, use restapiInstall-r14.jar.
- For Domino 12, use restapiInstall-r12.jar.

Install Domino REST API

Important

It is strongly recommended to shut down your Domino server before running the installer. The installer updates the notes.ini, which could conflict with a running Domino server.

To install, run the following commands:

sudo java -jar <installer jar file name> \
 -d="/local/notesdata" \
 -i="/local/notesdata/notes.ini" \
 -r="/opt/hcl/restapi" \
 -p="/opt/hcl/domino/notes/latest/linux" \
 -a

Example:

sudo java -jar restapiInstall-r14.jar \
 -d="/local/notesdata" \
 -i="/local/notesdata/notes.ini" \
 -r="/opt/hcl/restapi" \
 -p="/opt/hcl/domino/notes/latest/linux" \
 -a

Expand to see the explanation of the installation command parameters

Short	Full parameter	Description
`-d`	`--dataDir=<dataDir>`	Directory of your HCL Notes or Domino data. Mandatory
`-i`	`--ini=<notesIni>`	HCL Notes/Domino notes.ini file. Mandatory
`-r`	`--restapiDir=<restapiDir>`	Directory to install the Domino REST API files into. Mandatory
`-p`	`--programDir=<programDir>`	Directory where HCL Notes or Domino is installed. Mandatory
`-u`	`--upgrade`	Performs an upgrade from a previous version. Upgrade will remove known program files and libraries from the Domino REST API directory and install the new version into the same directory.
`-f`	`--forceUpgrade`	Performs an upgrade without regard to the previous version. If an unknown version or unexpected files are found in the Domino REST API directory, this option will delete the entire contents of the Domino REST API directory and subdirectories first before installing the new version.
`-a`	`--accept`	Automatically accepts terms & conditions.
`-h`	`--help`	Shows help message and exits.
`-n`	`--noIniUpdates`	Installs the files, shows updated ini entries, but doesn't write them out.
`-o`	`--oneTouchInstall`	If installing Domino REST API as part of a Domino One Touch Install, use this option to prevent checking for Notes / Domino directories and notes.ini.
`-y`	`--dryRun`	Doesn't actually copy or alter files and settings.
`-s`	`--skipDirectoryCheck`	Skips the checks if the program and data directories contain Notes or Domino.
`-V`	`--version`	Prints version information and exits.

The installer adds the restapi task to the automatically starting tasks. If opted out using -n, you must manually add the KeepInstallDir key into your notes.ini and then can subsequently issue load restapi manually in the Domino console.

For more information, see Domino REST API task.

Update environment

The restapi task requires 2 environment variables to be set before launching Domino.
Add the following directories to your PATH if not already there:
- your notesdata directory
- the Domino binary directory
- the res/C directory inside your Domino binary directory.
For example:

PATH=/local/notesdata:/opt/hcl/domino/notes/latest/linux:/opt/hcl/domino/notes/latest/linux/res/C:$PATH
Add the following to your LD_LIBRARY_PATH environment variable if not already there:
- your Domino binary directory
- the jvm/bin directory inside your Domino binary directory
- the jvm/bin/classic directory inside your Domino binary directory
For example:

LD_LIBRARY_PATH=/opt/hcl/domino/notes/latest/linux:/opt/hcl/domino/notes/latest/linux/jvm/bin:/opt/hcl/domino/notes/latest/linux/jvm/bin/classic:$LD_LIBRARY_PATH

Check file ownership and access rights

On Linux, you need to carefully check that your file and directory ownership and access rights are set correctly. The strongly recommended conventions are:

User to run the Domino server: notes.
Domino installed in /opt/hcl/domino -> owned by root.
Domino REST API installed in /opt/hcl/restapi -> owned by root.
Domino data directory /local/notesdata -> owned by notes.
Access for files and directories in /opt set to 755.
Access for directories in /local/notesdata set to 770.
Access for files in /local/notesdata set to 660.
NOTE: directories need the execute flag (1), otherwise they can't be accessed, so access for a directory must be an odd number always.
Don't set access anywhere to 777.

Check that Domino REST API is running

The installation, unless told otherwise, added restapi to the servertasks in the notes.ini. You can check on the Domino console if the REST API is running by using sh ta. In case restapi isn't listed as a running task, load it using load restapi. The Domino console will output a message on the success or failure to load.

Additional information

Installation explanation

The following details explain what happens when installing Domino REST API.

A new Domino REST API installation

creates the Domino REST API directory.
copies all binary files needed by Domino REST API to that directory.
copies restapi into the Domino directory.
updates the ServerTasks variable in notes.ini with restapi.
adds a variable KeepInstallDir to the notes.ini pointing to the Domino REST API directory.

If there is an existing installation at the location you specified as the restapi directory:

The installer checks for a file in your Domino REST API directory named installerFiles.txt.
If this file exists, the installer uses this list as the list of files to remove before proceeding.
- If you specified -u on the command line, removal of the old files and installation of the new version are performed.
- If you didn't specify -u, you will be asked if you want to upgrade. Answering A <enter> continues the removal of the old files and the installation of the new version.
If this file doesn't exist, which it didn't with Domino REST API V1, the installer checks to see if this is V1 by checking for the existence of the keep-core-1.9.5.jar file in the Domino REST API directory.
- If this is V1, the installer uses the list of known V1 files before proceeding.
  - If you specified -u on the command line, old files are removed and installation of the new version is performed.
  - If you didn't specify -u, you'll be asked if you want to upgrade. Answering A <enter> continues the removal of the old files and the installation of the new version. Pressing any other key aborts the process.
- If this isn't V1, you are notified that an unknown version has been found, and if you want to proceed, you will need to force an upgrade to continue. Forcing an upgrade removes ALL files from the Domino REST API directory and it's subdirectories, so take care that any files you may have put there will be removed. Domino REST API doesn't store any configuration or user files in the Domino REST API directory, only its runtime and libraries.
  - If you specified -f on the command line, all files in the Domino REST API directory structure are removed and installation of the new version is performed.
  - If you didn't specify -f, you will be asked if you want to force an upgrade. Answering A <enter> continues the removal of all files in the REST API directory structure and the installation of the new version. Pressing any other key aborts the process.

Next step

Perform post-installation tasks.