From f9676a88c1375ace4de65455d88042c913b35748 Mon Sep 17 00:00:00 2001 From: Rhys Bevilaqua Date: Tue, 27 Oct 2026 15:45:15 +0800 Subject: [PATCH] Update container readmes to reflect new storage types --- src/ServiceControl.Audit/Container-README.md | 21 +++++++++++++- .../Container-README.md | 2 +- .../Container-README.md | 4 +-- src/ServiceControl/Container-README.md | 29 ++++++++++++++++++- 4 files changed, 51 insertions(+), 5 deletions(-) diff --git a/src/ServiceControl.Audit/Container-README.md b/src/ServiceControl.Audit/Container-README.md index 51a56d36fd..957ba151ba 100644 --- a/src/ServiceControl.Audit/Container-README.md +++ b/src/ServiceControl.Audit/Container-README.md @@ -7,7 +7,7 @@ The `particular/servicecontrol-audit` image is part of the Particular Service Pl | [`particular/servicecontrol`](https://hub.docker.com/r/particular/servicecontrol) | [Instance Documentation](https://docs.particular.net/servicecontrol/servicecontrol-instances/)
[Container Documentation](https://docs.particular.net/servicecontrol/servicecontrol-instances/deployment/containers) | The primary/error instance, which includes error handling and recoverability | | [`particular/servicecontrol-audit`](https://hub.docker.com/r/particular/servicecontrol-audit) | [Instance Documentation](https://docs.particular.net/servicecontrol/audit-instances/)
[Container Documentation](https://docs.particular.net/servicecontrol/audit-instances/deployment/containers) | The audit instance, which stores audit data, and can be scaled out to multiple audit instances | | [`particular/servicecontrol-monitoring`](https://hub.docker.com/r/particular/servicecontrol-monitoring) | [Instance Documentation](https://docs.particular.net/servicecontrol/monitoring-instances/)
[Container Documentation](https://docs.particular.net/servicecontrol/monitoring-instances/deployment/containers) | The monitoring instance, which tracks runtime information like throughput, queue length, and other metrics | -| [`particular/servicecontrol-ravendb`](https://hub.docker.com/r/particular/servicecontrol-ravendb) | [Container Documentation](https://docs.particular.net/servicecontrol/ravendb/containers) | The database used by the error/audit instances | +| [`particular/servicecontrol-ravendb`](https://hub.docker.com/r/particular/servicecontrol-ravendb) | [Container Documentation](https://docs.particular.net/servicecontrol/ravendb/containers) | The database for error/audit instances using RavenDB persistence | | [`particular/servicepulse`](https://hub.docker.com/r/particular/servicepulse) | [App Documentation](https://docs.particular.net/servicepulse/)
[Container Documentation](https://docs.particular.net/servicepulse/containerization/) | The web application that provides a front end for recoverability and monitoring features | ## Usage @@ -18,10 +18,29 @@ The following is the most basic way to create an audit container using [Docker]( docker run -d --name audit -p 44444:44444 \ -e TRANSPORTTYPE=RabbitMQ.QuorumConventionalRouting \ -e CONNECTIONSTRING="host=rabbitmq" \ + -e PERSISTENCETYPE=RavenDB \ -e RAVENDB_CONNECTIONSTRING="http://audit-db:8080" \ particular/servicecontrol-audit:latest --setup-and-run ``` +### Persistence + +Set `PERSISTENCETYPE` to select the database. RavenDB is the default. + +| `PERSISTENCETYPE` | Connection string environment variable | +|-------------------|---------------------------------------| +| `RavenDB` | `RAVENDB_CONNECTIONSTRING` | +| `SQLServer` | `DATABASE_CONNECTIONSTRING` | +| `PostgreSQL` | `DATABASE_CONNECTIONSTRING` | + +For SQL Server and PostgreSQL, create the database before running setup. The `particular/servicecontrol-ravendb` image is not needed for either relational database. Audit instances store message bodies in the database and do not require separate message body storage settings or volumes. + +The audit instance uses the `sc_audit` schema by default. Set `DATABASE_SCHEMA` to override it. Error and audit instances can share a database but must use different schemas. + +Setup creates a missing schema if the database user has permission. Otherwise, create the schema and grant the required permissions before running setup. For an existing instance, set `DATABASE_SCHEMA` to the schema containing its data; ServiceControl does not move existing tables. See [SQL persister schemas](https://github.com/Particular/ServiceControl/blob/master/docs/sql-persister-schemas.md). + +These settings also accept the `SERVICECONTROL_AUDIT_` prefix, for example `SERVICECONTROL_AUDIT_PERSISTENCETYPE` and `SERVICECONTROL_AUDIT_DATABASE_CONNECTIONSTRING`. Use prefixed settings when error and audit containers share environment configuration but need different persistence settings. + For all other usage information see the [official container documentation](https://docs.particular.net/servicecontrol/audit-instances/deployment/containers). ## Image tagging diff --git a/src/ServiceControl.Monitoring/Container-README.md b/src/ServiceControl.Monitoring/Container-README.md index bc3c223f15..97be8a7f2e 100644 --- a/src/ServiceControl.Monitoring/Container-README.md +++ b/src/ServiceControl.Monitoring/Container-README.md @@ -7,7 +7,7 @@ The `particular/servicecontrol-monitoring` image is part of the Particular Servi | [`particular/servicecontrol`](https://hub.docker.com/r/particular/servicecontrol) | [Instance Documentation](https://docs.particular.net/servicecontrol/servicecontrol-instances/)
[Container Documentation](https://docs.particular.net/servicecontrol/servicecontrol-instances/deployment/containers) | The primary/error instance, which includes error handling and recoverability | | [`particular/servicecontrol-audit`](https://hub.docker.com/r/particular/servicecontrol-audit) | [Instance Documentation](https://docs.particular.net/servicecontrol/audit-instances/)
[Container Documentation](https://docs.particular.net/servicecontrol/audit-instances/deployment/containers) | The audit instance, which stores audit data, and can be scaled out to multiple audit instances | | [`particular/servicecontrol-monitoring`](https://hub.docker.com/r/particular/servicecontrol-monitoring) | [Instance Documentation](https://docs.particular.net/servicecontrol/monitoring-instances/)
[Container Documentation](https://docs.particular.net/servicecontrol/monitoring-instances/deployment/containers) | The monitoring instance, which tracks runtime information like throughput, queue length, and other metrics | -| [`particular/servicecontrol-ravendb`](https://hub.docker.com/r/particular/servicecontrol-ravendb) | [Container Documentation](https://docs.particular.net/servicecontrol/ravendb/containers) | The database used by the error/audit instances | +| [`particular/servicecontrol-ravendb`](https://hub.docker.com/r/particular/servicecontrol-ravendb) | [Container Documentation](https://docs.particular.net/servicecontrol/ravendb/containers) | The database for error/audit instances using RavenDB persistence | | [`particular/servicepulse`](https://hub.docker.com/r/particular/servicepulse) | [App Documentation](https://docs.particular.net/servicepulse/)
[Container Documentation](https://docs.particular.net/servicepulse/containerization/) | The web application that provides a front end for recoverability and monitoring features | ## Usage diff --git a/src/ServiceControl.RavenDB/Container-README.md b/src/ServiceControl.RavenDB/Container-README.md index 0c7b42a517..207273b231 100644 --- a/src/ServiceControl.RavenDB/Container-README.md +++ b/src/ServiceControl.RavenDB/Container-README.md @@ -7,10 +7,10 @@ The `particular/servicecontrol-ravendb` image is part of the Particular Service | [`particular/servicecontrol`](https://hub.docker.com/r/particular/servicecontrol) | [Instance Documentation](https://docs.particular.net/servicecontrol/servicecontrol-instances/)
[Container Documentation](https://docs.particular.net/servicecontrol/servicecontrol-instances/deployment/containers) | The primary/error instance, which includes error handling and recoverability | | [`particular/servicecontrol-audit`](https://hub.docker.com/r/particular/servicecontrol-audit) | [Instance Documentation](https://docs.particular.net/servicecontrol/audit-instances/)
[Container Documentation](https://docs.particular.net/servicecontrol/audit-instances/deployment/containers) | The audit instance, which stores audit data, and can be scaled out to multiple audit instances | | [`particular/servicecontrol-monitoring`](https://hub.docker.com/r/particular/servicecontrol-monitoring) | [Instance Documentation](https://docs.particular.net/servicecontrol/monitoring-instances/)
[Container Documentation](https://docs.particular.net/servicecontrol/monitoring-instances/deployment/containers) | The monitoring instance, which tracks runtime information like throughput, queue length, and other metrics | -| [`particular/servicecontrol-ravendb`](https://hub.docker.com/r/particular/servicecontrol-ravendb) | [Container Documentation](https://docs.particular.net/servicecontrol/ravendb/containers) | The database used by the error/audit instances | +| [`particular/servicecontrol-ravendb`](https://hub.docker.com/r/particular/servicecontrol-ravendb) | [Container Documentation](https://docs.particular.net/servicecontrol/ravendb/containers) | The database for error/audit instances using RavenDB persistence | | [`particular/servicepulse`](https://hub.docker.com/r/particular/servicepulse) | [App Documentation](https://docs.particular.net/servicepulse/)
[Container Documentation](https://docs.particular.net/servicepulse/containerization/) | The web application that provides a front end for recoverability and monitoring features | -This image is the database used by the [`particular/servicecontrol`](https://hub.docker.com/r/particular/servicecontrol) and [`particular/servicecontrol-audit`](https://hub.docker.com/r/particular/servicecontrol-audit) images, based on the official [RavenDB image](https://hub.docker.com/r/ravendb/ravendb). +This image provides the database for the [`particular/servicecontrol`](https://hub.docker.com/r/particular/servicecontrol) and [`particular/servicecontrol-audit`](https://hub.docker.com/r/particular/servicecontrol-audit) images when `PERSISTENCETYPE=RavenDB` (the default). It is based on the official [RavenDB image](https://hub.docker.com/r/ravendb/ravendb). Instances using `PERSISTENCETYPE=SQLServer` or `PERSISTENCETYPE=PostgreSQL` do not need this image. The purpose of this image is to provide version parity between ServiceControl and database containers. Users can be sure that a given version of the `servicecontrol` and `servicecontrol-audit` container images have been tested with and are known to work with the matching version of `servicecontrol-ravendb`. diff --git a/src/ServiceControl/Container-README.md b/src/ServiceControl/Container-README.md index 806df8c49c..19d7377c2d 100644 --- a/src/ServiceControl/Container-README.md +++ b/src/ServiceControl/Container-README.md @@ -7,7 +7,7 @@ The `particular/servicecontrol` image is part of the Particular Service Platform | [`particular/servicecontrol`](https://hub.docker.com/r/particular/servicecontrol) | [Instance Documentation](https://docs.particular.net/servicecontrol/servicecontrol-instances/)
[Container Documentation](https://docs.particular.net/servicecontrol/servicecontrol-instances/deployment/containers) | The primary/error instance, which includes error handling and recoverability | | [`particular/servicecontrol-audit`](https://hub.docker.com/r/particular/servicecontrol-audit) | [Instance Documentation](https://docs.particular.net/servicecontrol/audit-instances/)
[Container Documentation](https://docs.particular.net/servicecontrol/audit-instances/deployment/containers) | The audit instance, which stores audit data, and can be scaled out to multiple audit instances | | [`particular/servicecontrol-monitoring`](https://hub.docker.com/r/particular/servicecontrol-monitoring) | [Instance Documentation](https://docs.particular.net/servicecontrol/monitoring-instances/)
[Container Documentation](https://docs.particular.net/servicecontrol/monitoring-instances/deployment/containers) | The monitoring instance, which tracks runtime information like throughput, queue length, and other metrics | -| [`particular/servicecontrol-ravendb`](https://hub.docker.com/r/particular/servicecontrol-ravendb) | [Container Documentation](https://docs.particular.net/servicecontrol/ravendb/containers) | The database used by the error/audit instances | +| [`particular/servicecontrol-ravendb`](https://hub.docker.com/r/particular/servicecontrol-ravendb) | [Container Documentation](https://docs.particular.net/servicecontrol/ravendb/containers) | The database for error/audit instances using RavenDB persistence | | [`particular/servicepulse`](https://hub.docker.com/r/particular/servicepulse) | [App Documentation](https://docs.particular.net/servicepulse/)
[Container Documentation](https://docs.particular.net/servicepulse/containerization/) | The web application that provides a front end for recoverability and monitoring features | ## Usage @@ -18,12 +18,39 @@ The following is the most basic way to create ServiceControl containers using [D docker run -d --name servicecontrol -p 33333:33333 \ -e TRANSPORTTYPE=RabbitMQ.QuorumConventionalRouting \ -e CONNECTIONSTRING="host=rabbitmq" \ + -e PERSISTENCETYPE=RavenDB \ -e RAVENDB_CONNECTIONSTRING="http://servicecontrol-db:8080" \ -e REMOTEINSTANCES='[{"api_uri":"http://audit:44444/api"}]' \ -e ENABLEINTEGRATEDSERVICEPULSE="true" \ particular/servicecontrol:latest --setup-and-run ``` +### Persistence + +Set `PERSISTENCETYPE` to select the database. RavenDB is the default. + +| `PERSISTENCETYPE` | Connection string environment variable | +|-------------------|---------------------------------------| +| `RavenDB` | `RAVENDB_CONNECTIONSTRING` | +| `SQLServer` | `DATABASE_CONNECTIONSTRING` | +| `PostgreSQL` | `DATABASE_CONNECTIONSTRING` | + +For SQL Server and PostgreSQL, create the database before running setup. SQL Server requires the Full-Text Search feature. The `particular/servicecontrol-ravendb` image is not needed for either relational database. + +The error instance uses the connection or provider default schema, typically `dbo` on SQL Server or `public` on PostgreSQL. Set `DATABASE_SCHEMA` to override it. Error and audit instances can share a database but must use different schemas. + +Setup creates a missing schema if the database user has permission. Otherwise, create the schema and grant the required permissions before running setup. For an existing instance, set `DATABASE_SCHEMA` to the schema containing its data; ServiceControl does not move existing tables. See [SQL persister schemas](https://github.com/Particular/ServiceControl/blob/master/docs/sql-persister-schemas.md). + +SQL Server and PostgreSQL also require `MESSAGEBODY_STORAGETYPE` to select where message bodies are stored: + +| `MESSAGEBODY_STORAGETYPE` | Required configuration | +|--------------------------|------------------------| +| `FileSystem` | Set `MESSAGEBODY_FILESYSTEM_STORAGEPATH` to a directory backed by a persistent volume and writable by the container user. Without a persistent volume, recreating the container loses message bodies. | +| `AzureBlob` | Set exactly one of `MESSAGEBODY_AZURE_CONNECTIONSTRING` or `MESSAGEBODY_AZURE_SERVICEURI`. A service URI uses managed identity. | +| `S3` | Set `MESSAGEBODY_S3_BUCKETNAME`. Uses the default AWS credential chain unless both `MESSAGEBODY_S3_ACCESSKEYID` and `MESSAGEBODY_S3_SECRETACCESSKEY` are set. | + +These settings also accept the `SERVICECONTROL_` prefix, for example `SERVICECONTROL_PERSISTENCETYPE` and `SERVICECONTROL_DATABASE_CONNECTIONSTRING`. + For all other usage information see the [official container documentation](https://docs.particular.net/servicecontrol/servicecontrol-instances/deployment/containers). ## Image tagging