Development: Add documentation for production setup using Docker

docker/artemis/config/node1-core.env

@@ -0,0 +1,6 @@
+SPRING_PROFILES_ACTIVE='prod,localvc,localci,core,scheduling,docker'
+EUREKA_INSTANCE_INSTANCEID='Artemis:1'
+EUREKA_INSTANCE_HOSTNAME='artemis-app-node-1'
+SPRING_HAZELCAST_INTERFACE='artemis-app-node-1'
+
+ARTEMIS_VERSIONCONTROL_URL='http://artemis-app-node-1:8080'

docker/artemis/config/node2-buildagent.env

@@ -0,0 +1,8 @@
+SPRING_PROFILES_ACTIVE='prod,buildagent'
+EUREKA_INSTANCE_INSTANCEID='Artemis:2'
+EUREKA_INSTANCE_HOSTNAME='artemis-app-node-2'
+SPRING_HAZELCAST_INTERFACE='artemis-app-node-2'
+
+ARTEMIS_VERSIONCONTROL_URL='http://artemis-app-node-1:8080'
+ARTEMIS_VERSIONCONTROL_USER='artemis_admin'
+ARTEMIS_VERSIONCONTROL_PASSWORD='artemis_admin'

docker/artemis/config/node3-core.env

@@ -0,0 +1,6 @@
+SPRING_PROFILES_ACTIVE='prod,localvc,localci,core,docker'
+EUREKA_INSTANCE_INSTANCEID='Artemis:3'
+EUREKA_INSTANCE_HOSTNAME='artemis-app-node-3'
+SPRING_HAZELCAST_INTERFACE='artemis-app-node-3'
+
+ARTEMIS_VERSIONCONTROL_URL='http://artemis-app-node-1:8080'

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
 ^^^^^^^^^^
 
@@ -533,3 +537,163 @@ different ports and a unique instance ID for each instance.
 #. Start the remaining instances.
 
 You should now be able to see all instances in the registry interface at ``http://localhost:8761``.
+
+.. _Running multiple instances locally with Docker:
+
+Running multiple instances locally with Docker
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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
+
+
+
+.. note::
+
+    You don't have to start the client manually. The client files are served by the Artemis instances and can be
+    accessed through the load balancer on ``http(s)://localhost``.
+
+Linux setup
+"""""""""""
+
+#. (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:
+
+    .. code:: bash
+
+        DOCKER_GROUP_ID=<REPLACE_WITH_DOCKER_GROUP_ID_OF_YOUR_SYSTEM>
+
+#. The docker compose setup which we will use will mount some local directories
+   (namely the ones under docker/.docker-data) into the containers. To ensure that the user running in the container has
+   the necessary permissions to these directories, you will have to change the owner of these directories to the
+   user running in the container (User with ID 1337). You can do this by running the following command:
+
+    .. code:: bash
+
+        sudo chown -R 1337:1337 docker/.docker-data
+
+    .. note::
+
+        - If you don't want to change the owner of the directories, you can create other directories with the necessary
+          permissions and adjust the paths in the docker-compose file accordingly.
+        - You could also use docker volumes instead of mounting local directories. You will have to adjust the docker-compose
+          file accordingly (`Docker docs <https://docs.docker.com/storage/volumes/#use-a-volume-with-docker-compose/>`_).
+          However, this would make it more difficult to access the files on the host system.
+
+#. Start the docker containers by running the following command:
+
+    .. code:: bash
+
+        docker compose -f docker/test-server-multi-node-mysql-localci.yml up
+
+#. You can now access artemis on ``http(s)://localhost`` and the registry on ``http://localhost:8761``.
+
+Windows setup
+"""""""""""""
+
+#. When running the Artemis container on a Windows system, you will have to change the value for the Docker connection
+   URI. You need to change the value of the environment variable ``ARTEMIS_CONTINUOUSINTEGRATION_DOCKERCONNECTIONURI``
+   in the file ``docker/artemis/config/prod-multinode.env`` to ``tcp://host.docker.internal:2375``.
+
+    .. note::
+
+        - Make sure that option "Expose daemon on tcp://localhost:2375 without TLS" is enabled. This can be found under
+          Settings > General in the Docker Desktop.
+
+#. Start the docker containers by running the following command:
+
+    .. code:: bash
+
+        docker compose -f docker/test-server-multi-node-mysql-localci.yml up
+
+#. You can now access artemis on ``http(s)://localhost`` and the registry on ``http://localhost:8761``.
+
+MacOS setup
+"""""""""""
+
+#. Make sure to enable "Allow the default Docker socket to be used (requires password)" in Docker Desktop settings.
+   This can be found under Settings > Advanced in the Docker Desktop.
+
+#. Start the docker containers by running the following command:
+
+    .. code:: bash
+
+        docker compose -f docker/test-server-multi-node-mysql-localci.yml up
+
+#. You can now access artemis on ``http(s)://localhost`` and the registry on ``http://localhost:8761``.
+
+
+Separate Core and BuildAgent Instances
+""""""""""""""""""""""""""""""""""""""
+
+In a multi instance setup, it is possible to separate the core and build agent instances. This can be useful if you want
+to have a dedicated instances for running the build agents. The core instances will then only be responsible for handling
+the core functionality of Artemis (e.g. managing courses, exercises, users, etc.). The build agent instances will only be
+responsible for running the build agents. This can be useful if you want to scale the build agents independently from the
+core instances. The setup will be similar to the one described in :ref:`Running multiple instances locally with Docker`.
+The main differences are:
+
+* The artemis instances will be separated into core and build agent instances:
+
+    * artemis-app-node-1: using following spring profile: ``prod,localvc,localci,core,scheduling,docker``
+    * artemis-app-node-2: using following spring profile: ``prod,buildagent``
+    * artemis-app-node-3: using following spring profile: ``prod,localvc,localci,core,docker``
+
+* The load balancer will not forward requests to the build agent instance (node-2).
+
+
+#. Follow the steps described in :ref:`Running multiple instances locally with Docker`. However, do not run the
+   ``docker compose`` command to start the docker containers yet.
+
+#. Add the following environment variables to the file ``docker/.env``:
+
+    .. code:: bash
+
+        ARTEMIS_NODE_1_ENV_FILE=./artemis/config/node1-core.env
+        ARTEMIS_NODE_2_ENV_FILE=./artemis/config/node2-buildagent.env
+        ARTEMIS_NODE_3_ENV_FILE=./artemis/config/node3-core.env
+
+#. Comment out the following line in the file ``docker/nginx/artemis-upstream-multi-node.conf``:
+
+    .. code:: bash
+
+        server artemis-app-node-1:8080;
+        # server artemis-app-node-2:8080;
+        server artemis-app-node-3:8080;
+
+#. Start the docker containers by running the following command:
+
+    .. code:: bash
+
+        docker compose -f docker/test-server-multi-node-mysql-localci.yml up
+
+    .. hint::
+
+        You may run into the following error when starting the containers
+        ``No member group is available to assign partition ownership...``. To fix this, you can first start the following
+        containers:
+        ``docker compose -f docker/test-server-multi-node-mysql-localci.yml up mysql jhipster-registry activemq-broker artemis-app-node-1``.
+        After these containers are up and running, you can start the remaining containers:
+        ``docker compose -f docker/test-server-multi-node-mysql-localci.yml up artemis-app-node-2 artemis-app-node-3 nginx``.