Using Progress-supplied Docker images

In addition to building your own Docker images, Progress Semaphore distributes pre-built Docker images for the main Semaphore components. These images are produced and tested by Progress and are intended for production use. Using the supplied images removes the need to install RPMs and build Dockerfiles yourself.

This topic provides an overview of the available images and covers the following:

• Prerequisites
• Image tags
• Pulling an image
• Container user and file permissions
• Standard volume locations
• Network architecture and exposure
• Container security hardening
• Licence directory requirements
• Required internal services
• Common environment variables

Note: Progress-supplied Docker images are available starting with Semaphore release 5.10.4. Earlier releases are not distributed as Docker images. To deploy an earlier release in a container, follow the instructions in Deploy Semaphore with Docker.

The following components are available as Progress-supplied Docker images:

Note: The Classification Server is distributed as four image variants to match different NLP engine and language requirements:

• semaphore-classification — Bitext NLP engine only; no Java runtime required. Smallest footprint.
• semaphore-classification-java — Babel Street Rosette NLP runtime included; language packs must be mounted externally.
• semaphore-classification-en — Babel Street Rosette NLP with English language pack bundled.
• semaphore-classification-multilingual — Babel Street Rosette NLP with multiple language packs bundled. Largest image.

Prerequisites

• Docker version 20.10 or later

• Docker Compose version 2.0 or later (only required when using Docker Compose)

• Access to the Progress Semaphore Docker registry, with credentials provided by Progress

• A valid Semaphore licence file

Image tags

Progress-supplied images are tagged with the Semaphore release version. Choose a tag based on how strictly you need to control which version is deployed:

Pinning to X.Y.Z (for example 5.10.4) guarantees that an unintended image update cannot change the version of a running service. Using the X.Y tag (for example 5.10) automatically picks up the most recent patch release of that minor version when the container is recreated.

Pulling an image

Authenticate against the Progress Semaphore Docker registry, then pull the image you need. For example:

docker login progresssemaphore.azurecr.io
docker pull progresssemaphore.azurecr.io/semaphore/semaphore-studio:5.10.4

Container user and file permissions

Most Progress-supplied images run as a non-root user with UID 185. When mounting host directories for configuration, data, or logs, ensure the directories are writable by this user. For example:

sudo mkdir -p /mnt/studio-config /mnt/studio-data
sudo chown -R 185:185 /mnt/studio-config /mnt/studio-data

The Classification Server image is an exception — it creates a sem_cs system account without pinning a UID. To get the actual UID before setting ownership on host directories, run:

docker run --rm --entrypoint "" <image-name> sh -c 'id -u sem_cs'

Standard volume locations

All Progress-supplied images use the same top-level directory layout inside the container:

• /etc/opt/semaphore/<component> --- editable configuration files

• /var/opt/semaphore/<component>/... --- runtime data, logs and any other state that must persist across container restarts. The layout under that subdirectory varies per component (for example, /var/opt/semaphore/CS/rulebases, /var/opt/semaphore/SES/data and /var/opt/semaphore/studio/data/tdb). The exact mount points for each component are listed in Run individual Progress-supplied Docker images.

Mount host directories or named Docker volumes to these paths to preserve configuration and data when the container is recreated.

Note: The Classification Server also requires one writable path outside the standard layout: /opt/semaphore/CS/failures. On a read-only root filesystem, mount a writable volume at this path or redirect it by setting failure_dir in config.xml to a path under /var/opt/semaphore/CS/. Set max_fails_kept to 0 in config.xml to disable failure file writing entirely.

Network architecture and exposure

Semaphore Studio is the only component that end users interact with directly. The remaining components are internal services that Studio (and other Semaphore tooling) calls on behalf of the user:

• Semaphore Studio entrypoint --- semaphore-studio

• Internal services --- semaphore-kmm (KMM), semaphore-rm, semaphore-sm, semaphore-cm, semaphore-da, semaphore-alerting, semaphore-pandr, semaphore-ai, and any other service that backs Semaphore Studio

• External services --- semaphore-cs, semaphore-ses, semaphore-concepts and semaphore-text-mining-side-panel are also called from Semaphore Studio, but may additionally be reached by external clients, publishers or end-user tools. Publish their ports on the host (or expose them through a reverse proxy) only when external access is actually required; otherwise leave them accessible only on the shared Docker network.

Internal services must not be exposed to public networks. Only the Semaphore Studio port (5080) --- and, where required, the CS, SES, Concepts and Text Mining Side Panel ports --- should be published on the host or routed through a reverse proxy.

