7 minute read

This article explains how to configure Digital.ai Deploy and Digital.ai Release with HTTPS. We’ll cover all the different scenarios and also the configuration of the Deploy cli and the xl cli.
All the steps are tested with version 22.3 of Deploy and Release but should also apply to previous versions up to 10.3

There are 3 ways to configure Deploy and Release with HTTPS:

  1. During the first setup using a self-signed certificate generated by the setup
  2. During the first setup using an existing certificate
  3. After the first setup

Case 1: Configuration during the first setup using a self-signed certificate generated by the setup

For both Release and Deploy, the command ./run.sh -setup has the option to generate a keystore with a self-signed certificate (conf/keystore.p12).
This simple setup is fine for test purpose but if you want to connect the Deploy cli to Deploy or use the xl cli, this simple setup is not enough as we need a certificate.

Sample simple setup answers:

➜  bin ./run.sh -setup
[....]
Do you want to use the simple setup?
Default values are used for all properties. To make changes to the default properties, please answer no.
Options are yes or no.
[yes]: no
[....]
Would you like to enable SSL?
Options are yes or no.
[yes]:

Would you like to generate a keystore with a self-signed certificate for you?
N.B.: Self-signed certificates do not work correctly with some versions of the Flash Player and some browsers!
Options are yes or no.
[yes]: yes

Would you like to enable mutual SSL?
Options are yes or no.
[yes]: no
[....]
Finished setup.

The wizard has generated a keystore in the conf directory conf/keystore.p12.
To check the content of the keystore run this command (there is no password by default):

-> keytool -list -v -keystore  conf/keystore.p12
Enter keystore password:
[....]
Keystore type: PKCS12
Keystore provider: SUN

Your keystore contains 1 entry

Alias name: jetty
Creation date: 12 oct. 2022
Entry type: PrivateKeyEntry

The alias jetty is important as it’s used by the embedded Jetty HTTP server to read the key. As we can see, the store does not contain any certificate.

Case 2: Configuration during the first setup using an existing certificate

Before we run the setup, let’s generate a key and certificate:

-> openssl req -new -newkey rsa:2048 -days 365 -x509 \
> -keyout xlKey.key -out xlCert.crt \
> -addext "subjectAltName = DNS:localhost" 
Generating a RSA private key
..........................................................................................................................................+++++
.............+++++
writing new private key to 'xlKey.key'
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:
-----
[....]
-----
Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:digitalai
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:localhost
Email Address []:

NOTE: It’s important to set the correct server name in the Common Name during the creation of the certificate. This will be used for the cli to connect to Deploy.
Note also the -addext where you have to set your domain name; see later for the xl cli requirements.

Then we export to a store:

➜  openssl pkcs12 -export -inkey xlKey.key  \
> -in xlCert.crt -name jetty -out keystore.p12
Enter pass phrase for xlKey.key:
Enter Export Password:
Verifying - Enter Export Password:

Note the jetty alias; it’s used by Jetty to load the certificate.

Copy the keystore.p12 file into the conf directories of Release and Deploy

Release

Run the setup for Release:

-> bin ./run.sh -setup
[....]
Do you want to use the simple setup?
Default values are used for all properties. To make changes to the default properties, please answer no.
Options are yes or no.
[yes]: no
[....]
Would you like to enable SSL?
Options are yes or no.
[yes]:

Would you like to generate a keystore with a self-signed certificate for you?
N.B.: Self-signed certificates do not work correctly with some versions of the Flash Player and some browsers!
Options are yes or no.
[yes]: no

What is the path to the keystore?
[]: conf/keystore.p12

What is the password to the keystore?
[]: storepassword

What is the password to the key in the keystore?
[]: storepassword

Would you like to enable mutual SSL?
Options are yes or no.
[yes]: no

[....]
Finished setup.

Done, Release is now configured with HTTPS. You can start Release.

Deploy

Follow the same procedure with Deploy.

➜  bin ./run.sh -setup

[....]
Do you want to use the simple setup?
Default values are used for all properties. To make changes to the default properties, please answer no.
Options are yes or no.
[yes]: no
[....]
Would you like to enable SSL?
Options are yes or no.
[yes]:

Would you like to generate a keystore with a self-signed certificate for you?
N.B.: Self-signed certificates do not work correctly with some versions of the Flash Player and some browsers!
Options are yes or no.
[yes]: no

