ServiceControl Audit 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 audit -p 44444:44444 \
-e TRANSPORTTYPE=RabbitMQ.QuorumConventionalRouting \
-e CONNECTIONSTRING="host=rabbitmq" \
-e RAVENDB_CONNECTIONSTRING="http://audit-db:8080" \
particular/servicecontrol-audit: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-audit --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-audit --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 audit 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.
RavenDB connection string
Environment variable: RAVENDB_CONNECTIONSTRING
Provides the URL to connect to the database container that stores the audit instance's data. The database container should be exclusive to the error instance, and not shared by any other ServiceControl instances.
If the storage requirements for the RavenDB container cannot be met by the container hosting infrastructure, especially in cloud-hosted environments, an externally-hosted and separately-licensed RavenDB instance can also be used starting with ServiceControl version 6.0.
In this case, the RavenDB Major.Minor version must match the version expected by ServiceControl as shown in this table:
| ServiceControl Versions | RavenDB Version |
|---|---|
6. | 6. |
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
44444 is the canonical port exposed by the audit instance API within the container, though this port can be mapped to any desired external port.
Volumes
The Audit instance is stateless and does not require any mounted volumes.
Additional settings
Additional optional settings are documented in Audit 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 SERVICECONTROL_AUDIT_ 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 SERVICECONTROL_AUDIT_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
An ServiceControl audit 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 audit
docker rm audit
docker pull particular/servicecontrol-audit:latest
docker run -rm {OPTIONS} particular/servicecontrol-audit:latest --setup
docker run -d {OPTIONS} particular/servicecontrol-audit: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.