ServiceControl 6 documentation (#6862)

* Add SC version 6 snippets, but … and remove stuff we weren't using

* Upgrade guide

* Raven container page updates

* Volume map instead of bind mount

* external raven

* Revisions

---------

Co-authored-by: Brandon Ording <bording@gmail.com>

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

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,25 +18,47 @@ 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 <DATA_DIRECTORY>:/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
 
 As the ServiceControl RavenDB container extends the official RavenDB container, additional configuration details can be found in the RavenDB Docker container documentation, according to this version map:
 
 | 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.

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 <insert sc ravendb container name here>
+docker remove <insert sc ravendb container name here>
+docker run --rm \
+    -v <ravendb volume name or bind mount path>:/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).