Skip to content

Deploy DRAPI to multiple servers

The Domino REST API is designed to be able to share configuration between multiple servers. To do this succesfully, you need to plan carefully and follow the steps outlined here. Sharing configuration works not only for tightly coupled systems, but also for servers that ate just on the same org or even across Domain boundaries (as long as trust and replication are setup correctly and working).

Not everything is shared

Settings in KeepConfig.nsf, mostly scopes and oauth applications replicate. Configuration settings in keepconfig.d and keepweb.d are per server. When you want to share those, you need to manually copy them over.

We are working on improving the config sharing.

Planning

You need to know the following to plan properly:

  • How are the participating servers replicating? You need to balance timelyness (to avoid replication conflicts) with resource consumption. Revisit these considerations.
  • What will be the source of identity: DRAPI's login/Identity Provider or some external one like Keycloak, Microsoft Entra (formerly known as "Azure Active Directory"), Okta or some other OIDC compliant identity service?
  • Do you have or plan DRAPI extensions?
  • What SPA are you planning to deploy to keepweb.d?

Installation

  • Follow the steps outlined here to install DRAPI on your main server. We shall refer to it as hub henceforth.
  • Start DRAPI on the hub using the Domino console command load restapi. This will create the database KeepConfig.nsf. When you upgrade DRAPI, you need to refresh the design of KeepConfig.nsf from KeepConfig.ntf
  • Use the Domino admin to create replicas of KeepConfig.nsf on all participating servers. You must retain the name and location.
  • If one of the participating servers already has a KeepConfig.nsf with a divergent replicaId, you must remove it. If it has no configuration entries, just delete it. When there are or you are not sure, rename it and deal with it later on.
  • Create and/or verify scheduled (or cluster) replication between the participating servers (henceforth referred to as spokes) and the hub.
  • Now install DRAPI on the spokes.

Configuration

There are three areas you need to configure:

  • Shared JWT Keys to login to DRAPI
  • TLS to secure web traffic
  • OIDC/OAuth

All those will write their configuration entries into keepconfig.d. For now, manually copy them between servers until a more convenient solution is available. Be careful to only copy the settings you want to share.

Shared JWT Keys to login to DRAPI

Use the Management Console to generate the Keys for JWT. As of 2025, you should prefer EC certificates. Follow the example and copy the 4 files across servers.

TLS to secure web traffic

The strongly recommended way is to use the Domino Certificate Manager. It's the most secure option and the least work. Create a file keepconfig.d\DominoCertMgr.json with the following content:

{
  "TLSCertStore": true
}

Copy the file to all participating servers.

You have other options, but they require more work.

OIDC/OAuth

  • To activate DRAPI's OAuth support, follow these steps. You might want to split the JSON file into two and take out the only server specific entry url - unless all participating servers sit behind a proxy serving the same URL.
  • Follow these steps for a generic IdP, these steps for Microsoft Entra ID, formerly Azure Active Directory.

Limit admin access

You don't need access to the AdminUI on your spoke servers, it only increases the possibility of replication conflicts by an absent-minded admin. The capability walkthrough Lab 11 outlines the steps to take to disable both the Admin UI and the Admin endpoints. Create a file keepconfig.d/disableadmin.json and copy it to all spokes, but not the hub.

{
  "versions": {
    "setup": {
      "active": false
    },
    "admin": {
      "active": false
    },
    "admin-server": {
      "active": false
    }
  },
  "verticles": {
    "Design": {
      "active": false
    },
    "KeepAdmin": {
      "active": false
    },
    "AdminAccess": {
      "active": false
    }
  },
  "webapps": {
    "webjars": {
      "active": false
    }
  }
}

Swagger UI

This also disables the Swagger UI. So use a tool like Bruno instead.

Let's connect

We really like to hear from you!

Your opinion matters. Let us know all your:

  • questions
  • discussions
  • ideas
  • feedback

Join the OpenNTF Discord channel.