added uml describing the final setup

docs/admin/setup/distributed.rst

@@ -43,6 +43,8 @@ have to be synchronized:
 
 Each of these three aspects is synchronized using a different solution
 
+.. _Database Cache:
+
 Database cache
 ^^^^^^^^^^^^^^
 Artemis uses a cache provider that supports distributed caching: Hazelcast_.
@@ -281,6 +283,8 @@ This enables the registry in nginx
 This will apply the config changes and the registry will be reachable.
 
 
+.. _WebSockets:
+
 WebSockets
 ^^^^^^^^^^
 
@@ -537,13 +541,33 @@ You should now be able to see all instances in the registry interface at ``http:
 Running multiple instances locally with Docker
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-You can also run multiple instances of Artemis locally using Docker. This will run the Artemis instances in prod
-environment
+You can also run multiple instances of Artemis locally using Docker. This will start 3 artemis instances, each running
+on a its own container. A load balancer (nginx) will be used to distribute the requests to the different instances. The
+load balancer will be running on a separate container and will be accessible on ports 80/443 of the host system. The
+instances will be registered in the registry service running on a separate container. The instances will use the registry
+service to discover each other and form a hazelcast cluster. Further details can be found in :ref:`Database Cache`. The
+instances will also use a ActiveMQ Artemis broker to synchronize WebSocket messages. Further details can be found in
+:ref:`WebSockets`. In summary, the setup will look like this:
+
+* 3 Artemis instances:
+
+    * artemis-app-node-1: using following spring profile: ``prod,localvc,localci,buildagent,core,scheduling,docker``
+    * artemis-app-node-2: using following profile: ``prod,localvc,localci,buildagent,core,docker``
+    * artemis-app-node-3: using following profile: ``prod,localvc,localci,buildagent,core,docker``
+* A MySQL database addressable on port 3306 of the host system
+* A Load balancer (nginx) addressable on ports 80/443 of the host system: ``http(s)://localhost``
+* A Registry service addressable on port 8761 of the host system: ``http://localhost:8761``
+* An ActiveMQ broker
+
+
+   .. figure:: distributed/multi-node-setup.drawio.png
+      :align: center
 
 Linux setup
 """""""""""
 
-#. When running the Artemis container on a Unix system, you will have to give the user running in the container
+#. (This step is not necessary for MacOS. Here's why: `post <https://stackoverflow.com/a/70385997>`_)
+   When running the Artemis container on a Unix system, you will have to give the user running in the container
    permission to access the Docker socket by adding them to the docker group. You can find the group ID of the docker
    group by running ``getent group docker | cut -d: -f3``. Afterwards, create a new file ``docker/.env`` with the
    following content: