Install Semaphore Studio

Note: Before installing, see Requirements for software prerequisites and required technical specifications for Semaphore.

Semaphore Studio software can be installed in any location on the file system. However, it is recommended that it be installed in appropriate sub-directories under the Program Files\Smartlogic directory (for ease of access).

Important: It is recommended that the components be installed in the order indicated in this section to ensure they are correctly configured.

To install Semaphore Studio:

1. On the target server, run the following installer program executable as an administrator:

   Copy

   Semaphore-<Version>-Studio-setup.exe
   

2. The License Agreement window appears. Make sure that you read and understand the license agreement. To continue with the installation, select the I accept the agreement; then, click Next.

3. In the Select Destination Location window, specify the location to install Semaphore Studio. Then click Next.

4. In the Java Home Configuration window, specify the JVM (jvm.dll) to be used by Semaphore. See Installing third-party software for supported Java versions.

5. In the Select Data Directory window, specify the directory in which the Studio server should store data files. Click Next to proceed.

6. The Studio server configuration window opens. Specify the port on which the Studio server listens. Note that the specified port must be free. Typically, the default value is fine. Click Next to proceed.

7. The Select Start Menu Folder window appears. Provide the location in the Start Menu to add Semaphore shortcuts. Click Next.

8. Click Install to begin the installation.

After the installation, the following services for Semaphore Studio will be available and started:

• Semaphore Studio <version> - Studio (ai)

• Semaphore Studio <version> - Studio (alerting)

• Semaphore Studio <version> - Studio (cm)

• Semaphore Studio <version> - Studio (da)

• Semaphore Studio <version> - Studio (kmm)

• Semaphore Studio <version> - Studio (rm)

• Semaphore Studio <version> - Studio (sm)

• Semaphore Studio <version> - Studio (studio)

Configure the Knowledge Model Management Max Memory (Java Heap)

If you have one or more large models in the Knowledge Model Management component, you may need to increase your maximum Java heap size.

For version 5.6: To adjust the maximum java heap size for the Knowledge Model Management component, run the following command from a command prompt as an administrator:

"c:/Program Files/Smartlogic/Studio/tomcat/bin/tomcat8w.exe"
//ES//SEM-KMM

After running the command, the Configure Tomcat UI dialog opens. On the Java tab, update the value in the Maximum memory pool field (the units are in megabytes (MB)). Click the Ok button to commit the changes.

For versions 5.8 and higher: To adjust the maximum java heap size for the Knowledge Model Management component, open the following file in a text editor:

<install_dir>\Smartlogic\Studio\kmm\bin\kmm.cmd file.

Navigate to the following entry:

-Xms128M -Xmx8G \^

For the -Xmx parameter, the numeral value represents the maximum number of Gigabytes memory to allocate for the JVM. Increase this number increase the numeral to the value you want. For example, to increase the memory to 10 gigabytes, you would have the following entry:

-Xms128M -Xmx10G \^

Important: Do not remove the ^ character at the end of the line. This character is the Windows command continuation marker.

Semaphore Studio Environment Configuration

After installing Studio, ensure the following environments variables are set correctly. These variables can be set by doing the following:

1. From the Windows start button, open the Control Panel for Windows.

2. Select the System icon in the control panel. Note that you might need to expose the System icon by changing the view or by using the search functionality.

3. Select the Advanced system settings. The System Properties window opens.

4. On the Advanced tab, click Environment Variables.

5. In the System variables pane, verify that the values for the environment variables described in "General Environment Settings" and "MarkLogic Environment Settings" are correctly configured. If required, add or edit the values for these environment variables according to following sections.

Important: If you change any of these variables, you will need to restart the Knowledge Model Management" service for the changes to be applied. See Starting and stopping services for more information.

General Environment Settings

The following general environment settings should be verified:

• SEMAPHORE_KEY_DIR (Optional): Specifies the directory to store encryption keys for generation of signed SPARQL End-point tokens. If this environment variable is not set the keys will be stored within the data directory specified during installation.

MarkLogic Environment Settings

Starting with Semaphore 5.6.1, you can configure the MarkLogic connection to use TLS/SSL for authentication. For earlier versions, only digest authentication is available. If you are using Marklogic as a triplestore (to store model information), then there are two methods you can use to configure it.

If the MarkLogic server is configured to use digest authentication (on the app services panel in the MarkLogic administration interface), then the following environment variables should be set:

• SEMAPHORE_DEFAULT_BACKEND: This variable should be set to MARKLOGIC.

• SEMAPHORE_MARKLOGIC_CONFIG: This variable should be set to:

  Copy

  <username>:<password>@marklogic://<marklogic_host>:<marklogic_application_port>/<database>
  

  For example:

  Copy

  mluser:mlpassword@marklogic://ml_server.company.com:8000/semaphore_database
  

If certificate authentication is set on the Marklogic server, then a trusted certificate must be generated for a suitably permissioned user. (If necessary, the Certifying Authority should be added to the set in the MarkLogic instance.) Once this is done, the environment variable SEMAPHORE_DEFAULT_BACKEND should be set to MARKLOGIC.

On the first run of KMM, the environment variable SEMAPHORE_MARKLOGIC_CONFIG should be set to

CERTIFICATE_FILE:certificate_password@marklogic://hostName:portNumber/dbName

MARKLOGIC_CLIENT_CERTIFICATE_FILE should be set to the path to the certificate on the Semaphore server. Note this file should be readable by the account under which the KMM Service is running.

