Run individual Progress-supplied Docker images

This topic describes how to start each Progress-supplied Semaphore container using the docker run command. For multi-service deployments, see Run Progress-supplied Docker images with Docker Compose.

Before you start: Ensure that any host directories used as mount points exist and are owned by UID 185. See Container user and file permissions.

Note: The Classification Server image is the only component image that does not pin a UID. To find the UID before setting ownership for host directories, run docker run --rm --entrypoint "" <image-name> sh -c 'id -u sem_cs'

Note: Semaphore Studio is the only component that end users interact with directly. All other Semaphore components described in this topic are internal services that must not be exposed to public networks. The docker run examples in this topic attach each internal service to a shared Docker network (semaphore-network) and do not publish their ports on the host. Semaphore Studio and the other Semaphore tools reach them by container name on that network. See Networking Semaphore with Docker for how to create the shared network. The Classification and Language Service (CS), the Semantic Enhancement Server (SES), the Concepts Server and the Text Mining Side Panel are also called from Semaphore Studio, but may additionally be reached by external clients, publishers or end-user tools. You should publish their ports on the host only when external access is required.

Classification and Language Service

The Classification Server is distributed in four image variants. The semaphore-classification image shown here uses the built-in Bitext NLP engine and has the smallest footprint. For Babel Street Rosette NLP or bundled language packs, see the variant table in Using Progress-supplied Docker images.

The Classification Server exposes its API and the CAT tool web interface on port 5058.

To start the Classification and Language Service container, run the following:

docker run -d \
  --name semaphore-cs \
  --restart unless-stopped \
  --read-only \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --tmpfs /var/opt/semaphore/CS/tmp:uid=185,gid=0 \
  --network semaphore-network \
  -p 5058:5058 \
  -v /path/to/semaphore.licence:/opt/semaphore/licence:ro \
  -v /srv/semaphore/cs/rulebases:/var/opt/semaphore/CS/rulebases \
  -v /srv/semaphore/cs/logs:/var/opt/semaphore/CS/logs \
  -v /srv/semaphore/cs/stats:/var/opt/semaphore/CS/stats \
  -v /srv/semaphore/cs/certificates:/var/opt/semaphore/CS/certificates \
  --tmpfs /var/opt/semaphore/CS/tmp \
  --tmpfs /var/opt/semaphore/run \
  --tmpfs /opt/semaphore/CS/failures \
  semaphore-classification:5.10.4

Note: In the example, the failures mount uses tmpfs. Substitute a bind-mount if you need to preserve failed request dumps across container restarts.

CS container directories

CS environment variables

All CS environment variables are optional. CS starts successfully without any of them.

You should use filesystem auto-detection instead of these variables when the language pack directory contains a current symlink and current/list entries (created by the Linux RPM installer).

Set SEMAPHORE_LANGUAGE_PACK_VERSION to None to disable Rosette language packs and use the built-in Bitext NLP engine for available languages.

Set SEMAPHORE_LANGUAGES_IN_PACK to override the list of available languages. This is useful for excluding languages not used in your deployment or for restricting languages available via the built-in Bitext NLP engine.

Verify CS

curl --silent --location 'http://<host>:5058' --form 'operation=version'

A healthy server returns an XML response containing a <version> element. The CAT tool web interface is also accessible at http://<host>:5058/cat/index.html.

If CS is only used by Semaphore Studio and other containers on semaphore-network, omit the -p flag so that the port is not exposed on the host.

Semantic Enhancement Server

The semaphore-ses image exposes the SES on port 8983. A licence directory must be made available to the container at /opt/semaphore/licence.

To start the Semantic Enhancement Server container, execute the following:

docker run -d \
  --name semaphore-ses \
  --restart unless-stopped \
  --read-only \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --tmpfs /var/opt/semaphore/SES/temp:uid=185,gid=0 \
  --network semaphore-network \
  -p 8983:8983 \
  -e SOLR_JAVA_MEM="-Xms1g -Xmx4g" \
  -e SEMAPHORE_LICENCE_DIR=/opt/semaphore/licence \
  -v /mnt/ses-licence:/opt/semaphore/licence:ro \
  -v /mnt/ses-config:/etc/opt/semaphore/SES \
  -v /mnt/ses-data:/var/opt/semaphore/SES/data \
  -v /mnt/ses-logs:/var/opt/semaphore/SES/logs \
  semaphore-ses:5.10.4

SES-specific environment variables:

The licence directory on the host must contain the Semaphore licence file and be readable by UID 185.

Verify SES

