ServiceControl Monitoring instances are deployed using the particular/ image, as shown in this minimal example using docker run, assuming a RabbitMQ container named rabbitmq:
docker run -d --name monitoring -p 33633:33633 \
-e TRANSPORTTYPE=RabbitMQ.QuorumConventionalRouting \
-e CONNECTIONSTRING="host=rabbitmq" \
particular/servicecontrol-monitoring:latest
For examples of ServiceControl containers used together, including Docker Compose and Kubernetes examples, see the Platform Container Examples repository.
Initial setup
Before running the container image normally, it must run in setup mode to create the required message queues and perform upgrade tasks.
The container image will run in setup mode by adding the --setup argument. For example:
# Using docker run
docker run --rm {OPTIONS} particular/servicecontrol-monitoring --setup
Setup mode may require different settings, such as a different transport connection string with permissions to create queues.
After setup is complete, the container will exit, and the --rm (or equivalent) option may be used to automatically remove the container.
The setup process should be repeated any time the container is updated to a new version.
Simplified setup
Instead of running --setup as a separate container, the setup and run operations can be combined using the --setup-and-run argument:
# Using docker run
docker run {OPTIONS} particular/servicecontrol-monitoring --setup-and-run
The --setup-and-run argument will run the setup process when the container is run, after which the application will run normally. This simplifies deployment by removing the need for a separate init container in environments where the setup process does not need different settings.
Using --setup-and-run removes the need to repeat a setup process when the container is updated to a new version.
Required settings
The following environment settings are required to run a ServiceControl monitoring instance:
Transport type
Environment variable: TRANSPORTTYPE
Determines the message transport used to communicate with message endpoints. See ServiceControl transport configuration for valid TransportType values.
Transport connection string
Environment variable: CONNECTIONSTRING
Provides the connection information to connect to the chosen transport. The form of this connection string is different for every message transport. See ServiceControl transport support for more details on options available to each message transport.
License
Environment variable: PARTICULARSOFTWARE_LICENSE
The Particular Software license, which is most easily provided to a container as an environment variable. The environment variable should contain the full multi-line contents of the license file.
A license file can also be volume-mounted to the container in the machine-wide license location for Linux:
-v license.xml:/usr/share/ParticularSoftware/license.xml
Ports
33633 is the canonical port exposed by the monitoring instance API within the container, though this port can be mapped to any desired external port.
Volumes
The monitoring instance is stateless and does not require any mounted volumes.
Additional settings
Additional optional settings are documented in Monitoring Instance Configuration Settings which describes all available settings, allowed values, and the environment variable keys used to configure the container.
When using tools such as Docker Compose that can share environment information between many containers, the prefix MONITORING_ can be dropped from an environment variable name, and the value will still be understood by the container. This facilitates sharing values such as TRANSPORTTYPE when all instances will be configured with the same values.
In the event of a naming collision, a fully qualified key such as MONITORING_TRANSPORTTYPE will be preferred over the shared TRANSPORTTYPE variant.
Not all settings are relevant to audit instances running in a container. For example, HTTP hostname and port use standard values inside the container, and mapped to real hosts and ports by infrastructure external to the container. Be sure to check the documentation for each configuration setting carefully to ensure it is relevant in a container context.
Upgrading
A ServiceControl monitoring instance is upgraded by removing the container for the old version and replacing it with a container built using the new version. However, the container should be run in setup mode each time it is upgraded. For example:
docker stop monitoring
docker rm monitoring
docker pull particular/servicecontrol-monitoring:latest
docker run -rm {OPTIONS} particular/servicecontrol-monitoring:latest --setup
docker run -d {OPTIONS} particular/servicecontrol-monitoring:latest
Note that Docker can cache the latest tag as well as the major/minor tags (such as 5 or 5.) unless the tag is pulled again. To be certain, use the full version tag.