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.
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
Copy them to a folder of your choice, e.g.
Open the file
.env in the editor of your choice, e.g.
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
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
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
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:
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:
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:
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.
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.
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.