Powered by Zoomin Software. For more details please contactZoomin

Install Semaphore 5.13 on Linux

NO TITLE FOUND

  • Last Updated: November 20, 2026
  • 7 minute read
    • Semaphore
    • Version 5.13
    • Documentation

This video introduces Progress Semaphore concepts, features, and workflows through clear, practical explanations. It helps users understand how Semaphore supports semantic modeling, search, and AI‑driven use cases across the enterprise.

Note: To see the video description, resources, and list of links on YouTube, hover over the video player and click the video title at the top.

The video refers to "Concepts Server", the former name of the Knowledge Service.

The MarkLogic database

Knowledge Service requires an installed, initialized MarkLogic Server. On each startup, it creates or updates a dedicated REST application, its content, schema, and modules databases, forests, and security configuration. You do not need to deploy these resources separately.

Edit <install_dir>/conf/marklogic.properties before starting the service. The following parameters control the connection and application resources:

Parameter Description Default
marklogic.host Host running MarkLogic Server Set for your deployment
marklogic.port Dedicated REST data server port 8040
marklogic.app-services.port App-Services port for administrative database access 8000
marklogic.monitoring.port Manage API port for configuration and database status 8002
marklogic.admin.user User with privileges to provision databases, forests, application servers, and security resources Set for digest or basic authentication
marklogic.admin.password Password for this user Set for digest or basic authentication
marklogic.rest-server-name Dedicated REST application server name knowledge-service-rest
marklogic.group MarkLogic group in which the REST application server is created. The group must exist and marklogic.host must belong to it Default
marklogic.database Content database for published models KnowledgeService
marklogic.schema-database Database for schema and Template-Driven Extraction (TDE) documents KnowledgeService-schemas
marklogic.modules-database Database for application modules KnowledgeService-modules
marklogic.client.connectionType Connect directly (direct) or through a gateway such as a load balancer (gateway) direct

For example, a connection using the default ports has the following settings:

marklogic.host=marklogic.example.com
marklogic.port=8040
marklogic.app-services.port=8000
marklogic.monitoring.port=8002

The REST data port must be free on MarkLogic and reachable from the Knowledge Service. Do not use the App-Services port as the REST data port. These ports are separate from the Knowledge Service's own HTTP port, which defaults to 5092. For separate deployments on the same MarkLogic cluster, use distinct REST server names, database names, and REST ports.

Important: If replacing the Concepts Server, review Upgrading from Concepts Server before applying fresh-install defaults. The legacy marklogic.forest and marklogic.schema-database-forest properties are no longer supported.

High availability

Use the following properties to configure forests and replicas on an existing MarkLogic cluster:

Parameter Description Default
marklogic.forests-per-host Number of primary forests per host for the content database 1
marklogic.forest-replicas Number of replicas for each forest 0

For example, on a multi-host cluster, the following creates one content forest per host and replicas on other hosts:

marklogic.forests-per-host=1
marklogic.forest-replicas=1

Keep marklogic.forest-replicas=0 for a single-host installation. Replica configuration also applies to schema and modules databases, as well as the shared MarkLogic Security database. Before changing this parameter, review the cluster configuration and the requirements of other applications that use the shared Security database.

Administrative credentials

Provisioning credentials are required on every startup. Typically, model queries and publishing use automatically created content-reader and content-writer users with passwords generated at startup. Their names are knowledge-service-content-reader-<server> and knowledge-service-content-writer-<server>, where <server> is the configured REST server name. These accounts are for internal use, not external client access.

Keep the configured administrative credentials available for provisioning, upgrades, and database management/status operations. Do not remove their provisioning privileges after the first startup.

Reduced-permission provisioning account

In Semaphore 5.13, the user configured by marklogic.admin.user does not need the MarkLogic admin or security role. Have a MarkLogic administrator assign it manage-admin, rest-admin, tde-admin, and tde-view, plus a custom provisioning role with the following execute privileges:

  • create-privilege, get-privilege, create-data-role, create-data-user
  • create-amp, get-amp, grant-my-roles, grant-my-privileges
  • xdmp:eval-in, xdmp:invoke, xdmp:invoke-in, xdbc:eval-in
  • admin-module-write, xdmp:write-cluster-config-file, user-exists

