The full installation consists of three components:
Rosette Server (RS), including Rosette Entity Extractor (REX)
REX Training Server (RTS)
Rosette Adaptation Studio (RAS)
The components can be installed on three separate machines or all together on a single machine. One machine is adequate for light loads and configuration testing. For production work, large projects, or multiple projects, we recommend installing on three machines.
For either install, you will need to know the fully qualified host name where a component is installed. For the three machine install, you will need the three host names. For a single machine install, you only need the one name.
Important
For all installations localhost is not an acceptable name; the hostname must be addressable from within the Docker containers.
To find the host name for a machine, run the command hostname -f on the machine.
Docker Compose Configuration
When you extract the zip files, each server directory will contain the following 2 files for Docker:
docker-compose.yml
-
.env
Tip
The .env file is a hidden file. All file names that start with a . are hidden. Type ls -a to list the hidden files along with the other files in the directory.
The directories used to connect the components, as shown in the figure below, are defined in the .env for each product. To view or change a value, edit the .env file, not the docker-compose.yml file.
Example .env file for RTS
RTS_PORT=9080
# Default /basis/rts/workspaces
WORKSPACE_ROOT=$RTS_WORKSPACE_ROOT
# Default /basis/rts
# Wordclasses need to go into this directory
ASSETS_ROOT=$RTS_ASSETS
# Default /basis/rts/config
# File is mongodal_config.yaml
DAL_CONNECTOR_CONFIG_DIR=$DAL_CONNECTOR_CONFIG_DIR
# The release script will update this variable.REX_TRAINING_SERVER_IMAGE=rex-training-server:0.4.2
# See https://www.ibm.com/support/knowledgecenter/SSD28V_liberty/com.ibm.websphere.wlp.core.doc/ae/twlp_admin_customvars.html
# for details on the contents of this file.
JVM_OPTIONS=/basis/rts/config/jvm.options
# See https://www.ibm.com/support/knowledgecenter/SSEQTP_liberty/com.ibm.websphere.wlp.doc/ae/cwlp_config.html# for details on the contents of this file.
SERVER_XML=/basis/rts/config/server.xml
# Where to store RTS logs
RTS_LOGS=$RTS_LOGS
The variable values set in the .env file are used in the docker-compose.yml file:
version: '3'
services:
rex-training-server:
image: ${REX_TRAINING_SERVER_IMAGE}
volumes:
- ${WORKSPACE_ROOT}:/basis/rts/workspaces
- ${ASSETS_ROOT}:/basis/rts
# The file mongodal_config.yaml must exist in this directory
- ${DAL_CONNECTOR_CONFIG_DIR}:/basis/rts/config
- ${RTS_LOGS}:/logs
# Optionally override JVM settings here, default -Xms8G -Xmx16G
# - ${JVM_OPTIONS}:/config/jvm.options
# Optionally override Server settings here
# - ${SERVER_XML}:/config/server.xml
environment:
- AS_MONGO_DAL_CONNECTOR_CONFIG_DIR=/basis/rts/config
ports:
- ${RTS_PORT}:9080
Specifying Service Restart Policy
The service restart policy for each service can be specified in the docker-compose.yml files by specifying the restart parameter. This allows containers to be restarted on server reboot, Docker service restart, etc. Restart can be one of no, always, on-failure, unless-stopped. The default is no if not specified.
Example for Rosette Server docker-compose.yml:
version: '3.2'
services:
rosette-server:
restart: "no"
image: ${ROSETTE_SERVER_IMAGE}
ports:
......
Important
Recommended Operating System: 64 bit Linux or macOS.
Windows deployment (including Docker Desktop for Windows) is not tested or supported at this time. Windows users using Windows 10 pro or Windows Server 2016 or 2019 should run Rosette Adaptation Studio in a Linux virtual machine under Hyper-V or VMWare Workstation.
You must install the Docker files for Rosette Server, REX Training Server, and Rosette Adaptation Studio in different directories or on different computers.
All machines must have Docker and docker-compose installed.
-
Before installing any components, create the top-level directory for all components with proper permissions on each machine.
In this example, the install directory (<installDir>) is /basis.
sudo mkdir /basis
sudo chmod 2777 /basis
Table 2. Tested Versions
Component |
Version |
Docker |
19.03.12 or 19.03.13 |
docker-compose |
1.26.0 |
CentOS |
7.8.2003 |
Table 3. Rosette Server System Requirements
Resource |
Requirement |
CPU |
4 virtual CPU cores |
Memory |
32 GB |
Disk Space |
100 GB recommended for multiple small/medium projects. The actual amount required is determined by size and number of active projects. |
Table 4. REX Training Server System Requirements
Resource |
Requirement |
CPU |
4 virtual CPU cores |
Memory |
32 GB |
Disk Space |
500 GB recommended for multiple small/medium projects. The actual amount required is determined by the size and number of active projects. |
Table 5. Rosette Adaptation Studio System Requirements
Resource |
Requirement |
CPU |
4 virtual CPU cores |
Memory |
16 GB |
Disk Space |
500 GB recommended for multiple small/medium projects. The actual amount required is determined by the size and number of active projects. |
The shipment contains the following files:
rs-installation-<version>.zip: Files for Rosette Server. The size of the file is dependent on the number of languages included.
rts-installation-<version>.zip: Files for REX Training Server.
ras-installation-<version>-zip: Files for Rosette Adaptation Studio.
rosette-license.xml: Rosette license key file. During the installation of Rosette Server you will be prompted for the location of this file.
The following documentation files are included in the release:
Install Rosette Server (RS)
You must have Docker and docker-compose installed.
Unzip the file rs-installation-<version>.zip.
-
From the directory rs-installation-<version>, run the installation script:
./install-rs.sh
The Rosette Server image in this package differs from a typical Rosette Server Docker image install:
The Rosette roots contain the models and data for the Rosette endpoints. In this install they are mounted externally, not unzipped in the Docker container. This lets you place them on an NFS or network drive, provides faster startup, and uses less Docker daemon space.
The directories <installDir>/config and <installDir>/config/rosapi are extracted and mounted externally to facilitate customizing the installation.
Two custom profiles are provided in <installDir>/rosette/server/launcher/config/custom-profiles.
The installer will prompt you for the following information:
Table 6. Rosette Server Installer Prompts
Prompt |
Purpose |
Options |
Notes |
Installation directory |
Installation directory for Rosette Server files |
Default:
/<installDir>/rs
|
This is now the RSinstallDir |
Installation directory for docker files |
Directory where the Rosette Server docker compose files will be installed. |
Default:
/<RSInstallDir>/rs-docker
|
The disk requirements for the docker-compose files are minimal (< 1 MB). However, other parts of the install require greater disk space |
Load the Rosette Server docker image? |
Load the Docker images so they are available on the local machine |
Otherwise, load them to a Docker registry shared by all machines. |
|
Directory for Rosette Server configuration files |
This directory will be mounted as a volume. |
Default:
/<RSinstallDir>/config
|
The directory configuration to customize Rosette Server. |
Location of the rosette-license.xml file |
This file will be mounted as a volume. |
|
You will be prompted if this file should be copied to its default location of /config/rosapi. Copy it to this location to make management of Rosette Server easier and remove the need to mount the license file. |
Port Rosette Server should listen on |
|
Default: 8181 |
This port and hostname will be required when installing Rosette Adaptation Studio. |
Location of Rosette Server logs |
|
Default: /<RSinstallDir>/logs |
|
Fully qualified host name where REX Training Server is installed |
Used to connect the RTS Decoder to the REX Training Server |
|
The REX Training Server does not need to be installed before Rosette Server, but you must know where it will be installed.
Cannot be empty, localhost or 127.0.0.1
|
Directory Rosette Server roots |
This directory will be containing mounted as a volume. |
Default: /<RSinstallDir>/roots |
The roots can be quite large depending on the number of languages licensed. |
Rosette Server Memory Management
There is not a single one size fits all number here. The best value for max heap size depends on a number of factors:
activated endpoints and features
usage pattern
data characteristics such as size (both character and token lengths), language, and genre
java garbage collector and its settings
Please note that it’s not recommended setting the max heap to the amount of physical RAM in the system. More heap doesn’t always translate to better performance, especially depending on your garbage collection settings.
Rosette Server’s data files are loaded into virtual memory. Some endpoints, such as /entities, involve a large amount of data. In order for Rosette to operate at its peak performance, we recommend that you reserve enough free memory to allow memory mapping of all our data files so that page misses are minimized at runtime.
To modify the JVM heap edit the .env file: /basis/rs/rs-docker/.env and set ROSETTE_JVM_MAX_HEAP to the required size in GB.
# Maximum JVM heap in GB
ROSETTE_JVM_MAX_HEAP=16
-
Navigate to the installation directory containing the Docker Compose files. The default is:
/basis/rs/rs-docker
-
Run the service in detached mode.
docker-compose up -d
-
To check that the service has started, check the logs. This will display the last few lines of the logs from the service.
tail /basis/rs/logs/wrapper.log
-
The service can be tested by using a browser and navigating to http:<host>:<port>/rest/v1/info. This will display information about the version of RS.
Example:
http://localhost:8181/rest/v1/info
This instance of Rosette Server is shipped with two custom profiles, ad-base-linguistics and ad-suggestions. The are stored in /rosette/server/launcher/config/custom-profiles/ in the image. See Custom Profiles for instructions on setting up and using custom profiles.
Install REX Training Server (RTS)
You must have Docker and docker-compose installed.
Unzip the file rts-installation-<version>.zip.
-
From the directory rts-installation-<version>, run the installation script:
./install-rts.sh
The REX Training Server installer will prompt you for the following information:
Table 7. REX Training Server Installer Prompts
Prompt |
Purpose |
Options |
Notes |
Installation directory |
Installation directory for REX Training Server files |
Default:
/<installDir>/rts
|
This is now the <RTSinstallDir> |
Installation directory for docker files |
Directory where REX Training Server docker-compose files will be installed. |
Default:
/<RTSinstallDir>/rts-docker
|
The disk requirements for the docker-compose files are minimal (< 1 MB). However, other parts of the install require greater disk space |
Should REX Training Server docker image be loaded? |
Load the Docker images so they are available on the local machine |
Otherwise, load them to a Docker registry shared by all machines. |
|
Port REX Training Server should listen on |
|
Default: 9080 |
This port and hostname will be required when installing the other servers. |
Directory to store the REX Training Server assets and wordclass files |
This directory will be mounted as a volume. |
Default: /<RTSinstallDir>/assets |
This directory holds files needed for training including static wordclass files.
The wordclass files can be manually installed later but must exist prior to starting RTS.
|
Directory to hold configuration information for the data access layer (DAL) connector and if the configuration file should be copied in now. If the file is copied at install time then you will be prompted for the host of the Rosette Adaptation Studio instance. |
This directory will be mounted as a volume. |
Default:
/<RTSinstallDir/config
|
The DAL connects to the mongo database on the Rosette Adaptation Studio component to access samples. If the port 27017 is NOT exposed on the RAS server then the mongodal_config.yaml file must be manually updated with the correct port number before starting the REX training server. |
Fully qualified host name where Rosette Adaptation Studio is installed |
|
The suggested value will be the host name of your current machine |
Cannot be empty, localhost or 127.0.0.1 |
Location of REX Training Server Logs |
|
Default: <RTSinstallDir>/logs |
|
REX Training Server workspaces root directory |
This directory will be mounted as a volume. |
Default: <RTSinstallDir>/workspaces |
|
REX Training Server Memory Management
The number of models that can be simultaneously trained depends on the size of the models and the memory available.
Once the model is written to disk, it consumes relatively little memory (~2 GB) for runtime requirements. The training and writing phases are much more memory intensive, each consuming approximately three times more memory. Typically, a model actively training will require approximately 10 GB of RAM.
Total memory consumption depends on the number of models being trained simultaneously, as well as the size of the models. The training server is a Java application and all operations use the JVM heap. To allow more simultaneous annotations on more projects, increase the RAM allocated to the JVM in Rosette Training Server.
To modify the JVM heap:
-
Create a file jvm.options in the /basis/rts/config directory. In this file, set the initial and maximum heap sizes. They should be set to the same value. The values must be less than the physical RAM installed on the machine.
# Set the initial and minimum heap size to 16GB
-Xms16G
# Set the maximum heap size to 16GB
-Xmx16G
-
Edit the file /basis/rts/rts-docker/docker-compose.yml and uncomment the line ${JVM_OPTIONS}:/config/jvm.options.
# Optionally override JVM settings here, default -Xms8G -Xmx16G
- ${JVM_OPTIONS}:/config/jvm.options
-
Edit the file /basis/rts/rts-docker/.env and set JVM_OPTIONS to point to the jvm.options file.
JVM_OPTIONS=/basis/rts/config/jvm.options
Run the REX Training Server (RTS)
-
Navigate to the installation directory containing the Docker Compose files. The default is:
/basis/rts/rts-docker
-
Run the service in detached mode.
docker-compose up -d
-
To check that the service has started, check the logs. This will display the last few lines of the logs from the service.
tail /basis/rts/logs/messages.log
-
The service can be tested by using a browser and navigating to http://<host>:<port> . This will list the endpoints to be used for health checks, API documentation, and metrics.
Example:
http://localhost:9080
Install Rosette Adaptation Studio (RAS)
You must have Docker and docker-compose installed.
Unzip the file ras-installation-<version>.zip.
-
From the directory ras-installation-<version>, run the installation script:
Start the installation:
./install-ras.sh
Note
SSL for the front end browser, the connection from the web client to the Rosette Adaptation Studio server, is enabled when RAS is installed. After installation of all three servers is complete, you can enable SSL between the servers.
To enable SSL for the front end browser, answer Yes to the question "Enable SSL for NGINX?".
Enabling front end SSL support is independent of enabling SSL between the servers.
The RAS installer will prompt you for the following information:
Table 8. RAS Installer Prompts
Prompt |
Purpose |
Options |
Notes |
Installation directory |
Directory for docker compose files and helper scripts. |
Default:
/basis/ras
|
The disk requirements for the docker-compose files are minimal (< 1 MB). However, other parts of the install require greater disk space |
Load the Rosette Adaptation Studio Docker image? |
Load the Docker images so they are available on the local machine |
Otherwise, load them to a Docker registry shared by all machines. |
|
Enable SSL for NGINX? |
To enable SSL for the connection from the web client to the RAS server |
|
In a closed network this may not be required however, passwords from the client to server are initially sent using clear-text so it is recommended to enable SSL. |
Target directory for SSL certificate files |
Directory that will contain the SSL certificate files |
Default: /basis/ras/certs |
For information on SSL certificate files:http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate |
Location of the certificate key file |
Where to find the certificate key file |
|
The certificate must be in PEM format |
Location of the certificate file |
Where to find the certificate file |
|
The certicate must be in PEM format |
HTTPS Port to expose |
|
Default: 443 |
|
HTTP port to expose |
|
Default: 80 |
|
Fully qualified host name where REX Training Server is installed |
Used by Rosette Adaptation Studio to perform training |
|
The REX Training Server does not need to be installed before Rosette Adaptation Studio, but you must know where it will be installed.
Cannot be empty, localhost or 127.0.0.1
|
Port REX Training Server is listening on |
|
Default: 9080 |
|
Fully qualified host name where Rosette Server is installed |
Used internally by Rosette Adaptation Studio |
|
Rosette Server does not need to be installed before Rosette Adaptation Studio but Server should be installed and started before starting the studio. Liveliness checks will be performed on startup.
Cannot be empty, localhost or 127.0.0.1
|
Port Rosette Server is listening on |
|
Default: 8181 |
|
Data directory for Rosette Adaptation Studio database |
Directory where the Adaptation Studio data will be stored. |
Default: /basis/ras/mongo_data_db |
This can be an NFS mount. |
Directory for database backups |
Directory where data should be stored when backed up from the RAS client. |
Default: /basis/ras/mongo_data_dump |
This can be an NFS mount. |
Port to expose for the database . |
This port will be used by RTS to connect to the RAS database instance to retrieve samples. |
Default: 27017 |
|
Run Rosette Adaptation Studio (RAS)
Rosette Server and REX Training Server must be running.
Navigate to the installation directory (default /basis/ras).
Execute the script ./scripts/start-standalone.sh. This script starts the services in detached mode and prints the logs. CTRL-C to disconnect from the logs.
Using a browser, navigate to http(s)://<host>:<port>/ to display the RAS landing page.
Rosette Adaptation Studio has scripts on each server to monitor the health and status of the system. Run them at startup to verify the system is ready to go.
The scripts are:
/basis/rs/rs-docker/rs-healthcheck.sh
/basis/rts/rts-docker/rts-healthcheck.sh
/basis/ras/scripts/ras-healthcheck.sh
where /basis is the default installation directory. If you've installed in a different directory, replace /basis with your install directory.
Each script verifies that the Docker containers have loaded and all components are running.
These commands are executed in the directory with the docker-compose files, e.g. /basis/rts/rts-docker.
Table 9. Basic Troubleshooting Commands
Command |
Purpose |
docker-compose config
|
Applies the variables from the .env file to the docker-compose.yml file so you can see how the containers will be started. |
docker-compose up
|
If you omit the -d, the command will dump the logs to the console. CTRL-C will bring the stack down. |
docker-compose up -p <name> up -d
|
The -p flag gives the container a project name. This is useful if you are running multiple instances in a single VM. For example, if you are upgrading versions and you want to run the side by side. docker ps will show the names. Example: 09_rex-training_server_1, 08_rex_training_server. |
docker-compose logs
|
Attaches to the logs |
printenv (from inside a container)
|
Allows yo to seen what ENV variables the container is using. |
Example 1. docker-compose config
docker-compose config
services:
rex-training-server:
environment:
AS_MONGO_DAL_CONNECTOR_CONFIG_DIR: /basis/rts/config
image: rex-training-server-tom-0.4.1:latest
ports:
- 9080:9080/tcp
volumes:
- /basis/0.8.final/rts/workspaces:/basis/rts/workspaces:rw
- /basis/0.8.final/rts/assets:/basis/rts:rw
- /basis/0.8.final/rts/config:/basis/rts/config:rw
- /basis/0.8.final/rts/logs:/logs:rw
- /basis/0.8.final/rts/rts-docker/jvm.options:/config/jvm.options:rw
version: '3.0'
Each component generates logs which may be useful if a problem occurs.
The location of the logs is determined during installation. The files in the default locations are:
/basis/rs/logs/wrapper.logs
/basis/rts/logs/messages.logs
/basis/ras/logs/error.log (Nginx error log)
/basis/ras/logs/access.log (Nginx access log)
/basis/ras/logs/server.log
/rest/metrics/health/worker
The metrics/health/worker endpoint provides basic healthy information indicating whether the application is up or down.
curl localhost:8181/rest/metrics/health/worker
{"healthy":true,"message":null,"error":null,"details":null,"timestamp":"2020-09-15T16:30:49.235Z"}
Ping the server to test that Rosette is running and you can connect to it.
-
bash:
curl http://localhost:8181/rest/v1/ping
-
Windows Powershell:
Invoke-WebRequest -Uri http://localhost:8181/rest/v1/ping
-
Windows Command Prompt:
start "" http://localhost:8181/rest/v1/ping
This should return:
{"message":"Rosette at your service","time":1467912784915}
This should return:
{"name":"Rosette","version":"1.7.2","buildNumber":"","buildTime":""}
RTS → RAS Troubleshooting/Monitoring
The /model/info endpoint provides the version of Rosette Training Server:
$ curl "http://localhost:9080/model/info"
{"version":"0.4.2"}
/metrics returns detailed information about the server in prometheus log file format.
/health returns the basic health of the system, including:
{"checks":
[
{"data":
{
"DIRECTORY":true,
"AS_MONGO":true},
"name":"DALHealthCheck",
"status":"UP"
},
{"data":
{
"wordclassesPathExists":true,
"wordclassesPopulated":true,
"workspaceRoot":"/basis/rts/workspaces",
"wordclasses":"/basis/rts/wordclasses",
"isWritable":true
},
"name":"WorkspaceWritableCheck","status":"UP"
}
],
"status":"UP"}
DAL Connection Test
The DAL connection test verifies the connection between RTS and the mongo instance on RAS by connecting to RTS directly. If RAS is not reachable, this test could hang for 1-2 minutes waiting for the connection.
curl -v -X POST "http://localhost:9081/model/rex/test-dal-connector" --header 'Content-Type: application/json' -d '{
"connectorId": "AS_MONGO",
"corpusType": "ANNOTATED_TRAIN_CORPUS",
"healthCheck" : "true",
"config": {
"projectId": "5f1470b6412ff29b8e4982f3",
"sampleIds": "5f158b0e412ff29b8e4983b8,5f158b0e412ff29b8e4983b5,5f158b0e412ff29b8e4983b7,5f158b0e412ff29b8e4983b6"
}
}'
If it is working, it will return:
{"tests":[{"connectorId":"AS_MONGO","message":"Health check passed","success":true}]}
This message indicates that the port is open and mongo is responding to requests.
The DAL connector is configured using the file /basis/rts/config/mongodal_config.yaml. The file contains 2 lines:
connectionString: 192.168.0.145:27017
maxSamples: 100000
The connectionString points to the mongo instance in RAS which is needed by the DAL connector in RTS. If the test is not successful, use cURL or a mongo client to test the connection to the mongo server without going through RTS.
curl 192.168.0.145:27017
When using cURL, a successful response will be a message from mongo similar to:
"It looks like you are trying to access MongoDB over HTTP on the native driver port."
This indicates the port is open and mongo is responding to requests.
RS → RTS Troubleshooting/Monitoring
Ping the server to test that RTS is running and you can connect to it.
curl localhost:9080/rest/v1/ping
Verify the settings in the .env file in the rs-docker directory
$ cat .env
returns:
# Connector information
RTS_HOSTNAME=rts.c.adst-rex-integration-280520.internal
RTS_PORT=9081
RTS_SOURCE_STRING=statistical
Verify that the hostname/port are correct and reachable from the host. In the Rosette Server container the following command should return 200.
curl $RTS_HOSTNAME:$RTS_PORT
Rosette Adaptation Studio
Rosette Adaptation Studio uses mongo as the backend database to store projects. The mongo client is required to perform a health check of the backend.
For performance, db.enable.FreeMonitoring() can be enabled and will provide an external API with statistics. This is not recommended for use in production.
The Manage Project page in the Studio will display the status of Rosette Server and REX Training Server.
Note
SSL for the front end browser, the connection from the web client to the Rosette Adaptation Studio server, is enabled when RAS is installed. After installation of all three servers is complete, you can enable SSL between the servers.
This section describes how to enable and disable SSL support between the servers.
Enabling front end SSL support is independent of enabling SSL between the servers.
To run the provided scripts you need a certificate and a key generated for each host that is running a component (RTS, RS, RAS). Each of the certificates must be signed by the root certificate authority (CA) that will be shared by all hosts running components. All certificates, keys, and root certificate authority files must be stored in PEM format.
RTS and RS are Java processes, so they require a keystore for the host and truststore for the root CA in a password protected Java Key Store (JKS) format. There is a script provided, generate-keystores.sh, in the component’s docker directory that will convert the certificate and key into a password protected JKS file. Additionally this script will generate a password protected truststore JKS file.
As long as the root CA is included, any truststore can be used. The truststore created by the provided script does not have to be used.
Enable and Disable SSL Support
Note
These instructions assume you have certificates for each of the servers. You will need the location and passwords for the keystore and the truststore for each server.
Rosette Adaptation Studio includes scripts to enable and disable SSL support between the servers. The scripts are found in the following directories:
/basis/rs/rs-docker
/basis/rts/rts-docker
/basis/ras/scripts
Enable SSL
Install and test the complete Rosette Adaptation Studio installation before enabling SSL. This will verify that everything is properly installed.
For each component (RS, RTS, RAS):
Warning
You must shut down the all three services before enabling SSL between them.
If you receive an error when restarting the services: "Cannot start service servicename: error while creating mount source path", the services were not shut down before enabling SSL.
To continue, restart Docker:
sudo systemctl restart docker
then restart the RS, RTS, and RAS services.
Once the installation has been verified, shut down the RS, RTS, and RAS services.
-
Execute the script from the directory containing scripts. For each product, you will be prompted for the location and passwords for the keystore and truststore.
./enable-rs-ssl.sh
./enable-rts-ssl.sh
./enable-ras-ssl.sh
Restart the RS, RTS, and RAS services.
Disable SSL
Shut down the services.
-
Execute the script from the directory containing the docker-compose files.
./disable-rs-ssl.sh
./disable-rts-ssl.sh
./disable-ras-ssl.sh
Restart the services.
Rosette Server SSL Scripts
Rosette Server is based on the Java-based OSGI with Jetty web server. To enable incoming SSL connections the server configuration must be updated to include the path to the truststore, keystore, and their respective passwords. Additionally, to enable outgoing SSL connections, e.g. RTS Decoder, custom code etc., the Java virtual machine settings must be updated to include the path to the truststore, keystore, and their respective passwords as well.
The enable-rs-ssl.sh script performs the following actions:
Prompts for the location and passwords of the truststore and keystore files.
-
Copies the truststore and keystore to the configuration directory so that the container has access to them.
Note
if you are re-enabling SSL and using truststores and keystores already present in the configuration directory you will see a warning message about the files being identical and not being copied. This message can safely be ignored.
Copies ssl-conf-template.conf to the configuration directory and renames it to ssl-conf.conf.
ssl-conf.conf will contain parameters to the JVM settings for RS and will hold the names and passwords of the truststore and keystore.
On startup, if the RS container detects the presence of the ssl-conf.conf file in the config directory and the environment variable ENABLE_SSL is set to 1 (set in the .env file), then the configuration file will be included in the wrapper.conf file for RS. The wrapper.conf file is responsible for setting up the runtime environment for RS.
Sets ENABLE_SSL to 1 in .env.
Adds/uncomments the keystore and truststore file names and passwords in the file org.apache.cxf.http.jetty-main.cfg in the config directory.
Sets the URL scheme to https in the file com.basistech.ws.cxf.cfg in the config directory.
Sets the scheme of the RTS_URL to https in the .env file.
The disable-rs-ssl.sh script reverses the actions above:
Note
This script does not delete the truststore or keystore from the configuration directory.
Sets ENABLE_SSL to 0 in .env.
Comments out the keystore and trustore file names and passwords in the file org.apache.cxf.http.jetty-main.cfg in the config directory.
Sets the URL scheme to http in the file com.basistech.ws.cxf.cfg in the config directory.
Sets the scheme of the RTS_URL to http in the .env file.
REX Training Server SSL Scripts
REX Training Server is based on the Java-based Open Liberty web container. To enable incoming and outgoing SSL the server configuration must be updated to include the path to the truststore, keystore, and their respective passwords. Additionally the mongodal_config.yaml file (in the config directory) must be updated to set the useSsl flag to true, enabling SSL between RTS and the mongo instance running on Rosette Adaptation Studio.
The enable-rts-ssl.sh script performs the following actions:
Prompts for the location and passwords of the truststore and keystore files.
-
Copies the truststore and keystore to the configuration directory so that the container has access to them.
Note
if you are re-enabling SSL and using truststores and keystores already present in the configuration directory you will see a warning message about the files being identical and not being copied. This message can safely be ignored.
Copies a server.template.xml file to the configuration directory and renames it to server.ssl.xml.
Replaces the values for the truststore and keystore file names and passwords in the server.ssl.xml file.
Updates the docker-compose.yml file and enables mounting the server.ssl.xml file as server.xml. This updates the server’s configuration.
Updates the .env file with the name of the SERVER_XML file (server.ssl.xml).
Enables ssl in the mongodal_config.yaml file.
The disable-rts-ssl.sh script reverses the actions above:
Note
This script does not delete the truststore or keystore from the configuration directory.
Updates the docker-compose.yml file and comments out the mounting of the SERVER_XML file.
Updates the .env file and comments out the SERVER_XML filename.
Deletes the server.ssl.xml file from the configuration directory.
Rosette Adaptation Studio SSL Scripts
Rosette Adaptation Studio is based on multiple technologies: python server, nginx reverse proxy, mongoDB server and React. As such, the configuration for RAS will be different from a Java process. All components internal to RAS use nginx for outgoing communication. Mongo is exposed to the host machine and can be protected by SSL. One of the primary differences between the RAS scripts and RS/RTS scripts is that the RAS scripts use PEM files rather than JKS files. Also, since RAS is made of one incoming connection (mongo) and two outgoing connections (RTS,RS) it is possible to selectively enable SSL for mongodb, RTS and RS.
The enable-ras-ssl.sh script performs the following actions:
Prompts for the locations of the certificate, key, and root CA PEM files.
Copies the PEM files to WEBSITE_HTTPS_CERT_DIR defined in the .env file.
-
If incoming mongodb traffic is to use SSL:
The certificate and key are concatenated into a single file for use by mongo and stored in the WEBSITE_HTTPS_CERT_DIR. This file is named <certificate name without file extension>-ras-cert-key.pem.
The file proxy-ssl-template.conf is copied and renamed proxy-mongo-ssl.conf. This file will contain nginx SSL settings for the certificate and ca certificate to use when internal components communicate with mongodb.
The file mongo-ssl-template-docker-compose.override.yml is copied and renamed docker-compose.override.yml. This file contains the alternative startup command for mongodb that includes parameters to only accept SSL traffic. Additionally it mounts the proxy-mongo-ssl.conf file so that the ras-proxy service can gain access to the SSL configuration file.
-
If the outgoing traffic to RS is to use SSL:
The file proxy-ssl-template.conf is copied and renamed proxy-rs-ssl.conf. This file will contain nginx SSL settings for the certificate and ca certificate to use when internal components communicate with RS.
The nginx-template.conf file is updated to uncomment the inclusion of the proxy-rs-ssl.conf file.
The docker-compose.yml file is updated to mount the proxy-rs-ssl.conf file so that nginx can load it.
The scheme for ROSETTE_URL is changed to https in .env
-
If the outgoing traffic to RTS is to use SSL:
The file proxy-ssl-template.conf is copied and renamed proxy-rts-ssl.conf. This file will contain nginx SSL settings for the certificate and ca certificate to use when internal components communicate with RS.
The nginx-template.conf file is updated to uncomment the inclusion of the proxy-rts-ssl.conf file.
The docker-compose.yml file is updated to mount the proxy-rts-ssl.conf file so that nginx can load it.
Changes the scheme of RTS_URL to https in the .env file.
The disable-ras-ssl.sh script reverses the actions above:
Note
This script does not delete the PEM files from the WEBSITE_HTTPS_CERT_DIR directory.
-
If SSL is to be disabled for incoming mongodb traffic:
Comments out the inclusion of the proxy-mongo-ssl.conf from the nginx-template.conf file.
Deletes the proxy-mongo-ssl.conf file.
Backs up then deletes the proxy-mongo-ssl.conf file.
-
If SSL is to be disabled for outgoing RS traffic:
Deletes the proxy-rs-ssl.conf file.
Comments out the inclusion of the proxy-rs-ssl.conf from the nginx-template.conf file.
Comments out the mount of the proxy-rs-ssl.conf from the docker-compose.yml file.
-
If SSl is to be disabled for outgoing RTS traffic:
Deletes the proxy-rts-ssl.conf file.
Comments out the inclusion of the proxy-rts-ssl.conf from the nginx-template.conf file.
Comments out the mount of the proxy-rts-ssl.conf from the docker-compose.yml file.
Changes the scheme of RTS_URL to http in the .env file.