Skip to main content
Version: 3.4

Docker Containers

Starting from version 3.4.0, USP is available as a set of custom Docker images.

Image Variants​

Each image is offered in two variants that differ only in the base operating system layer. The USP binary is the same in both.

  • RHEL: built on redhat/ubi10-minimal. Use this variant if your organization requires Red Hat base images.
  • Debian: built on debian:trixie. A suitable default for most deployments without a specific OS policy requirement.

If your organization has no base image policy, either variant works.

Each USP component is provided in a separate Docker image:

ImageComponent
usp-managerUSP Manager
usp-serverUSP Server
usp-clientUSP Client

Downloading a USP Docker Image​

To obtain the Docker images, contact your Stonebranch representative. If you do not have a representative, reach out to support@stonebranch.com.

Architecture​

Each USP component runs in its own container. The three images are independent; they are configured separately and communicate over the network. USP Manager and USP Client run in the trusted internal network (LAN); USP Server runs in the DMZ.

USP Manager connects outward to a database, which must be running and reachable before the Manager container starts. Admins access the USP Manager Admin UI through port 8800.

USP Manager communicates with USP Server over mutual TLS (mTLS) through port 8900 on the Server container. This management channel is used to push configuration and track operational state.

USP Client initiates an outbound tunnel to USP Server (no inbound port mappings are required on the Client container). Once the tunnel is established, USP Client forwards authorized traffic to UDMG Server (or another configured internal target). External Partners connect to USP Server through port 8901.

Prerequisites​

Database​

USP Manager requires a running database. Refer to Database Installation for setup instructions.

Running a USP Container​

There are two ways to provide configuration when running a USP container:

  • Environment Variables (Recommended): pass required parameters as -e flags on docker run, overriding the default configuration file bundled in the image.
  • Custom Configuration File: mount a complete HCL configuration file from the host into the container, replacing the default configuration file bundled in the image.

Pass configuration parameters directly to docker run using -e flags.

The following commands include the minimum required parameters for each component:

docker run -d \
  --name usp-manager \
  -p 8800:8800 \
  -e USP_MANAGER_ENCRYPTION_KEK=<encryption-key> \
  -e USP_MANAGER_AUTH_KEY=<auth-key> \
  -e USP_MANAGER_DATABASE_ENGINE=<engine> \
  -e USP_MANAGER_DATABASE_HOSTNAME=<hostname> \
  -e USP_MANAGER_DATABASE_PORT=<port> \
  -e USP_MANAGER_DATABASE_NAME=<database-name> \
  -e USP_MANAGER_DATABASE_USERNAME=<database-user> \
  -e USP_MANAGER_DATABASE_PASSWORD=<database-password> \
  <image-name>:<tag>

For guidance on generating and setting these values, refer to Set the USP Manager's Configuration File in the USP Manager Linux Installation guide.

For a full list of available options, refer to USP Manager Environment Variables.

Custom Configuration File​

Mount a configuration file from the host into the container at the default configuration file location, replacing the default:

docker run -d \
  --name usp-manager \
  -p 8800:8800 \
  -v <path-to-existing-config-file>:/config/usp-manager.hcl:ro \
  <image-name>:<tag>

The following configuration file includes the minimum required parameters to start USP Manager:

usp-manager.hcl
encryption {
  kek_source = "config"
  kek        = "<encryption-key>"
}

database {
  engine   = "<engine>"
  hostname = "<hostname>"
  port     = <port>
  name     = "<database-name>"
  username = "<database-user>"
  password = "<database-password>"
}

auth {
  key = "<path-to-auth-key>"
}

For guidance on generating and setting these values, refer to Set the USP Manager's Configuration File in the USP Manager Linux Installation guide.

For a full list of available options, refer to USP Manager Configuration File.

Docker Container Default Port Numbers​

The USP Docker images declare the following ports. To make a port accessible on the host, map it explicitly using the -p <host-port>:<container-port> option when running the container.

Default Port NumberDescriptionConfiguration File ArgumentEnvironment Variable
8800USP Manager web server port.web.host (in the usp-manager.hcl file)USP_MANAGER_WEB_HOST
8900USP Server management port.web.config_host (in the usp-server.hcl file)USP_SERVER_WEB_CONFIG_HOST
8901USP Server API port.web.api_host (in the usp-server.hcl file)USP_SERVER_WEB_API_HOST

Entrypoint​

Each USP Docker image has a simple entrypoint that adds support for the OpenShift arbitrary UIDs and then proceeds to start each component using the binary and the configuration file at the default location. This is either the default file bundled in the image, a custom file mounted at that path, or the default file with values overridden by environment variables, as explained in Running a USP Container.

ImageBinary LocationDefault Configuration File Location
usp-manager/app/usp-manager/config/usp-manager.hcl
usp-server/app/usp-server/config/usp-server.hcl
usp-client/app/usp-client/config/usp-client.hcl

Image Labels​

USP images include labels that provide metadata about the image, such as the version, base image, and build information.

OCI Labels​

These labels follow the OCI Image Format Specification.

LabelDescriptionExample Value
org.opencontainers.image.authorsThe contact details of the organization that created the image.support@stonebranch.com
org.opencontainers.image.base.nameThe name of the base image the component image was created with.docker.io/redhat/ubi10-minimal:latest
org.opencontainers.image.base.digestThe digest of the base image the component image was created with.sha256:d801168f5e8b…
org.opencontainers.image.createdAn ISO8601 timestamp of when the image was created.2026-09-07T20:00:41Z
org.opencontainers.image.descriptionA description of the component image and what it is used for.USP Manager
org.opencontainers.image.ref.nameThe name of the component in the image.usp-manager
org.opencontainers.image.titleThe title for the image.USP Manager installed in a Red Hat base image
org.opencontainers.image.vendorThe organization distributing the image.Stonebranch, Inc.
org.opencontainers.image.versionThe version of the application inside the image.3.4.0

RHEL Labels​

These labels follow the Red Hat OpenShift Software Certification Policy Guide.

LabelDescriptionExample Value
nameThe image name.usp-manager
vendorThe company name.Stonebranch, Inc.
versionThe image version.3.4.0
releaseThe image release.3.4.0
summaryA short description of the image.USP Manager
descriptionA description of the image.The USP Manager provides the management API and web UI for UDMG Secure Proxy