Only when using a non-admin provisioning account, a MarkLogic administrator must create these two custom privileges and grant them to the provisioning role before the first startup. If the provisioning account has the MarkLogic admin role, Knowledge Service creates all required resources automatically; no manual creation of roles or privileges is needed. Replace <server> with marklogic.rest-server-name (default: knowledge-service-rest).

Privilege name Kind Action
knowledge-service-execute-<server> execute http://semaphore.com/xdmp/privileges/knowledge-service-execute-<server>
knowledge-service-tde-uri-<server> uri /conceptsWithEmbeddingsTemplate/<server>/

Use this account for provisioning, including upgrades and subsequent startups. Knowledge Service creates its own application roles and technical users; do not create those manually. Normal model queries and publishing use the technical users described above. When upgrading from Concepts Server, review the account's roles and privileges before starting Knowledge Service; the earlier role set is not sufficient for the new provisioning process.

Secure credential storage

To avoid storing credentials in plain text configuration, set MARKLOGIC_ADMIN_USER_FILE and MARKLOGIC_ADMIN_PASSWORD_FILE to files containing the respective values. Each file must contain only the credential value and be readable only by the service account and authorized administrators. You can use either file setting independently. Administrative credentials can also be supplied through environment configuration.

Alternatively, store the password in an encrypted keystore. Add the following to marklogic.properties:

marklogic.admin.password=${marklogic-password}
quarkus.file.vault-config-source.keystore-path=conf/dbpasswords.p12
quarkus.file.vault-config-source.keystore-secret=<keystore_password>

From the installation directory, run:

keytool -importpass -alias marklogic-password -keystore conf/dbpasswords.p12 -storepass <keystore_password> -storetype PKCS12

Restrict access to the keystore and its configuration to the service account and authorized administrators.

Document permissions

Documents written to the content database by Knowledge Service receive read permission for knowledge-service-reader-<server> and update permission for knowledge-service-writer-<server>. To grant additional access to an existing MarkLogic role, add role/capability pairs to marklogic.properties. For example:

marklogic.document.permissions=reporting-reader,read

These permissions supplement the built-in defaults. During a detected application upgrade, Knowledge Service replaces the permissions on existing documents in the configured content database with the built-in defaults and these additional permissions. Include any customer permissions that must be retained. The setting applies to newly written documents. Changing it without an application upgrade does not update all existing documents.

MarkLogic document permissions do not replace Studio adoption and publishing permissions, or the X-Token used to publish from outside Studio.

TLS and authentication

The Knowledge Service supports digest (the default), basic, and certificate authentication for administrative MarkLogic connections. Basic authentication uses the same username/password settings as digest; use HTTPS to protect those credentials. Certificate authentication requires HTTPS and a client certificate instead of an administrative username/password.

The following parameters configure authentication and TLS:

Parameter Description Default
marklogic.protocol Connection protocol: http or https http
marklogic.client.authType Administrative authentication: digest, basic, or certificate digest
marklogic.sslCertificateTemplate Existing MarkLogic certificate template to apply to the REST data server; required for HTTPS Set for HTTPS
marklogic.client.sslProtocol TLS protocol TLSv1.2
marklogic.client.sslHostnameVerifier Server hostname verification strict
marklogic.client.ssl.truststore.path Truststore containing the server's trusted certificate authority Set for your truststore
marklogic.client.ssl.truststore.password Truststore password Set for your truststore
marklogic.client.ssl.truststore.type Truststore type, for example PKCS12 Set for your truststore
marklogic.client.ssl.keystore.path Client certificate and private-key keystore Set for certificate authentication
marklogic.client.ssl.keystore.password Client keystore password Set for certificate authentication
marklogic.client.ssl.keystore.type Client keystore type, for example PKCS12 Set for certificate authentication
marklogic.client.certificate.ca-id MarkLogic certificate authority ID for the client certificate Set for certificate authentication

Configure TLS and the chosen authentication method on MarkLogic's administrative endpoints before starting Knowledge Service, including App-Services and Manage. For certificate authentication, configure the trusted client certificate authority and the corresponding MarkLogic user. See Configuring SSL on App Servers and Certificate-Based Authentication in Secure MarkLogic Server.

For example, add the following to the connection and credential settings to use HTTPS with digest authentication:

