HCL Nomad Web - in a container

Wednesday, June 29, 2022 at 6:27 PM UTC

Daniel Nashed did it again: he simplified a process to get faster results. This time: getting started with HCL Nomad Web and SafeLinx.

HCL Nomad Web needs SafeLinx as Proxy and additional files which are the WAS part of the product which will run in your browser. Installing and especially configuring a SafeLinx server may be cumbersome and at least I failed several times. With SafeLinx now running in a container and using a simple ENV file to configure all the important stuff is a huge step forward.

However, there is currently no documentation or a step-by-step guide. I try to do this here now. In my case I am installing SafeLinx without a database.

Ingredients

This is a list of things you need to prepare:

  • a host, reachable from the internet
  • git, Docker installed and running (or whatever you prefer for containers) and docker-compose
  • on the host, the repository from HCL for all stuff Docker
  • on the host, the software packages for SafeLinx and Nomad Web
  • a Domino server 12.0.1 (or newer) acting as the CertMgr in your Domain
  • ID vault ready and set up containing the IDs of the users which should be able to use Nomad later

Building the image

Once you have cloned HCL's repo, switch to the develop branch with git checkout develop.

In the repo's root folder, execute

./build.sh safelinx +nomadweb

We will also need two files from the folder examples/safelinx:

  • .env
  • docker-compose.yml

Copy them to a folder of your choice, e.g. /install/safelinx.

Open the file .env in the editor of your choice, e.g.

nano .env

Change the values for the environment variables according to your infrastructure. You basically have to define

  • the hostname of the SafeLinx machine (you are here)
  • Domino domain name (ORG)
  • LDAP hostname
  • LDAP credentials and port (or leave credentials blank if you support anonymous LDAP usage)
  • CertMgr Domino server's hostname

Run docker-compose up -d to create and start the container.

When you do this for the first time, two data volumes will be created and the logs begin with a special section that you should have a look into.

docker logs safelinx

It's good to copy and store the info in that section somewhere as we need it later. This section you will see looks like this:

Generated PEM import password: EbvT8vwWhI4m8blPKKoxOU47e4Idcc3Hczuib6kwQkw=
Write down the password, if you plan to import password protected PEM files (e.g. from HCL Domino CertMgr)
Creating new certificate for nomad.notesx.net

Signature ok
subject=O = MyOrg, CN = nomad.example.com
Getting CA Private Key
Export Password: NN8Yt+cXXffn+qWG1U10OK0XmfHd/KWKdWoKjaQZQlE=

In our approach we will prepare the Domino CertMgr to expose the SSL certificate for the Nomad host, so we need the PEM import password (the first one) later.

The logs also will show an error that the certificate could not be set as the key does not match blah blah - that's ok for now.

Preparing Domino CertMgr

In my case, to provide an endpopint for the ACME challenge, I also put a Domino server on the Nomad host machine. This is not needed but I did it since I didn't want to tinker with nginx for a redirect to the "real" CertMgr server. Your environment may vary here.

The most important thing is: start with new TLS credentials as we need a certain function that we don't get with an existing one.

Create a new TLS credentials configuration. Define the hostname and the server(s) that should be able to access this setting (usually at least the CertMgr server itself). Select your preferred cert provider and ACME account. If you use LetsEncrypt, please use the "Staging" profile first. You can switch to "Production" later if everything works fine.

Important: DO NOT SAVE the document now, click the action button "Create Exportable Key" first! (See the picture).

In the dialog use the password you noted in the step before, i.e. the PEM import password. Click ok and then submit the TLS credentials.

Assuming you are using LetsEncrypt and everything worked fine, switch to "Production" and repeat the submission only.

Now we have a certificate - what's next?

Open the TLS credentials again and switch to the Security/Keys tab.

On your SafeLinx host (assuming you are still in the directory where you have the .env file), cd to the directory cert-mount. This directory contains two files:

  • certstore_export.pem
  • root_cert_safelinx_ca.pem

Ignore both Wink

The "official" way would now be to export the TLS credentials as a file, create a password and bring this file to your SafeLinx host - the following steps are much easier though.

Open an editor again and now copy and paste both the certificate chain content AND the exportable private key from your TLS credentials document.

Save the file as server.pem in that folder. Exit the editor.

If you check the folder again, the file you just created should be gone - this is intentional. If so, also check the logs of the SafeLinx container with

docker logs safelinx

You should see something like this at the end:

Certificate
-----------

SAN         : DNS:nomad.example.com
Subject     : CN = nomad.example.com
Issuer      : C = NO, O = Buypass AS-983163327, CN = Buypass Class 2 CA 5
Expiration  : Dec 25 22:59:00 2022 GMT
Fingerprint : 8B:87:45:16:71:5B:F3:BA:E3:F7:F0:55:CB:4A:AB:09:AA:2D:BC:E1
Serial      : 02D67A35579520C50F385F

(This example doesn't use LetsEncrypt but Buypass).

If you see this, then your SafeLinx server successfully got the certificate from your Domino CertMgr!

Check this by opening the URL in a supported browser:

https://nomad.example.com

It should return a valid SSL connection.

If you have a valid certificate you can also put it directly in that folder to let the SafeLinx container read it and then use it. This approach of using the Domino CertMgr is optional but very smart if you already use it.

Now what?

Try to login with your Domino web user credentials. After the a while you should be prompted to login with your user ID credentials (these can be different of course).

After another while (only for the first time) you should be presented the Nomad workspace.

Resume

I think this is awesome and stupid simple once you know the certification hurdles and know how to overcome them. Once again, Daniel was the helping hand here. Of course this is not an official documentation but I thought a quick start guide would be helpful for others to save some time. Grin

Sources:

https://blog.nashcom.de/nashcomblog.nsf/dx/safelinx-nomad-server-community-project.htm

https://blog.nashcom.de/nashcomblog.nsf/dx/how-to-create-exportable-tls-credentials-with-domino-12.0.1.htm





Latest comments to this post

Daniel Nashed wrote on 02.07.2022, 20:48

Glad you got it working without much documentation needed.
It's still only available in the develop branch. But I think I will take it over soon to the main branch to get feedback.

I just wrote a first version of the documentation:

https://opensource.hcltechsw.com/domino-container/safelinx/

Sadly the requirements for certificates has become more strict. The container comes with it's own root CA.
But today a private CA isn't that helpful. The out of the box CA is just a starting point and you really need a public cert.

There are multiple ways to get it working with multiple integration options. The certificate part is always the hardest part.

There is a NGINX integration as well, that could help in more complex environments in the same sample/safelinx directory.

It comes with documentation in the NGINX file itself.

 

 

 

 

 Link to this comment

Leave a comment right here