(CERTIFICATE_FILE should be present exactly as here, the certificate_password is the password for the certificate, the hostName, portNumber and dbName are as above.

On the first run KMM will store the certificate password in its own trusted store, so for subsequent runs, this should be omitted, so the environment variable becomes:

CERTIFICATE_FILE@marklogic://hostName:portNumber/dbName

These optional variables are available:

• MARKLOGIC_CLIENT_VERIFY_HOSTNAME: Set this to FALSE if you do not want Semaphore to validate the URL of the Marklogic server.

• MARKLOGIC_CLIENT_TRUST_CA: set this to TRUE if you do not want Semaphore to validate the issuing authority for the Marklogic server's certificate.

These are both useful when you want to set up the environment with self-signed certificates.

For example, a first run of KMM the settings could take the following form:

SEMAPHORE_DEFAULT_BACKEND=MARKLOGIC
SEMAPHORE_MARKLOGIC_CONFIG=CERTIFICATE_FILE:password1@marklogic://172.18.0.20:8000/Semaphore
MARKLOGIC_CLIENT_CERTIFICATE_FILE=/opt/semaphore/cert.pfx MARKLOGIC_CLIENT_VERIFY_HOSTNAME=FALSE
MARKLOGIC_CLIENT_TRUST_CA=TRUE

For subsequent runs, the values would take the following form:

SEMAPHORE_DEFAULT_BACKEND=MARKLOGIC
SEMAPHORE_MARKLOGIC_CONFIG=CERTIFICATE_FILE@marklogic://172.18.0.20:8000/Semaphore
MARKLOGIC_CLIENT_CERTIFICATE_FILE=/opt/semaphore/cert.pfx
MARKLOGIC_CLIENT_VERIFY_HOSTNAME=FALSE
MARKLOGIC_CLIENT_TRUST_CA=TRUE

Configuration of Studio Users

After installing Semaphore Studio, you need to configure user access using either Quarkus form-based authentication or external security providers (e.g. LDAP).

For Semaphore 5.6 and later, Studio comes with Quarkus (For Semaphore 4, Quarkus was installed separately). As a result, the authentication and authorization methods supported by Quarkus are available for Semaphore Studio.

Refer to Access level roles in the Semaphore Knowledge Model Management (KMM) Administration for information on the type of roles that you should assign users.

Note: All Knowledge Model Management permissions and security configuration are case sensitive.

Configure form-based authentication (static list)

The simplest of the supported authentication mechanisms to implement is Quarkus form-based authentication. To configure form-based authentication, create entries in the following file as described in this section:

<studio_installation_directory>\\studio\\conf\\studio-authentication.properties

Important: Best security practices dictate that user name and password authentication is not used in a production environment.

To enable form authentication and disable other methods, add the following entries to the file:

studio.auth.form.enabled=true
studio.auth.disabled=false
quarkus.oidc.enabled=false

For each user, create a pair of the following entries in the file:

quarkus.security.users.embedded.users.<user_name>=<Password>
quarkus.security.users.embedded.roles.<user_name>=<role_1>[,<role_2>,...]

The first entry defines the user and their password. The second lists the roles assigned to them. Therefore, a pair of entries to create a global God user with the password admin would take the following form:

quarkus.security.users.embedded.users.God=admin
quarkus.security.users.embedded.roles.God=SemaphoreSuperAdministrators,SemaphoreAdministrators,SemaphoreRoots

Entries for a user would with fewer permissions would take the following form:

quarkus.security.users.embedded.users.User=password1
quarkus.security.users.embedded.roles.User=SemaphoreUsers

User name values that contain period (.) characters (such as with an email address) must be wrapped in quotation marks, such as:

quarkus.security.users.embedded.users.\"support@marklogic.com\"=password1

Once this file has been updated, restart the Studio service for the changes to take effect.

If you are upgrading from an earlier version of Studio, the users present in the file <install_dir>/studio/conf/tomcat-users.xml should be recreated in file described in this section.

Note that this method of authentication is not recommended for use in production environments. Rather, we would recommend using an external authentication/authorization system.

External security providers

To use external authentication providers, refer to Form-basedauthentication for form based or OAuth 2 OpenID Authentication for in the Semaphore Knowledge Model Management (KMM) Administration.

Initial Studio Configuration

Before you can use Studio, you will need to upload the relevant licence into the application. This can be done as follows:

1. Download the environment-specific licence from the Progress Semaphore Customer Portal in Software Downloads. These files are generally named <environment_name>Env-Licence-<expiry_date>.txt.

   You may have multiple environments for which licences are required, so be sure to install the correct licence on the correct systems.

2. Verify that the Semaphore Studio service is running.

3. In a browser, open the Studio web app by navigating to http://<hostname>:<port>/ (e.g. http://localhost:5080/)

4. On the Services tab, select License.

5. Click on + Upload a new license button and search for the Semaphore environment license file you downloaded above. If this installation of Studio is managing multiple environments, be sure to upload each of the relevant licences.

   

6. After a successful upload, the details of your Semaphore licence are displayed:

   

Back-up Semaphore Studio

Semaphore Super Administrators are able to back up the Studio configuration using the Backup functionality. Note that the back-up is for the configuration of Studio, not the contents of any model that is stored in the Knowledge Model Management component.

A backup can also be generated using a cURL call. For example:

curl -v http://localhost:5080/api/backup \--header
x-api-key:\<access_token\> \--output StudioBackup.zip

Where <access_token> is a token generated from the Studio UI. You can generate a token by selecting Services > Generate Access Token.

Next steps

Install the Facts Framework