Docker

Introduction

The Stream Host Docker image is available from XMPro Platform v4.4.2+.

If your installation requires multiple Stream Hosts, please be aware that Stream Host Variable Overrides must be applied as environment variables when running as a Container - enabling frictionless automation when creating multiple Stream Host instances.

Prerequisites

Hardware and Software

A container runtime tool capable of running Docker images, such as Docker Desktop.

The XMPro Docker Stream Host image has already met the rest of the hardware requirements and software requirements.

Configuration Settings

The following configuration settings are required to run the Docker Stream Host. Locate these values before you proceed.

The Keys should be set as environment variables on the running Stream Host Container.

Key	Description
xm:xmpro:Gateway:Id	A unique identifier for a Stream Host instance. A Guid Generator can be used to generate a unique identifier.
xm:xmpro:Gateway:CollectionId	The ID of your Collection. This can be retrieved from a Data Stream Designer "Collection"
xm:xmpro:Gateway:Name	The name that appears in Data Stream Designer when viewing Online Hosts. E.g. "SH1-Device1-Docker" or "SH2-Device2-Winx64".
xm:xmpro:Gateway:Secret	The secret key of your Collection. This can be retrieved from a Data Stream Designer "Collection"
xm:xmpro:Gateway:ServerUrl	The server url for where Data Stream Designer is hosted. E.g. "https://mysampleserver/datastreamdesigner/". Please note that this URL needs to end in a forward slash.
xm:xmpro:Gateway:Rank	An integer, by default is "0". See Stream Host Rank for further details.

These settings can be found in Data Stream Designer:

Fig 1: Collection details in Data Stream Designer

Repository

Below is the XMPro Docker Stream Host repository.

xmpro.azurecr.io/stream-host

Image tags

All images are tagged with the release version number, starting from 4.4.2. For example, use a version tag to reference the Stream Host for v4.4.2:

xmpro.azurecr.io/stream-host:4.4.2

The latest tag identifies the most recent XMPro Platform release version number, for example:

xmpro.azurecr.io/stream-host:latest

Using the latest tag stores a copy of the image on your system. This cached version may not be the latest release if a newer release has since been published.

We recommend specifying the specific version or re-pulling the image if a newer release has occurred since your last Stream Host docker install.

Run Examples

Please see the following examples to run Stream Host as a Container:

• Docker Run

• Docker Compose

Docker Run

Create an "envfile" containing the following (replacing <values> with the actual Configuration Settings)

xm:xmpro:Gateway:Id=<Unique ID>
xm:xmpro:Gateway:CollectionId=<Collection ID>
xm:xmpro:Gateway:Name=<Device Name>
xm:xmpro:Gateway:Secret=<Collection Secret>
xm:xmpro:Gateway:ServerUrl=<Server URL>
xm:xmpro:Gateway:Rank=<Rank>

Start

Run the Stream Host using the following command. Specify the version or add "--pull always" to ensure you're using the newest release.

docker run --env-file=envfile --name stream-host xmpro.azurecr.io/stream-host:latest

Stop

Stop the Stream Host using the following command.

docker rm -f stream-host

Docker Compose

Create a file called compose.yaml in your working directory and paste the following (replacing <values> with the actual Configuration Settings):

stream-host:
  image: xmpro.azurecr.io/stream-host:latest
  pull_policy: always # specify to always use the latest release version
  container_name: 'stream-host'
  environment:
      - xm:xmpro:Gateway:Id=<Unique ID>
      - xm:xmpro:Gateway:CollectionId=<Collection ID>
      - xm:xmpro:Gateway:Name=<Device Name>
      - xm:xmpro:Gateway:Secret=<Collection Secret>
      - xm:xmpro:Gateway:ServerUrl=<Server URL>
      - xm:xmpro:Gateway:Rank=<Rank>
  restart: on-failure

See Docker Compose Overview for further details on how to use Docker Compose.

Start

In the same working directory ascompose.yaml, run the following command to start the Stream Host.

docker-compose up -d stream-host 

Stop

In the same working directory ascompose.yaml, run the following command to stop the Stream Host.

docker-compose down

Next Step: Agents & Connectors

The stream host installation is complete. Please click below to install the default Agents & Connectors:

pageInstall Agents & Connectors