From 2e85b48237eb3b81de5daae20f92aee4ae49c6df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Bo=CC=88hm?= Date: Sat, 17 Feb 2024 15:20:21 +0100 Subject: [PATCH] Update README --- README.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 50 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 24fc1b9a..5b28fac9 100644 --- a/README.md +++ b/README.md @@ -78,9 +78,9 @@ After executing the JAR or WAR file, the application will be available on http:/ For development, the recommended way to run the application is to use the provided IntelliJ run configurations. They all use the `local` profile, which is configured to use the `application-local.yml` file for configuration. -- Benchmarking (Server): Starts the application with the `dev` profile. -- Benchmarking (Server-Profiles): Starts the application with the `prod` profile. -- Benchmarking (Client): Starts the client separately. This allows to use Angular's live-reload feature. +- `Benchmarking (Server)`: Starts the application with the `dev` profile. +- `Benchmarking (Server-Prod)`: Starts the application with the `prod` profile. +- `Benchmarking (Client)`: Starts the client separately. This allows to use Angular's live-reload feature. We recommend running the server and client separately during development by running `Benchmarking (Server)` (or Server-Prod) and `Benchmarking (Client)`. The application will be available on http://localhost:9000 with Angular's live-reload feature enabled. @@ -105,10 +105,22 @@ This will create a Docker image named `artemis-benchmarking` in the production p To run the Docker image, you can use the docker-compose file `src/main/docker/app.yml`. This will also start a MySQL server. -After starting the containers with `docker compose -f src/main/docker/app.yml up -d`, the application will be available on http://localhost:8080. +After starting the containers with + +``` +docker compose -f src/main/docker/app.yml up -d +``` + +the application will be available on http://localhost:8080. Instead of creating a Docker image, you can use the [latest published Docker image](https://github.com/ls1intum/Artemis-Benchmarking/pkgs/container/artemis-benchmarking) from the GitHub Container Registry. -To start a container with that image, you can use the docker-compose file `docker-compose.yml` by running `docker compose up -d`. This will also start a MySQL server. +To start a container with that image, you can use the docker-compose file `docker-compose.yml` by running + +``` +docker compose up -d +``` + +This will also start a MySQL server. The application will be available on http://localhost:8080. When using this docker-compose file, you can set the environment variables in the files `config/benchmarking.env` and `config/mysql.env`. The published Docker image is not compatible with arm64 processors and will not work on Mac with the M1 processor family. @@ -206,7 +218,7 @@ Each push to the `main` branch triggers the `deploy.yml` workflow. This workflow To add a new Artemis Server to the Benchmarking Tool, changes in four places are necessary. The changes are trivial and should not cause any problems. -1. In the configuration (e.g., `application.yml`), add a new section for the new server. Orientate yourself on the existing servers. See the section "Configuration" for more information. +1. In the configuration (e.g., `application.yml`), add a new section for the new server. Orientate yourself on the existing servers. See the [Configuration](#configuration) for more information. 2. In the server-side enum `ArtemisServer` (`src/main/java/de/tum/cit/ase/util/ArtemisServer.java`), add a new value for the new server. 3. In the `ArtemisConfiguration` class (`src/main/java/de/tum/cit/ase/service/artemis/ArtemisConfiguration.java`), add new fields for the new server. Orientate yourself on the existing servers. 4. In the client-side enum `ArtemisServer` (`src/main/webapp/app/core/util/artemisServer.ts`), add a new value for the new server. It must have the same name as the value in the server-side enum. @@ -239,6 +251,7 @@ Each user has an ID. The ID is used to specify the users that will participate i - If you specify the number of users in the simulation form, the tool will use the users with IDs 1 to n. - If you specify the exact users that will participate in the simulation, you need to specify the IDs of the users. +- See [Creating a Simulation](#creating-a-simulation) for more information. When you add users with patterns, you can additionally check the box `Create users on Artemis`. You will then be able to specify patterns for first name, last name, and email. The tool will try to create the users on Artemis with the specified patterns. This is useful if your Artemis instance does not yet have the necessary amount of test users registered. This feature is only available if an Admin user is specified for the Artemis server. @@ -269,7 +282,7 @@ The Benchmarking Tool stores the credentials of the Artemis users in the databas For security reasons, it is not possible to store the credentials of an admin user of the Artemis production instance in the Benchmarking Tool. Instead, those credentials can be entered when starting a simulation run. They will not be stored in the database and will only be used for the respective simulation run. -If you want to create schedules for a simulation against the Artemis production instance, that is only possible for simulation modes that do not require admin rights. +If you want to create [schedules](#scheduling-simulations) for a simulation against the Artemis production instance, that is only possible for simulation modes that do not require admin rights. The credentials of an _Instructor_ (e.g. for the mode `Existing course, create exam`) can be specified when creating the simulation (or later). **They will be stored in the database!** Make sure to use an account that only has Instructor rights in the course that you want to use for the simulation. @@ -297,6 +310,7 @@ Explanation of the form fields: To run a simulation, find the simulation in the list of simulations and click the "Start Run" button. The new run will be added to the list of runs of the simulation. Click on the run to see the details. +If the simulation is configured to run against production, you will need to confirm your choice and - depending on the mode - specify admin credentials through a dialog (see [Artemis User Management](#artemis-user-management) for more information). The icon next to the run indicates the status of the run: @@ -336,6 +350,35 @@ The results are displayed in the detail view of the run. The metrics are also av If the simulation is running against an Artemis instance that uses the Integrated Code Lifecycle setup, the tool will fetch the CI status after the simulation. The CI status is displayed in the detail view of the run. It includes the number of builds and the average builds per minute. +### Scheduling Simulations + +The Benchmarking Tool can be used to schedule simulations. This is useful if you want to run simulations at a specific time or at regular intervals. + +To schedule a simulation, click on the calendar icon of the respective simulation. +In the dialog that opens, you will see a list of existing schedules for the simulation. +Click on "Create Schedule" to create a new schedule. +In the form that opens, you can specify the following fields: + +- `Cycle`: The repetition cycle of the schedule. The cycle can be `Daily` or `Weekly`. +- `From`: The start date of the time period in which the schedule will be active. +- `To`: The end date of the time period in which the schedule will be active. When reached, the schedule will be automatically deleted. If omitted, the schedule will be active indefinitely. +- `Time of Day`: The time of day at which the simulation will be started. +- `Day of Week`: The day of the week on which the simulation will be started. This field is only available if the cycle is `Weekly`. + +After creating the schedule, it will be added to the list of schedules for the simulation. +You can edit or delete the schedule by clicking on the respective icons. + +**Subscribing to a Schedule** +Click on the Bell icon of the respective schedule to subscribe to the schedule. You can specify your email address here. +After subscribing, you will receive an email notification containing a summary of the simulation results after every scheduled run. +To unsubscribe, click on the respective link in the email. + +**Particularities for the Artemis production instance:** + +- Simulations against production that require admin rights cannot be scheduled. +- For simulations that require instructor right, the credentials need to be specified before creating the schedule. +- See [Artemis User Management](#artemis-user-management) for more information. + [JHipster Homepage and latest documentation]: https://www.jhipster.tech [JHipster 8.1.0 archive]: https://www.jhipster.tech/documentation-archive/v8.1.0 [Using JHipster in development]: https://www.jhipster.tech/documentation-archive/v8.1.0/development/