(Optional) Install an SSL certificate with ML Studio

If you want to run the Workbench using your own SSL certificate instead of the ones that we provide, make sure to follow this optional step.

This process requires that the workBenchInstall/.env file has both SIMMACHINES_API_HOST and SIMMACHINES_GUI_HOST set to the expected domain.

Before you request an SSL certificate, you must generate a private key. This generation is actually necessary in order to proceed with the SSL Certificate request. When you receive your SSL Certificate from your provider you will normally receive 2 files:

your-site.crt

your-site.ca-bundle

With these 3 files (the 2 received files and the private key) we will generate the 2 JKS keys (keystore and truststore) needed to install your certificate in ML Studio.

It is important to note that when generating the keystore and truststore you will be prompted to create a password for each. These passwords need to be stored securely and will be necessary for the certificate installation in ML Studio.

In order to generate the keystore execute the following commands:

1. Create a PKCS12 with the three files using the OPENSSL tool (You will be prompted for a password in this step, you need to use the same password in the following step). The password must be at least 6 characters long. This command is only one line.
   
   

   openssl pkcs12 -export -out your-site.pkcs12 -inkey private.key -in your-site.crt -certfile your-site.ca-bundle

2. Create a Java keystore from PKCS12 using the Keytool command. If Keytool is not available, you can install it by running apt install openjdk-8-jre-headless in Ubuntu. You will need to have superuser privileges.
   
   keytool -v -importkeystore -srckeystore your-site.pkcs12 -srcstoretype PKCS12 -destkeystore myKeystore.jks -deststoretype JKS

Now in order to generate the truststore, execute the following two commands (these are one line each):

keytool -import -alias yourSiteCA -trustcacerts -file your-site.ca-bundle -keystore myTruststore.jks

keytool -import -alias yourSiteCRT -trustcacerts -file your-site.crt -keystore myTruststore.jks

At this point you should have generated both the keystore and truststore with their respective passwords. With these, we will set up ML Studio with the certificate.

First you need to copy the keystore and truststore to the docker containers with the following commands. Keep in mind that they are all only one line each.

First to the API docker container:

docker cp myKeystore.jks \ workbenchinstall_restAPI_1:/home/simuser/cloud/certificates/

docker cp myTruststore.jks \ workbenchinstall_restAPI_1:/home/simuser/cloud/certificates/

Then to the GUI docker container:

docker cp myKeystore.jks \ workbenchinstall_restGUI_1:/home/simuser/cloud/certificates/

docker cp myTruststore.jks \ workbenchinstall_restGUI_1:/home/simuser/cloud/certificates/

You may restart ML Studio by issuing both Docker Compose commands while on the installation path

docker-compose down

docker-compose up -d

Then, we need to edit the configuration file in order to update the key names and passwords.

First go to the installation folder named workBenchInstall, then edit the configuration file named docker-compose.yml.

When you open it you will see something like this:

You’ll see there’s a restAPI section. We need to edit here but also in the following restGUI section.

In this restAPI section you need to edit the fields highlighted in the image below:

For the FILE fields you don’t need to change the PATH, only the keyfile name in case it is different from the one shown.

For the PASSWORD fields enter the respective passwords used for the generation of each key.

You can ignore the LICENSES_TRUST_STORE fields since these serve a different purpose that’s not utilized in your current ML Studio installation.

Similarly, in the restGUI section edit the highlighted fields with the same information as before:

After editing and saving the file, while you are in the same workBenchInstall directory, execute the following commands in order to bring down the Workbench deployment and then turn it back on, including the recent changes:

docker-compose down

docker-compose up -d

After this, ML Studio should have started successfully with the new certificate enabled.