To allow Semaphore Studio to reach the other services, attach every container to the same Docker network, and refer to each service by its container name. Using the example container names from this guide, Semaphore Studio reaches the other services at host names such as semaphore-rm, semaphore-sm, semaphore-cs, semaphore-ses, semaphore-concepts, and so on. See Networking Semaphore with Docker for the network creation commands. The compose.yml example in Run Progress-supplied Docker images with Docker Compose creates this shared network automatically.

Container security hardening

Progress recommends running all Semaphore containers with the following security settings to reduce the attack surface:

• Read-only root filesystem (--read-only / read_only: true) --- prevents processes inside the container from writing to the container's own filesystem. Any writes that the application must perform go to explicitly mounted volumes or tmpfs mounts.

• Drop all Linux capabilities (--cap-drop ALL / cap_drop: [ALL]) --- removes all default Linux kernel capabilities from the container process.

• No new privileges (--security-opt no-new-privileges:true / security_opt: [no-new-privileges:true]) --- prevents the container process from gaining additional privileges via setuid or setgid binaries.

When running with a read-only root filesystem, each container needs a writable tmpfs mount for its temporary files. The standard location is /var/opt/semaphore/<component>/temp. For example, in a docker run command:

docker run -d \
  --read-only \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --tmpfs /var/opt/semaphore/studio/temp:uid=185,gid=0 \
  ...

In a compose.yml:

services:
  studio:
    read_only: true
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    tmpfs:
      - /var/opt/semaphore/studio/temp:uid=185,gid=0

The uid=185,gid=0 options ensure the tmpfs mount is writable by the non-root user that runs inside the container. See the individual container pages for the exact tmpfs path for each component.

Licence directory requirements

Several Semaphore components require a valid licence file at runtime. The licence directory must be mounted into the container. Most components only read the licence file and the mount may be read-only, but Studio requires read-write access:

• Semaphore Studio --- mount the licence directory at /var/opt/semaphore/studio/data/licenses. This mount must be read-write (do not use :ro) because Studio writes licence state files at runtime.

• Classification and Language Service (CS) --- mount the licence file at /opt/semaphore/licence

• Semantic Enhancement Server (SES) --- mount the licence directory at /opt/semaphore/licence

• Knowledge Model Management (KMM) --- mount the shared Studio licence directory at /var/opt/semaphore/studio/data/licenses (read-only)

Ensure that the host directory containing the licence file is readable by UID 185. For CS, SES, and KMM you may use the :ro suffix on the volume mount to prevent accidental modification. For Studio the mount must remain read-write.

Required internal services

Semaphore Studio requires the following internal services to be running and healthy before it can start serving requests:

• semaphore-kmm --- Knowledge Model Management
• semaphore-da --- Document Analyzer
• semaphore-sm --- SES Manager
• semaphore-rm --- Rulebase Manager
• semaphore-cm --- Concepts Manager
• semaphore-alerting --- Alerting service
• semaphore-ai --- KMM AI Assistant

When using Docker Compose, declare these services in the depends_on section of the Studio service with condition: service_healthy to ensure they are started in the correct order. When using docker run, start each internal service and confirm it is healthy (via its /application/info or health endpoint) before starting Semaphore Studio.

Common environment variables

Each Progress-supplied image supports a small set of common environment variables. Component-specific variables are listed in the page for that component.

Note: Some components use a component-specific log-level variable instead of LOG_LEVEL. Use:

• STUDIO_LOG_LEVEL for Semaphore Studio

• DA_LOG_LEVEL for the Document Analyzer

• RM_LOG_LEVEL for the Rulebase Manager

• SM_LOG_LEVEL for the SES Manager

• CM_LOG_LEVEL for the Concepts Manager

• CONCEPTS_LOG_LEVEL for the Concepts Server

• SEMAPHORE_WORKBENCH_LOG_LEVEL for the Knowledge Model Management plugin

• TEXT_MINING_SIDE_PANEL_LOG_LEVEL for the Text Mining Side Panel

The Alerting and KMM AI Assistant images use LOG_LEVEL. JVM_OPTS_APPEND is supported by all Java-based components.

The Classification Server supports additional optional environment variables used for the NLP engine and language pack configuration. See CS environment variables for more information.

The Quarkus-based services (Studio, Concepts, RM, SM, CM, DA, Alerting, KMM AI Assistant) also allow any application property to be overridden by setting the corresponding environment variable. The variable name is the property name in upper case with dots (.) and hyphens (-) replaced by underscores (_). For example, the property quarkus.http.port becomes QUARKUS_HTTP_PORT. Environment variables take priority over values defined in property files.

See also

• Run individual Progress-supplied Docker images

• Run Progress-supplied Docker images with Docker Compose