marklogic.protocol=https
marklogic.sslCertificateTemplate=<certificate_template_name>
marklogic.client.authType=digest
marklogic.client.ssl.truststore.path=conf/truststore.p12
marklogic.client.ssl.truststore.password=<truststore_password>
marklogic.client.ssl.truststore.type=PKCS12

For certificate authentication, replace the authType setting and add the following to the HTTPS configuration. The marklogic.admin.user and marklogic.admin.password settings are not required:

marklogic.client.authType=certificate
marklogic.client.ssl.keystore.path=conf/client-cert.p12
marklogic.client.ssl.keystore.password=<client_keystore_password>
marklogic.client.ssl.keystore.type=PKCS12
marklogic.client.certificate.ca-id=<certificate_authority_id>

Keep strict hostname verification and ensure the service account can read the certificate files. On Windows, use double backslashes in properties-file paths, for example C:\\semaphore\\KnowledgeService\\conf\\truststore.p12.

Note: Content-reader and content-writer users always use digest authentication on the dedicated REST server. After basic or certificate provisioning, Knowledge Service switches that server to digest for normal content access. TLS still applies when configured. These settings secure connections to MarkLogic, not the HTTP listner for the Knowledge Service.

Embedding vector calculation

Vector embedding calculation for concepts has been available since Semaphore 5.10.2. In Semaphore 5.13, vector embeddings can be calculated when concepts are pushed via the Knowledge Service into a MarkLogic database. This allows you to present a body of text to the semanticSearch method of the server to return concepts semantically similar to the presented text.

Note: Embedding calculation and semantic search require MarkLogic 12 or higher.

You can enable this functionality by configuring the <install_dir>/conf/knowledge-service.properties file. Note that if you have defined an external model for your Knowledge Service, embeddings are calculated whenever you publish a model to Knowledge Service. If you do not want this behavior for a particular model, you can disable it in the publisher configuration file by adding the calculateEmbeddings property with a value of false to the output processor. For example:

<bean parent="environmentKnowledgeServiceWriter">
	<property name="calculateEmbeddings" value="false" />
</bean>

Note: The previous environmentConceptsWriter name is also supported.

If it is possible to specify an internal or an external calculator, you can set the calculator using the knowledgeService.embedding.type parameter. If this parameter is not present (the parameter is commented out by default), embeddings are not calculated.

External

When using the external method, the external calculator must be specified. The following options for external calculators are currently supported:

  • custom
  • azureOpenAi
  • ollama
  • mistral
  • googleVertexAi

To configure the selected provider, uncomment the corresponding properties in the configuration file and specify the required values.

If you are using an embedding model that is accessed via http (e.g. if you are using a local test model), rather than https, set the knowledgeService.embedding.external.allowHttp parameter to true.

The following is an example for an Azure OpenAI Custom deployment:

knowledgeService.embedding.type=external
knowledgeService.embedding.external.provider=azureOpenAi
quarkus.rest-client.embeddingExternalAzureOpenAi.url=https://your-prefix.openai.azure.com/openai/deployments/text-embedding-3-large
knowledgeService.embedding.external.azureOpenAi.apiVersion=2024-10-21
knowledgeService.embedding.external.azureOpenAi.apiKey=your-api-key

Internal

When using the internal method, whereby the embeddings are calculated within the Knowledge Service, you must download a model (in the form of a .onnx file) and a tokenizer configuration file (as a .json file). A number of models and configuration files are available on the HuggingFace site. From the site, select a model (e.g. nomic-ai/nomic-embed-text-v1.5) and download the corresponding .onnx and tokenizer.json files. Next, place them on the server for the Knowledge Service and specify the location of the files by adding the following parameters to the knowledge-service.properties file:

knowledgeService.embedding.type=internal
knowledgeService.embedding.internal.modelPath=/opt/semaphore/knowledgeService/model.onnx
knowledgeService.embedding.internal.tokenizerPath=/opt/semaphore/knowledgeService/tokenizer.json

Notes:

  • Internal embedding calculation now supports CPU only, which might not be optimal for a production environment. We recommend using external embedding calculation for production systems.
  • On Windows, the path to model and tokenizer requires double backslashes. For example, C:\\semaphore\\knowledgeService\\model.onnx.
Alert