How to: Domino 12 OneTouch Setup

Thursday, May 20, 2021 at 11:14 PM UTC

Warning: this tutorial is not working anymore, please refer to HCL's official documentation.

While preparing an upcoming webcast hosted by We4IT I am tinkering again with Domino 12 beta. One very cool feature of version 12 is the "OneTouch" setup procedure which allows you to install the server with an already prepared configuration for almost everything relevant.

For the preparation my goal only was to show how to install an additional server to an existing Domino domain (DNN), using an existing admin user as an administrator and a prepared server.id. I am using Docker to build this new server as this is the fastest method to check it out.

Preparations

In your Domino domain, the only thing you need to do is to create a new server ID for the test server. My test server is named "OneTouch/Busse", so the ID file is called "onetouch.id".

You also need a configuration file to define the basics of the new server. You can define this as JSON or use ENV data when running this new server on Docker - I prefer JSON as a file as I am used to it as a developer.

This is my example JSON file for the configuration to give you an idea of what it could look like:

{
    "serverSetup": {
        "server": {
            "type": "additional",
            "name": "OneTouch",
            "domainName": "Busse",
            "IDFilePath": "/local/notesdata/onetouch.id"
        },
        "network": {
            "hostName": "onetouch.local"
        },
        "org": {
            "orgName": "Busse"
        },
        "admin": {
            "CN": "Oliver Busse"
        },
        "existingServer": {
            "CN":  "Echo Base",
            "hostNameOrIP": "echobase.local"
        }
    }
}

The complete overview can be found here.

As you can see, there is a reference to the server ID file in the container volume that has to be prepared.

Also, there is a reference to a name which will act as an administrator which is defined only in the common name (CN) format. Although I have this name twice in my directory with different organization parts, it worked like a charm. I guess it's more important to have name variations in the LocalDomainAdmins group. In my case I have both of them defined as admins.

One thing that didn't work for me was defining the existing server using an IP address instead of a hostname. YMMV.

I am trying this on my local MacBook Pro, so this also may have an effect.

Files I prepared

I have two files prepared which need to be copied to the preparation container:

  • onetouch.id (the server ID generated with the HCL Admin client before and already added in the Domino directory)
  • onetouch.json which holds the config shown above

Creating the Docker stuff

If you haven't already, download the Domino 12 beta 3 Docker image from FlexNext and create a Docker image from it like this:

docker load --input Domino_12.0_DockerImage_Beta3.tgz

Then create a new volume for your test server. I called mine "onetouch".

docker volume create onetouch

Then, run the temporary container which attaches the volume. This allows you to copy the two files mentioned above to the data folder of the server:

docker run -it -v onetouch:/local/notesdata --name domino_onetouch --entrypoint /bin/bash --env SetupAutoConfigure=1 --env SetupAutoConfigureParams=onetouch.json -p 8585:8585 -p 1352:1352 -p 443:443 domino-docker:V1200_03252021prod

Please notice that this command does not only run the container but also gives you access to the shell inside the container!

Now, open a new terminal on your host and copy the two files to the volume:

docker cp onetouch.id domino_onetouch:/local/notesdata

docker cp onetouch.json domino_onetouch:/local/notesdata

 

For some reason, the two files had some weird ownerships in my case. This may be a macOS issue only, but to make sure permissions are ok, just change ownership for the files in the volume with

docker exec -u root -it domino_onetouch chown notes:root /local/notesdata/onetouch.id

docker exec -u root -it domino_onetouch chown notes:root /local/notesdata/onetouch.json

 

This assumes that both files (server ID and JSON config) are located in the data folder and start with the name "onetouch".

Now, the HCL documentation says you have to run a script in the first terminal where the container runs.

/local/start.sh

Watch out for the logs and messages. If your JSON file is error-free you should see the normal server messages - after a little while. Please allow some time for Domino to read the JSON and do its stuff. Remember: Domino is going through a normal configuration process here! Once finished, normal Domino console messages will appear.

Preparing for server setup...
Done.
[000141:000002-00007F03929750C0] Loading AutoConfiguration parameters from the JSON file onetouch.json
[000141:000002-00007F03929750C0] Function CopyIDFile /local/notesdata/onetouch.id returned result 'No error'
[000141:000002-00007F03929750C0] Function REGCreateNotefileReplica Echo Base!!names.nsf returned result 'No error'
[000141:000002-00007F03929750C0] Function SetupGetDAReplica Echo Base!!admin4.nsf returned result 'No error'

If so, you can shutdown the server with 'quit` and leave the container with CTRL+D. Remove the temp container now:

docker rm domino_onetouch

Now you are able to run the container the "normal" way:

docker run -d --name domino_onetouch -v onetouch:/local/notesdata --hostname onetouch.local --cap-add=SYS_PTRACE -p 1352:1352 -p 80:80 domino-docker:V1200_03252021prod

Your new Domino server is up and running using your existing domain settings. This only took a few minutes without invoking the remote setup utility and everything you were used to.

Isn't that cool?







Leave a comment right here