Install Semaphore Studio

Save PDF

Last Updated: May 13, 2026
6 minute read

Semaphore
Documentation

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

To install Semaphore Studio, execute the following command on the target server:

yum install Semaphore-Studio-\<Version\>.noarch.rpm

Note: This installation process will install Semaphore Studio, KMM, and DA onto the server.

The installer creates the services semaphore-studio, semaphore-kmm and semaphore-da. Each of these services can be controlled individually with the systemctl utility. An overriding service, semaphore, which can be used to start or stop all three of these services, is also created.

Studio Environment Configuration

Before starting the services, ensure the environments variables described in this section are set correctly in the /etc/sysconfig/semaphore configuration file. Note that if the Knowledge Model Management service (semaphore-kmm) is already running (all of these settings are used by this Studio component only), then, after changing these values, the service will need to be restarted.

KMM Memory allocation

Starting in Semaphore 5.8, you will need to update the memory allocated to Knowledge Model Management. To configure the memory allocation, navigate and open the following file: /opt/semaphore/kmm/bin/start.sh. Locate the following line in the file:

-Xms2G -Xmx8G \

Replace the 8 with the maximum number of gigabytes of memory that should be allocated to the Java heap. (Ensure that the \ character remains, as it is the linux command continuation marker.)

General Environment Settings

The following general settings should be verified:

SEMAPHORE_WORKBENCH_HOME (Optional): Specifies the directory in which the application data, including models, are stored. For example:
```
SEMAPHORE_WORKBENCH_HOME=/home/SemaphoreWorkbenchHome/
```

Notes:

The specified directory should be readable/writeable by the semaphore user.
If this variable is not set, all the models created with the application will be physically present in the web application directory structure itself, meaning that, upon upgrading, any models will be removed. By setting SEMAPHORE_WORKBENCH_HOME appropriately, the models will be stored in a different location, and therefore, not removed during an upgrade.
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 are stored in the SEMAPHORE_WORKBENCH_HOME directory.

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:

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

For example:

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://<host_name>:<port_number>/<db_name>

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.

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

The following are optional variables:

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.

Both variables are 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 on

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

Configure Semaphore 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. As a result, the authentication and authorization methods supported by Quarkus are available for Semaphore Studio.

Refer to Access level security roles for information on the type of roles that you should assign users.

Note: All Knowledge Model Management permissions and security configurations 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:

/opt/semaphore/studio/conf/studio-authentication.properties

In addition, you will need to verify the following settings:

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
quarkus.security.users.embedded.roles.\"support@marklogic.com\"=SemaphoreUsers

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

systemctl restart semaphore-studio

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-based authentication or OAuth 2 OpenID Authentication in the Semaphore Knowledge Model Management (KMM) Administration.

Initial Semaphore Studio configuration

Before you can use Studio, upload the relevant licence into the application:

Download the environment-specific licence from the Progress Semaphore Customer Portal in [Software Downloads]{.underline}. 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.
Verify that the Semaphore Studio service is running.
In a browser, open the Studio web app by navigating to http://<hostname>:<port>/ (e.g. http://localhost:5080/).
On the Services tab, select License.
Click on + Upload a new license button and search for the Semaphore environment licence file you downloaded above. If this installation of Studio is managing multiple environments, be sure to upload each of the relevant licences.

After a successful upload, the details of your Semaphore license 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. If you need restore your installation from the backup, refer to Backing up and restoring Semaphore in the Semaphore for Linux Administration for details.

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

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

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

Install Semaphore on Linux