What is the path to the keystore?
: conf/keystore.p12

What is the type of the keystore?
Options are jks, pkcs12, or other keystore types supported on the JVM.
[jks]: pkcs12

What is the password to the keystore?
Password:

What is the password to the key in the keystore?
Password:

Would you like to enable mutual SSL?
Options are yes or no.
[yes]: no

[....]

Done, Deploy is now configured with HTTPS. You can start Deploy.

Deploy cli

We can follow the steps as in the documentation here

Export the certificate from the keystore

keytool -export -keystore keystore.p12 -alias jetty -file XLDeployServerCert.cer

Import the certificate as a trusted certificate

➜ keytool -import -alias XLDeployServerCert -file XLDeployServerCert.cer -keystore myCliTruststore.jks
Enter keystore password:
Re-enter new password:
Owner: CN=localhost, O=digitalai, ST=Some-State, C=AU
Issuer: CN=localhost, O=digitalai, ST=Some-State, C=AU
[....]
Trust this certificate? [no]:  yes
Certificate was added to keystore

Move the trustore to the CLI installation

Copy the myCliTruststore.jks file into the conf directory of the cli installation.

Configure the cli to use the truststore

Modify the cli.cmd or cli.sh as:

DEPLOYIT_CLI_OPTS="-Xmx512m -Djavax.net.ssl.trustStore=conf/myCliTruststore.jks -Djavax.net.ssl.trustStorePassword=storepassword"

Start the Deploy cli

➜  bin ./cli.sh -secure -host localhost -port 4517
[....]
Username: admin
Password:
Welcome to the XL Deploy Jython CLI!
Type 'help' to learn about the objects you can use to interact with XL Deploy.
[....]
admin >

The Deploy cli is now connected to the Deploy server using the self-signed certificate.

The xl cli

The xl cli is written in Go, so the only way to trust a certificate is to install the certificate in the truststore of your machine.

Refer to your os specific procedure to trust the certificate.

On my MAC I used this command:

-> sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain xlCert.crt

After the installation you can execute the command like:

-> xl generate xl-deploy -p Applications -f apps.yaml --xl-deploy-url https://localhost:4517
Generating definitions for path Applications from XL Deploy to apps.yaml

-> xl generate xl-release -d -f def.yaml --xl-release-url https://localhost:5516
Generating definitions from XL Release to def.yaml

Remember the -addext option we used to generate the certificate?
Since Go version 1.15, the legacy behavior of treating the CommonName field on X.509 certificates as a hostname when no Subject Alternative Names (SAN) are present is now disabled by default. So it’s mandatory to add the -addext "subjectAltName = DNS:domain-name.com" with the openssl command.
Otherwise you get this error with the xl command:
“Error while generating document: Post “https://localhost:4517/login”: x509: certificate relies on legacy Common Name field, use SANs or temporarily enable Common Name matching with GODEBUG=x509ignoreCN=0”

Case 3: Configuration after the first setup

The configuration is very simple.

  1. Get your key and certificate or generate the key and certificate as in the previous point
  2. Move the keystore file keystore.p12 into the conf directory of Deploy and Release
  3. Modify the Deploy config file conf/deployit.conf and the Release config file conf/xl-release-server.conf like below (add the last 4 key/values):
ssl=true
keystore.path=conf/keystore.p12
keystore.keypassword={your_password}
keystore.password={your_password}
keystore.type=pkcs12 (only for deploy)

(the passwords will be encrypted during the next start)

Deploy and Release are now configured with HTTPS.

Connect Deploy from Release

With Deploy configured in HTTPS, if you try to connect Release to Deploy you are going to have an error like below:

To get a successful connection, Release must trust the Deploy certificate.
There are 2 ways to solve the issue:

  • by disabling the ssl verification

In the Release directory modify the conf/deployit-defaults.properties by setting:

Restart Release.

If you followed all the previous steps then in our case it’s quite simple as we use self-signed certificate. Set the previous key xldeploy.XLDeployServer.verifySSL to the whole path of the Deploy certificate:

Restart Release.

You may also enjoy

Release Runner Installation

3 minute read

Starting from version 24.1, Release Runner (formely known as Release Remote Runner) installation is very straightforward. This article outlines how I install...

Release in an air-gapped environment

2 minute read

An air-gapped environment is a network physically isolated from unsecured networks. It means that when you install Digital.ai Release in such environment, Re...