Skip to content

Install on macOS

Caution

  • The Domino server isn't available for macOS, so you can use the Domino REST API only with a Notes client.
  • Notes client support is experimental and not supported for any production use. It's provided to ease evaluation of the Domino REST API and experimentation without the need to configure a Domino server.

To install, follow the example below:

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.
java -jar restapiInstall.jar \
 -d="/Users/[your user name]/Library/Application Support/HCL Notes Data" \
 -i="/Users/[your user name]/Library/Preferences/Notes Preferences" \
 -r="/Users/[your user name]/Applications/restapi" \
 -p="/Applications/HCL Notes.app" \
 -a

All 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 creates a runrestapi.sh script in the Domino REST API installation directory. Run it to launch the Domino REST API. You can copy or move the script to ~/bin to add it to the macOS path.

Verify the installation

On a new Domino REST API installation, the following actions are performed:

  • Create the Domino REST API directory.
  • Copy all binary files needed by Domino REST API to that directory.
  • Create runrestapi.sh in the Domino REST API directory.

If an exiting installation is found at the location you specified as the restapi directory, the following additional actions are performed:

  • The installer checks for a file in your Domino REST API directory named installerFiles.txt.

  • If this file exists, the installer will use this list as the of files to remove before proceeding.

    • If you specified -u on the command line, removal of the old files and installation of the new are performed.
    • If you didn't specify -u, you will be asked if you want to upgrade. Answering A <enter> continues removal of the old files and installation of the new is performed.
  • 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, removal of the old files and installation of the new are performed.

    • If you didn't specify -u, you will be asked if you want to upgrade. Answering A <enter> continues removal of the old files and installation of the new is performed. Pressing any other key aborts.

    • If this isn't V1, you will be 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 it's 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, all files in the REST API directory structure are remove and installation of the new is performed. Pressing any other key aborts.

Tip

If your Notes client has an issue when running runrestapi.sh, please downloand and install openJ9 SDK and modify the JAVA_HOME variable in the runrestapi.sh to point to your openJ9 directory.

Limitations to client use

  • Use is for evaluation only, don't use for production.
  • You can't run the Notes client while you are running the Domino REST API against your local Notes install.
  • The Notes client must have the Don't prompt for a password from other Notes-based programs option set. This option is in the Security/User Security menu.

    Notes security

  • If your organization has a policy to disable the Don't prompt for a password from other Notes-based programs, you may need to go into Notes, disable and immediately quit Notes. Next time you go into Notes, this setting will be again disabled.

  • On the first time run of runrestapi, even with Don't prompt for a password from other Notes-based programs set, you may be prompted to enter your Notes password in the java window that the Domino REST API is running in. Even if the message prompt has scrolled, you can type in your password and Enter. Notes is prompting because Domino REST API is creating 2 databases needed to run the API.

For more information, see Deploy HCL Domino REST API to HCL Notes Client for additional steps required to use the Notes client.