diff --git a/Snippets/ServiceControl/ServiceControl_5/compose.yml b/Snippets/ServiceControl/ServiceControl_5/compose.yml deleted file mode 100644 index 3fd8d066a73..00000000000 --- a/Snippets/ServiceControl/ServiceControl_5/compose.yml +++ /dev/null @@ -1,61 +0,0 @@ -services: - servicecontrol: - image: ghcr.io/particular/servicecontrol:pr-4187 - hostname: servicecontrol - environment: - - SERVICECONTROL_TRANSPORTTYPE=RabbitMQ.QuorumConventionalRouting - - SERVICECONTROL_CONNECTIONSTRING="host=rabbitmq" - - SERVICECONTROL_RAVENDB_CONNECTIONSTRING=http://ravendb:8080 - #Intentionally disabled so only containers can connect - #ports: - # - 33333:33333 - - servicecontrol-audit: - image: ghcr.io/particular/servicecontrol-audit:pr-4187 - hostname: audit - environment: - - SERVICECONTROL_AUDIT_TRANSPORTTYPE=RabbitMQ.QuorumConventionalRouting - - SERVICECONTROL_AUDIT_CONNECTIONSTRING="host=rabbitmq" - - SERVICECONTROL_AUDIT_RAVENDB_CONNECTIONSTRING=http://ravendb:8080 - #Intentionally disabled so only containers can connect - #ports: - # - 44444:44444 - - servicecontrol-monitoring: - image: ghcr.io/particular/servicecontrol-monitoring:pr-4187 - hostname: monitoring - environment: - - MONITORING_TRANSPORTTYPE=RabbitMQ.QuorumConventionalRouting - - MONIGORING_CONNECTIONSTRING="host=rabbitmq" - #Intentionally disabled so only containers can connect - #ports: - # - 33633:33633 - - servicepulse: - image: particular/servicepulse:1 - ports: - - 9090:90 - - ravendb: - image: ravendb/ravendb:ubuntu-latest - hostname: ravendb - environment: - - RAVEN_Setup_Mode='None' - - RAVEN_Security_UnsecuredAccessAllowed='PrivateNetwork' - - RAVEN_License_Eula_Accepted='true' - - RAVEN_ARGS='-n --log-to-console' - env_file: - - fileName - #Intentionally disabled so only containers can connect - #ports: - # - 8080:8080 - #volumes: - # - ravendatabases:/opt/RavenDb/Server/RavenData - - rabbitmq: - image: rabbitmq:management - hostname: rabbitmq - -volumes: - ravendb: - external: true \ No newline at end of file diff --git a/Snippets/ServiceControl/ServiceControl_5/servicecontrol.env b/Snippets/ServiceControl/ServiceControl_5/placeholder.txt similarity index 100% rename from Snippets/ServiceControl/ServiceControl_5/servicecontrol.env rename to Snippets/ServiceControl/ServiceControl_5/placeholder.txt diff --git a/Snippets/ServiceControl/ServiceControl_6/placeholder.txt b/Snippets/ServiceControl/ServiceControl_6/placeholder.txt new file mode 100644 index 00000000000..e69de29bb2d diff --git a/menu/menu.yaml b/menu/menu.yaml index 1bbad84dc86..5e38cc5d212 100644 --- a/menu/menu.yaml +++ b/menu/menu.yaml @@ -804,7 +804,7 @@ - Url: nservicebus/throughput-tool/sql-transport Title: using SQL Transport - Url: nservicebus/throughput-tool/postgresql-transport - Title: using PostgreSQL Transport + Title: using PostgreSQL Transport - Url: nservicebus/throughput-tool/service-control Title: using ServiceControl - Url: nservicebus/throughput-tool/determine-transport @@ -1453,6 +1453,8 @@ Articles: - Title: Upgrade tips Url: servicecontrol/upgrades + - Title: Version 5 to 6 + Url: servicecontrol/upgrades/5to6 - Title: Version 5.1 to 5.2 Url: servicecontrol/upgrades/5.1to5.2 - Title: Version 4 to 5 diff --git a/servicecontrol/ravendb/containers.md b/servicecontrol/ravendb/containers.md index 17c41aa36c4..1931a4b273f 100644 --- a/servicecontrol/ravendb/containers.md +++ b/servicecontrol/ravendb/containers.md @@ -2,13 +2,14 @@ title: Managing ServiceControl RavenDB instances via Containers reviewed: 2024-06-11 component: ServiceControl +versions: '[5,)' redirects: - servciecontrol/ravendb/deployment/containers --- When ServiceControl is hosted in containers, the [`particular/servicecontrol-ravendb` image](https://hub.docker.com/r/particular/servicecontrol-ravendb) provides the database storage to the Error and Audit instances. -The database container extends the [official RavenDB container](https://hub.docker.com/r/ravendb/ravendb) and is provided to easy version parity with ServiceControl instances. In other words, for any version `x.y.z` version of ServiceControl, the same version `x.y.z` of the database container should be used to ensure data storage compatibility. +The database container extends the [official RavenDB container](https://hub.docker.com/r/ravendb/ravendb) and is provided to ensure compatibility with ServiceControl instances. In other words, for any version `x.y.z` version of ServiceControl, the same version `x.y.z` of the database container should be used to ensure data storage compatibility. > [!WARNING] > A single database container should not be shared between multiple ServiceControl instances in production scenarios. @@ -17,17 +18,38 @@ The database container extends the [official RavenDB container](https://hub.dock This minimal example creates a database container using `docker run`: +#if-version [5, 6) ```shell docker run -d --name servicecontrol-db \ - -v :/opt/RavenDB/Server/RavenData \ + -v db-config:/opt/RavenDB/config \ + -v db-data:/opt/RavenDB/Server/RavenData \ particular/servicecontrol-ravendb:latest ``` +#end-if +#if-version [6, ) +```shell +docker run -d --name servicecontrol-db \ + -v db-config:/etc/ravendb \ + -v db-data:/var/lib/ravendb/data \ + particular/servicecontrol-ravendb:latest +``` +#end-if Once the database container is running, the connection string `http://servicecontrol-db:8080` can be used for the `RAVENDB_CONNECTIONSTRING` value for an [Error instance](/servicecontrol/servicecontrol-instances/deployment/containers.md) or [Audit instance](/servicecontrol/audit-instances/deployment/containers.md). ## Required settings +#if-version [5, 6) A volume must be mounted to `/opt/RavenDB/Server/RavenData` to provide persistent storage for database contents between container updates. Failure to specify a path for the volume will result in loss of all data when the container is removed. +#end-if +#if-version [6,7) +A volume must be mounted to `/var/lib/ravendb/data` to provide persistent storage for database contents between container updates. Failure to specify a path for the volume will result in loss of all data when the container is removed. +#end-if + +> [!NOTE] +> RavenDB has specific requirements about the types of storage it supports. See the [RavenDB container requirements documentation](https://ravendb.net/docs/article-page/6.2/csharp/start/installation/running-in-docker-container#requirements) for more information. +> +> If providing these storage requirements is not possible, it is also possible to connect to an external, separately-licensed RavenDB server. The external server must be using the same Major and Minor version noted in the version map below. ## Additional settings @@ -35,7 +57,8 @@ As the ServiceControl RavenDB container extends the official RavenDB container, | ServiceControl Versions | RavenDB Version | Container Documentation | |:-:|:-:|:-:| -| 5.4 and higher | 5.4 | [RavenDB 5.4 container docs](https://ravendb.net/docs/article-page/5.4/csharp/start/installation/running-in-docker-container) | +| 6.x | 6.2 | [RavenDB 6.2 container docs](https://ravendb.net/docs/article-page/6.2/csharp/start/installation/running-in-docker-container) +| 5.4 to 5.11 | 5.4 | [RavenDB 5.4 container docs](https://ravendb.net/docs/article-page/5.4/csharp/start/installation/running-in-docker-container) | > [!NOTE] -> The [RavenDB container overview on DockerHub](https://hub.docker.com/r/ravendb/ravendb) is specific to the most recent version of RavenDB which may not match the version used by ServiceControl. +> The [RavenDB container overview on Docker Hub](https://hub.docker.com/r/ravendb/ravendb) is specific to the most recent version of RavenDB which may not match the version used by ServiceControl. diff --git a/servicecontrol/upgrades/5to6.md b/servicecontrol/upgrades/5to6.md new file mode 100644 index 00000000000..c6bcb7c2c53 --- /dev/null +++ b/servicecontrol/upgrades/5to6.md @@ -0,0 +1,54 @@ +--- +title: Upgrade ServiceControl from Version 5 to Version 6 +summary: Instructions on how to upgrade ServiceControl from version 5 to 6 +reviewed: 2023-11-30 +isUpgradeGuide: true +component: ServiceControl +--- + +ServiceControl version 6 updates the underlying data storage from RavenDB 5.4 to RavenDB 6.2. Once upgraded, the database cannot be downgraded. + +Users hosting ServiceControl in containerized infrastructure must also make changes to ensure data is accessible in the new version. + +## Prerequisites + +Before upgrading to ServiceControl version 6, ensure all ServiceControl instances have first been upgraded to version 5.11.0. + +## Container changes + +When using the [`servicecontrol-ravendb` container image](https://hub.docker.com/r/particular/servicecontrol-ravendb), the following changes must be made when upgrading to ServiceControl version 6: + +### Data volume mount location + +The internal structure of the container image that the `servicecontrol-ravendb` container image is based on has changed, so the [required data volume](/servicecontrol/ravendb/containers.md#required-settings) must be mounted to the new location inside the container. + +- Old path: `/opt/RavenDB/Server/RavenData` +- New path `/var/lib/ravendb/data` + +If the volume mount mapping is not updated, the container will refuse to start. + +### Data volume permissions + +The previous container ran as `root`, but the new container now runs as a non-root `ravendb` user with user id 999. + +Because of this change, the files created in the data volume by the previous version of the container need to have their owner changed to user id and group id 999. + +The exact way to do this depends on the type of mount used (volume vs. bind mount) and container hosting environment. + +For example, one way this could be achieved: + + ```bash +docker stop +docker remove +docker run --rm \ + -v :/opt/RavenDB/Server/RavenData \ + --entrypoint /bin/bash \ + particular/servicecontrol-ravendb:5.11.0 \ + -c "chown -R 999:999 /opt/RavenDB/Server/RavenData" +``` + +If the permissions have not been updated, the container will refuse to start. + +## Support for version 5 + +Version 5 is supported for one year after version 6 is released as defined by the [ServiceControl support policy](/servicecontrol/upgrades/support-policy.md). The ServiceControl support end date is available at [ServiceControl supported versions](/servicecontrol/upgrades/supported-versions.md).