Installation and configuration

Installation

System requirements

Before performing the installation, make sure to check the System requirements.

Download the Domino REST API

Go to HCL License and Download Portal.
On the sign in page, enter your username and click Next. The License & Download Portal home page opens.
In the Your Downloads pane, scroll to find and then select HCL Domino. The Download Packages page opens.
On the New Versions tab, select the HCL Domino REST API version that you want to download.

OR

On the License & Download Portal home page, go to Downloads → Search Downloads.
On the Download Search page, enter HCL Domino REST API in the Search for field, and then click Search.
Select the HCL Domino REST API version that you want to download from the search result.

Tip

If you downloaded the Domino REST API Installer, extract the .tar.gz file before installing.

Perform the following based on your OS:

macOS / linux - execute the following command: tar xvf ./Domino_REST_API_V1_Installer.tar.gz --no-same-owner --no-same-permissions
Windows - Newer versions of Windows supports extracting .tar.gz through the Explorer, also most 3rd party compression utilities supports extracting .tar.gz -- Consult your 3rd party tool documentation for more information.

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

Domino REST API can be installed on:

Notes Client on macOS
Notes Client on Windows
Domino Server on Windows
Domino Server on Linux
Domino Server on Docker or Kubernetes

All platforms use a Java-based installer, except Docker, which uses a Docker image. You can download the installer and the Docker image from your Flexnet account. For any questions, contact your HCL reseller.

The installer requires a series of parameters:

[sudo] java -jar restapiInstall.jar [-ahnsyV] -d=<dataDir> -i=<notesIni> -r=<restapiDir> -p=<programDir>

Tip

Notes and Domino install a JVM on your computer. You can and should use it to install.

On Linux, /opt/hcl/domino/notes/latest/linux/jvm/bin
On Windows, <Notes installation directory>/jvm/bin (example: Program Files/HCL/Notes/jvm/bin)

You can also verify the Java version by opening the command prompt, going to the installation location, and then typing java -version.

Explanation of parameters

Short	Full parameter	Mandatory	Description
`-d`	`--dataDir=<dataDir>`	✓	Directory of your HCL Notes or Domino data.
`-i`	`--ini=<notesIni>`	✓	HCL Notes/Domino notes.ini file.
`-r`	`--restapiDir=<restapiDir>`	✓	Directory to install the Domino REST API files into.
`-p`	`--programDir=<programDir>`	✓	Directory where HCL Notes or Domino is installed.

`-u`	`--upgrade`		Performs an upgrade from a previous version. Upgrade will remove known program files and libraries from the 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 rest API directory, this option will delete the entire contents of the rest API directory and subdirectories first before installing the new version.
`-a`	`--accept`		Automatically accept terms & conditions.
`-h`	`--help`		Show this help message and exit.
`-n`	`--noIniUpdates`		Install the files, show updated ini entries but don't write them out.
`-o`	`--oneTouchInstall`		If installing restapi as part of a Domino One Touch Install, use this option to prevent checking for Notes / Domino directories and notes.ini.
`-y`	`--dryRun`		Do not actually copy or alter files and settings.
`-s`	`--skipDirectoryCheck`		Skips the checks if the program and data directories contain Notes or Domino.
`-V`	`--version`		Print version information and exit.

Installation return codes

Code	Explanation
0	Operation completed with no known error.
1	License not accepted.
2	Installation type could not be determined or is not supported.
3	Check for / creation of installation directories failed.
4	Extraction of Domino REST API binaries and JARs failed.
5	Creation of start script/cmd failed.
6	Update of `notes.ini` failed.

Tip

You can use a response file (see below) to provide the parameters.

Using a response file

Instead of providing all parameters on the command line, the Domino REST API installer can be called using a response file:

[sudo] java -jar restapiInstaller.jar @responses.txt

The file contains one parameter per line. Lines starting with # get ignored. Variables with \ need to be escaped \\:

# Sample of an installer response file
--dataDir=D:\\Domino\\data
--ini=D:\\Domino\\data\\notes.ini
--restapiDir=C:\\Program Files\\HCL\\restapi
--programDir=C:\\Program Files\\HCL\\Domino
--accept

Hosting your static application

A typical use case for Domino REST API is to build a web UI with the flavor of the day web development framework like Angular, ReactJS, Swelte etc. These frameworks usually generate a build directory with a set of static files.

You can copy that directory to keepweb.d in your Domino data directory and Domino REST API will serve them on the /keepweb/ URL path. This eliminates the need for CORS configuration.

This is similar to Domino's feature serving static files from its domino/html directory.

Configuration & Security

Domino REST API is preconfigured with settings that allow you to get started right away. However, you should familiarize yourself with all configuration parameters and security settings before you deploy into a production environment.

Tip

Domino REST API honors all Domino access control mechanisms and doesn't allow anonymous access. For more information, see Access Control.

Understanding configuration

The configuration follows the concept of an Overlay File System. The base configuration is retrieved from the installation directory or jar files.

When jar files contain a resource /config/config.json, that configuration file is added to total configuration.

Then, it's overlaid with any JSON files in the keepconfig.d directory within the Notes data directory and then finally, with any environment parameters.

Hierarchy

The call hierarchy

All files contribute JSON, which are overlaid on top of each other. JSON elements with same names get overwritten. Arrays are replaced and not overwritten.

The JSON files in keepconfig.d are processed in alphabetical order. Last entry wins. This processing order allows you, for example, to disable elements temporarily through settings in a z-final-words.json file without impacting the permanent configuration.

For more information, see vert.x overloading rules.

Example

Given the files config.json, a.json and the environment variable PORT=8564, you get the result result.json as shown below:

config.json

{
  "PORT": 8880,
  "AllowJwtMail": true,
  "versions": {
    "basis": {
      "path": "/schema/openapi.basis.json",
      "active": true
    }
  }
}

a.json

{
  "dance": "tango",
  "PORT": 1234,
  "versions": {
    "basis": {
      "active": false
    },
    "special": {
      "path": "/schema/openapi.special.json",
      "active": true
    }
  }
}

Merge these 2 files and apply the environment variables.

result.json

{
  "PORT": 8564,
  "AllowJwtMail": true,
  "dance": "tango",
  "versions": {
    "basis": {
      "path": "/schema/openapi.basis.json",
      "active": false
    },
    "special": {
      "path": "/schema/openapi.special.json",
      "active": true
    }
  }
}

The actual result can be inspected on the Domino REST API management API, like on a local install.

Important notes

JSON overlay doesn't allow you to remove JSON elements. So, most settings have an active parameter that can be set to false in an overlay.

Follow this guide to remove Domino REST API from your system.