To confirm the service is running, browse to http://<host>:8983/ses. If SES is only reached by Semaphore Studio and other containers on semaphore-network, omit the -p flag so that the port is not exposed on the host.

Warning: SES indexes created by versions older than 5.10.4 are not compatible with SES 5.10.4. If you are upgrading from an earlier release, delete or archive the existing indexes at /var/opt/semaphore/SES/data/Indexes and the Zookeeper data at /var/opt/semaphore/SES/data/Zookeeper (or the corresponding host directories, for example /mnt/ses-data/Indexes and /mnt/ses-data/Zookeeper) and republish your models after starting the new container.

Semaphore Studio

The semaphore-studio image exposes Semaphore Studio on port 5080.

Prerequisites: Before starting the container, create all required host directories. The tdb and licenses subdirectories are mandatory --- the application will fail to start if they do not exist or are not writable by UID 185:

sudo mkdir -p /mnt/studio-config /mnt/studio-data/tdb /mnt/studio-data/licenses /mnt/studio-logs
sudo chown -R 185:0 /mnt/studio-config /mnt/studio-data /mnt/studio-logs

Important: The licenses directory must be mounted read-write (do not use :ro). See Licence directory requirements for details.

To start the Semaphore Studio container, execute the following:

docker run -d \
  --name semaphore-studio \
  --restart unless-stopped \
  --read-only \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --tmpfs /var/opt/semaphore/studio/temp:uid=185,gid=0 \
  --network semaphore-network \
  -p 5080:5080 \
  -e STUDIO_LOG_LEVEL=WARN \
  -e STUDIO_KMM_URL=http://semaphore-kmm:5082/ \
  -e STUDIO_DA_URL=http://semaphore-da:5081/ \
  -e STUDIO_RM_URL=http://semaphore-rm:5083/ \
  -e STUDIO_SM_URL=http://semaphore-sm:5084/ \
  -e STUDIO_CM_URL=http://semaphore-cm:5085/ \
  -e STUDIO_AI_URL=http://semaphore-ai:5087/ \
  -v /mnt/studio-config:/etc/opt/semaphore/studio \
  -v /mnt/studio-data/tdb:/var/opt/semaphore/studio/data/tdb \
  -v /mnt/studio-data/licenses:/var/opt/semaphore/studio/data/licenses \
  -v /mnt/studio-logs:/var/opt/semaphore/studio/logs \
  semaphore-studio:5.10.4

Studio container directories:

Studio environment variables for internal service URLs:

