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 timeliness (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 databaseKeepConfig.nsf
. When you upgrade DRAPI, you need to refresh the design ofKeepConfig.nsf
fromKeepConfig.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 aren't 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:
- TLS to secure web traffic
- OIDC/OAuth
- Shared JWT Keys to login to DRAPI (if not using an external IdP)
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.
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. This will cause each server to attempt to find a certificate matching its fully qualified domain name as configured in its server document.
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.
Shared JWT Keys to login to DRAPI
When using DRAPI as your JWT provider, as opposed to an external identity provider like Keycloak, it can be useful to share the JWT issuing certificates across servers. The best way to do that is to store them in the Domino Certificate Manager. To do that, create a file keepconfig.d\DominoCertMgr.json
with the following content:
{
"JWTCertStore": true
}
If you already have a certificate chain in certstore.nsf, set the KeepCertStoreNameJWT
notes.ini parameter on each server to the subject host name of the certificate.
Alternatively, to generate the certificate chain using DRAPI, use the Management Console to generate the Keys for JWT. As of 2025, you should prefer EC certificates. This will create certificates in the certificate store using the common name of the Domino server and configure the local server to use it.
To enable access to this certificate for other servers, open the certificate store database and find the newly created certificate document. In that document, modify the Servers with access field to include the other Domino servers that will access it, and click Submit Request**. This causes the Certificate Manager to encrypt the certificate in a way compatible with each named server.
Then, set the KeepCertStoreNameJWT
notes.ini parameter on each server to the common name of the first server, for example MyServer
.
Alternately, to share certificates without the certificate store, follow the example and copy the 4 files across servers.
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.