# Deploying ServiceControl Audit instances using containers


ServiceControl Audit instances are deployed using the [`particular/servicecontrol-audit` image](https://hub.docker.com/r/particular/servicecontrol-audit), as shown in this minimal example using `docker run`, assuming a RabbitMQ container named `rabbitmq`:

```shell
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
```

> [!TIP]
> For examples of ServiceControl containers used together, including Docker Compose and Kubernetes using a Helm chart, see the [Platform Container Examples repository](https://github.com/Particular/PlatformContainerExamples).

## 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:

```shell
# 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 can be used to automatically remove it.

The setup process should be repeated any time the container is [updated to a new version](#upgrading).

### Simplified setup

Instead of running `--setup` as a separate container, the setup and run operations can be combined using the `--setup-and-run` argument:

```shell
# Using docker run
docker run {OPTIONS} particular/servicecontrol-audit --setup-and-run
```

The `--setup-and-run` argument runs the setup process when the container starts, after which the application runs 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](/servicecontrol/transports.md) 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](/servicecontrol/transports.md) 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 instance's data. The database container should be exclusive to the instance, and not shared by any other ServiceControl instances.

If the [storage requirements for the RavenDB container](/servicecontrol/ravendb/containers.md#required-settings) 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:

<!-- This include file may be auto-generated in the future -->

| ServiceControl Versions | RavenDB Version |
|:-:|:-:|
| `6.*` | `6.2` |

#### RavenDB client certificate

_Added in ServiceControl version 6.3.0_

When connecting to an external RavenDB instance, the RavenDB client certificate can be specified using a combination of settings, which are attempted in this order:

1. An environment variable `RAVENDB_CLIENTCERTIFICATEBASE64` can be used to supply the client certificate as a Base64-encoded string.
2. An environment variable `RAVENDB_CLIENTCERTIFICATEPATH` can be used to identify the local path to a certificate that has added to the container via a mounted volume.
3. The app will attempt to load the certificate from `/app/raven-client-certificate.pfx`.
4. The app will attempt to access the database without a client certificate.

In any of the above cases, the certificate can be password-protected, in which case the password can be supplied using the `RAVENDB_CLIENTCERTIFICATEPASSWORD` environment variable.
### License

_Environment variable:_ `PARTICULARSOFTWARE_LICENSE`

The Particular Software license, which is most easily provided to a container [as an environment variable](/nservicebus/licensing/index.md#license-management-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](/nservicebus/licensing/index.md#license-management-machine-wide-license-location):

```shell
-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](/servicecontrol/audit-instances/configuration.md), 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 across many containers, the `SERVICECONTROL_AUDIT_` prefix 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 are mapped to real hosts and ports by infrastructure external to the container. Be sure to carefully review the documentation for each configuration setting to ensure it is relevant in a container context.

## Upgrading

A 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](#initial-setup) each time it is upgraded. For example:

```shell
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.3`) unless the tag is pulled again. To be certain, use the full version tag.