These variables are required whenever Studio runs in a separate container from the backend services. When all services run on the same host the defaults (http://localhost:<port>/) work without configuration.

Semaphore Studio requires network access to the CS, SES and any other backend services. Attach Semaphore Studio and every backing service to the same Docker network (semaphore-network in these examples) and refer to each service by its container name --- for example, http://semaphore-cs:5058, http://semaphore-ses:8983/ses and http://semaphore-rm:5083. See Networking Semaphore with Docker.

SES, CS, and Concepts Server URL configuration

The Classification and Language Service (CS), the Semantic Enhancement Server (SES), and the Concepts Server may each need to be reached from two different contexts:

• Inter-Service URL — used by Studio and other containers to reach CS, SES, or the Concepts Server over the Docker network. Use the container name as the host, for example http://semaphore-cs:5058, http://semaphore-ses:8983/ses, or http://semaphore-concepts:5092.

• Client URL — used by browsers, publishers, or external tools that cannot reach the Docker network directly. This is typically the host address with a published port, for example http://localhost:5058, http://myhost.example.com:8983/ses, or http://myhost.example.com:5092.

When configuring Studio or external tools, ensure you use the correct URL for the context. Studio uses the Inter-Service URL (container name). Any external tool or browser that needs direct access must use the Client URL.

Important: Before starting Semaphore Studio, ensure the following internal services are running and healthy: semaphore-kmm, semaphore-da, semaphore-sm, semaphore-rm, semaphore-cm, semaphore-alerting, and semaphore-ai. Studio will not function correctly without these services. Verify each is healthy by checking its health endpoint (for example, http://semaphore-rm:5083/application/info) before launching Studio.

Verify Studio

To confirm the service is running, browse to http://<host>:5080.

Concepts Server

The semaphore-concepts image exposes the Concepts Server on port 5092. The Concepts Server is called from Semaphore Studio, but may also be reached directly by external clients. You should publish its port on the host only when external access is required. A running MarkLogic Server is required.

To start the Concepts Server container, execute the following:

docker run -d \
  --name semaphore-concepts \
  --restart unless-stopped \
  --read-only \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --tmpfs /var/opt/semaphore/concepts/temp:uid=185,gid=0 \
  --network semaphore-network \
  -p 5092:5092 \
  -e MARKLOGIC_HOST=marklogic.example.com \
  -e MARKLOGIC_PORT=8000 \
  -e MARKLOGIC_MONITORING_PORT=8002 \
  -e MARKLOGIC_ADMIN_USER=admin \
  -e MARKLOGIC_ADMIN_PASSWORD=<password> \
  -e CONCEPTS_LOG_LEVEL=WARN \
  -v /mnt/concepts-config:/etc/opt/semaphore/concepts \
  semaphore-concepts:5.10.4

Required environment variables:

The admin credentials are used only at first startup to provision the MarkLogic security model. At runtime, the application uses automatically-created technical users.

Important: Storing credentials in plain text environment variables is not recommended for production use. Use file-based credentials by setting MARKLOGIC_ADMIN_USER_FILE and MARKLOGIC_ADMIN_PASSWORD_FILE to the path of a file containing the value, or use Docker secrets when running in Docker Swarm.

Knowledge Model Management (KMM)

The semaphore-kmm image provides the Knowledge Model Management plugin used by Semaphore Studio. KMM is an internal service called from Semaphore Studio. Do not publish its port on the host.

KMM stores its database under /var/opt/semaphore/kmm. Mount a host directory or named volume to that path so that knowledge model data is preserved across container restarts. KMM also requires access to the Semaphore licence directory. Mount the same licence directory used by Studio at /var/opt/semaphore/studio/data/licenses:ro.

To start the KMM container, execute the following:

docker run -d \
  --name semaphore-kmm \
  --restart unless-stopped \
  --read-only \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --tmpfs /var/opt/semaphore/kmm/temp:uid=185,gid=0 \
  --network semaphore-network \
  -e SEMAPHORE_WORKBENCH_LOG_LEVEL=WARN \
  -v /mnt/kmm-config:/etc/opt/semaphore/kmm \
  -v /mnt/kmm-data:/var/opt/semaphore/kmm \
  -v /mnt/studio-data/licenses:/var/opt/semaphore/studio/data/licenses:ro \
  semaphore-kmm:5.10.4

Rulebase Manager (RM)

RM is an internal service called from Semaphore Studio. Do not publish its port on the host.

To start the Rulebase Manager container, execute the following:

docker run -d \
  --name semaphore-rm \
  --restart unless-stopped \
  --read-only \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --tmpfs /var/opt/semaphore/rm/temp:uid=185,gid=0 \
  --network semaphore-network \
  -e RM_LOG_LEVEL=WARN \
  semaphore-rm:5.10.4

The RM container exposes its API on port 5083 inside semaphore-network. Other containers on the same network reach it at http://semaphore-rm:5083. The health endpoint is http://semaphore-rm:5083/application/info.

SES Manager (SM)

SM is an internal service called from Semaphore Studio. Do not publish its port on the host.

To start the SES Manager container, execute the following:

docker run -d \
  --name semaphore-sm \
  --restart unless-stopped \
  --read-only \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --tmpfs /var/opt/semaphore/sm/temp:uid=185,gid=0 \
  --network semaphore-network \
  -e SM_LOG_LEVEL=WARN \
  semaphore-sm:5.10.4

Concepts Manager (CM)

CM is an internal service called from Semaphore Studio. Do not publish its port on the host.

To start the Concepts Manager container, execute the following:

docker run -d \
  --name semaphore-cm \
  --restart unless-stopped \
  --read-only \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --tmpfs /var/opt/semaphore/cm/temp:uid=185,gid=0 \
  --network semaphore-network \
  -e CM_LOG_LEVEL=WARN \
  semaphore-cm:5.10.4

Document Analyzer (DA)

DA is an internal service called from Semaphore Studio. Do not publish its port on the host.

To start the Document Analyzer container, execute the following:

docker run -d \
  --name semaphore-da \
  --restart unless-stopped \
  --read-only \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --tmpfs /var/opt/semaphore/da/temp:uid=185,gid=0 \
  --network semaphore-network \
  -e DA_LOG_LEVEL=WARN \
  -v /mnt/da-config:/etc/opt/semaphore/da \
  -v /mnt/da-logs:/var/opt/semaphore/da/logs \
  semaphore-da:5.10.4

The DA container reads da.properties and TextAnalytics_Rules.xml from the mounted /etc/opt/semaphore/da directory.

Alerting service

The semaphore-alerting image provides the alerting service used to send notifications by email. Alerting is an internal service called from Semaphore Studio. Do not publish its port on the host. SMTP credentials must be supplied as environment variables.

To start the Alerting service container, execute the following:

docker run -d \
  --name semaphore-alerting \
  --restart unless-stopped \
  --read-only \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --tmpfs /var/opt/semaphore/alerting/temp:uid=185,gid=0 \
  --network semaphore-network \
  -e QUARKUS_MAILER_HOST=smtp.example.com \
  -e QUARKUS_MAILER_PORT=587 \
  -e QUARKUS_MAILER_USERNAME=alerting@example.com \
  -e QUARKUS_MAILER_PASSWORD=<password> \
  -e QUARKUS_MAILER_FROM=alerting@example.com \
  -e LOG_LEVEL=WARN \
  semaphore-alerting:5.10.4

Required environment variables:

Important: Storing SMTP credentials in plain text environment variables is not recommended for production use. Use file-based credentials by setting QUARKUS_MAILER_USERNAME_FILE and QUARKUS_MAILER_PASSWORD_FILE to the path of a file containing the value, or use Docker secrets when running in Docker Swarm.

Classification Precision and Recall Server (PandR)

The semaphore-pandr image provides the Classification Precision and Recall Server (PandR). PandR is an internal service called from Semaphore Studio to evaluate classification quality. Do not publish its port on the host. PandR requires network access to a Classification Server (CS) instance.

To start the PandR container, execute the following:

docker run -d \
  --name semaphore-pandr \
  --restart unless-stopped \
  --read-only \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --tmpfs /var/opt/semaphore/pandr/temp:uid=185,gid=0 \
  --network semaphore-network \
  -e SEM_PR_CS_URL=http://semaphore-cs:5058 \
  -e PR_LOG_LEVEL=WARN \
  -v /mnt/pandr-logs:/var/opt/semaphore/pandr/logs \
  semaphore-pandr:5.10.4

PandR-specific environment variables:

The health endpoint is http://semaphore-pandr:5091/application/info.

KMM AI Assistant

The semaphore-ai image provides the AI assistant used by KMM. The AI Assistant is an internal service called from Semaphore Studio. Do not publish its port on the host. Connection details for the LLM endpoint (URL, API key, model name and so on) must be provided either through the ai.properties file mounted at /etc/opt/semaphore/ai/ or as environment variables.

To start the KMM AI Assistant container, execute the following:

docker run -d \
  --name semaphore-ai \
  --restart unless-stopped \
  --read-only \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --tmpfs /var/opt/semaphore/ai/temp:uid=185,gid=0 \
  --network semaphore-network \
  -e LOG_LEVEL=WARN \
  -v /mnt/ai-config:/etc/opt/semaphore/ai \
  semaphore-ai:5.10.4

Text Mining Side Panel

The semaphore-text-mining-side-panel image provides the Text Mining Side Panel. The Text Mining Side Panel is called from Semaphore Studio but may also be reached directly by end-user tools. You should publish its port on the host only when external access is required. A running MarkLogic Server is required.

To start the Text Mining Side Panel container, execute the following:

docker run -d \
  --name semaphore-text-mining-side-panel \
  --restart unless-stopped \
  --read-only \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --tmpfs /var/opt/semaphore/tmsp/temp:uid=185,gid=0 \
  --network semaphore-network \
  -p 5093:5093 \
  -e MARKLOGIC_HOST=marklogic.example.com \
  -e TEXT_MINING_SIDE_PANEL_LOG_LEVEL=WARN \
  -v /mnt/tmsp-config:/etc/opt/semaphore/tmsp \
  semaphore-text-mining-side-panel:5.10.4

Verifying a container

Use docker ps to verify that a container is running, and docker logs <container> to review the startup output. For example:

docker ps
docker logs -f semaphore-studio

Upgrading an image

Before upgrading, back up any mounted configuration and data directories. Although the contents of mounts are preserved when a container is recreated, a new image may apply schema or on-disk migrations that cannot be reversed by simply pulling the previous image. A file-system snapshot or copy of each mounted directory makes it possible to roll back if necessary. For example:

docker stop semaphore-studio
tar czf studio-config-backup.tgz -C /mnt studio-config
tar czf studio-data-backup.tgz   -C /mnt studio-data

To upgrade a running container to a newer image version:

docker pull progresssemaphore.azurecr.io/semaphore/semaphore-studio:<new-version>
docker stop semaphore-studio
docker rm semaphore-studio
docker run -d ... semaphore-studio:<new-version>

Mounted configuration and data directories are preserved across the recreate, so the new container starts with the existing state.