Server Setup

To start the Artemis application server from the development environment, first import the project into IntelliJ and then make sure to install the Spring Boot plugins to run the main class de.tum.cit.aet.artemis.ArtemisApp. Before the application runs, you have to change some configuration options. You can change the options directly in the file application-artemis.yml in the folder src/main/resources/config. However, you have to be careful that you do not accidentally commit your password. Therefore, we strongly recommend, to create a new file application-local.yml in the folder src/main/resources/config which is ignored by default. You can override the following configuration options in this file.

artemis:
    repo-clone-path: ./repos/
    legal-path: ./legal/
    repo-download-clone-path: ./repos-download/
    bcrypt-salt-rounds: 11   # The number of salt rounds for the bcrypt password hashing. Lower numbers make it faster but more unsecure and vice versa.
                             # Please use the bcrypt benchmark tool to determine the best number of rounds for your system. https://github.com/ls1intum/bcrypt-Benchmark
    user-management:
        use-external: true
        password-reset:
             credential-provider: <provider> # The credential provider which users can log in though (e.g. TUMonline)
             links: # The password reset links for different languages
                 en: '<link>'
                 de: '<link>'
        external:
            url: https://external.ase.in.tum.de
            user: <username>    # e.g. ga12abc
            password: <password>
            admin-group-name: tumuser
        ldap:
            url: <url>
            user-dn: <user-dn>
            password: <password>
            base: <base>
    version-control:
        url: https://gitlab.ase.in.tum.de
        user: <username>    # e.g. ga12abc
        password: <password>
        token: <token>                 # VCS API token giving Artemis full Admin access.
    continuous-integration:
        url: https://jenkins.ase.in.tum.de
        user: <username>    # e.g. ga12abc
        token: <token>      # Enter a valid token generated by the CI system or leave this empty to use the fallback authentication user + password
        password: <password>
        # Key of the saved credentials for the VCS service
        # Jenkins: You have to specify the key from the credentials page in Jenkins under which the user and
        #          password for the VCS are stored
        vcs-credentials: <credentials key>
        # Key of the credentials for the Artemis notification token
        # Jenkins: You have to specify the key from the credentials page in Jenkins under which the notification token is stored
        notification-token: <credentials key>
        # The actual value of the notification token to check against in Artemis. This is the token that gets send with
        # every request the CI system makes to Artemis containing a new result after a build.
        # Jenkins: The token value you use for the Server Notification Plugin and is stored under the notification-token credential above
        authentication-token: <token>
    git:
        name: Artemis
        email: artemis@in.tum.de
    athena:
         # If you want to use Athena, look at the dedicated section in the config.

Change all entries with <...> with proper values, e.g. your TUM Online account credentials to connect to the given instances. Alternatively, you can connect to your local instances. It’s not necessary to fill all the fields, most of them can be left blank. Note that there is additional information about the setup for programming exercises provided:

Note

Be careful that you do not commit changes to application-artemis.yml. To avoid this, follow the best practice when configuring your local development environment:

  1. Create a file named application-local.yml under src/main/resources/config.

  2. Copy the contents of application-artemis.yml into the new file.

  3. Update configuration values in application-local.yml.

By default, changes to application-local.yml will be ignored by git so you don’t accidentally share your credentials or other local configuration options. The run configurations contain a profile local at the end to make sure the application-local.yml is considered. You can create your own configuration files application-<name>.yml and then activate the profile <name> in the run configuration if you need additional customizations.

If you use a password, you need to adapt it in gradle/liquibase.gradle.

Run the server via Docker

Artemis provides a Docker image named ghcr.io/ls1intum/artemis:<TAG/VERSION>.
The current develop branch is provided by the tag develop.
The latest release is provided by the tag latest.
Specific releases like 5.7.1 can be retrieved as ghcr.io/ls1intum/artemis:5.7.1.
Branches tied to a pull request can be obtained by using the tag PR-<PR NUMBER>.

Dockerfile

You can find the latest Artemis Dockerfile at docker/artemis/Dockerfile.

  • The Dockerfile has multiple stages: A builder stage, building the .war file, an optional external_builder stage to import a pre-built .war file, a war_file stage to choose between the builder stages via build argument and a runtime stage with minimal dependencies just for running artemis.

  • The Dockerfile defines three Docker volumes (at the specified paths inside the container):

    • /opt/artemis/config:

      This can be used to store additional configurations of Artemis in YAML files. The usage is optional, and we recommend using the environment files for overriding your custom configurations instead of using src/main/resources/application-local.yml as such an additional configuration file. The other configurations like src/main/resources/application.yml, … are built into the .war file and therefore are not needed in this directory.

      Tip

      Instead of mounting this config directory, you can also use environment variables for the configuration as defined by the Spring relaxed binding. You can either place those environment variables directly in the environment section, or create a .env-file. When starting an Artemis container directly with the Docker-CLI, an .env-file can also be given via the --env-file option.

      To ease the transition of an existing set of YAML configuration files into the environment variable style, a helper script can be used.

    • /opt/artemis/data:

      This directory should be used for any data (e.g., local clone of repositories). This is preconfigured in the docker Java Spring profile (which sets the following values: artemis.repo-clone-path, artemis.repo-download-clone-path, artemis.course-archives-path, artemis.submission-export-path artemis.legal-path, and artemis.file-upload-path).

    • /opt/artemis/public/content:

      This directory will be used for branding. You can specify a favicon here.

  • The Dockerfile assumes that the mounted volumes are located on a file system with the following locale settings (see #4439 for more details):

    • LC_ALL en_US.UTF-8

    • LANG en_US.UTF-8

    • LANGUAGE en_US.UTF-8

Warning

ARM64 Image builds might run out of memory if not provided with enough memory and/or swap space. On a Apple M1 we had to set the Docker Desktop memory limit to 12GB or more.

Debugging with Docker

The Docker containers have the possibility to enable Java Remote Debugging via Java environment variables.
Java Remote Debugging lets you use your preferred debugger connected to port 5005. For IntelliJ, you can use the Remote Java Debugging for Docker profile shipped in the git repository.

With the following Java environment variable, you can configure the Remote Java Debugging inside a container:

_JAVA_OPTIONS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"
This is already pre-set in the Docker Compose Artemis-Dev-MySQL Setup.
For issues at the startup, you might have to suspend the java command until a Debugger is connected. This is possible by setting suspend=y.

Run the server via a run configuration in IntelliJ

The project comes with some pre-configured run / debug configurations that are stored in the .idea directory. When you import the project into IntelliJ the run configurations will also be imported.

The recommended way is to run the server and the client separately. This provides fast rebuilds of the server and hot module replacement in the client.

  • Artemis (Server): The server will be started separated from the client. The startup time decreases significantly.

  • Artemis (Client): Will execute npm install and npm run start. The client will be available at http://localhost:9000/ with hot module replacement enabled (also see Client Setup).

Other run / debug configurations

  • Artemis (Server & Client): Will start the server and the client. The client will be available at http://localhost:8080/ with hot module replacement disabled.

  • Artemis (Server, Jenkins & GitLab): The server will be started separated from the client with the profiles dev,jenkins,gitlab,artemis.

  • Artemis (Server with Integrated Code Lifecycle): The server will be started separated from the client with the profiles dev,localci,localvc,artemis. To use this configuration, Docker needs to be running on your system as Integrated Code Lifecycle uses it to run build jobs.

  • Artemis (Server, LocalVC & LocalCI, Athena): The server will be started separated from the client with athena profile and Local VC / CI enabled (see Athena Service).

Run the server with Spring Boot and Spring profiles

The Artemis server should startup by running the main class de.tum.cit.aet.artemis.ArtemisApp using Spring Boot.

Note

Artemis uses Spring profiles to segregate parts of the application configuration and make it only available in certain environments. For development purposes, the following program arguments can be used to enable the dev profile and the profiles for Jenkins and Gitlab:

--spring.profiles.active=dev,jenkins,gitlab,artemis,scheduling

If you use IntelliJ (Community or Ultimate) you can set the active profiles by

  • Choosing Run | Edit Configurations...

  • Going to the Configuration Tab

  • Expanding the Environment section to reveal VM Options and setting them to -Dspring.profiles.active=dev,jenkins,gitlab,artemis,scheduling

Set Spring profiles with IntelliJ Ultimate

If you use IntelliJ Ultimate, add the following entry to the section Active Profiles (within Spring Boot) in the server run configuration:

dev,jenkins,gitlab,artemis,scheduling

Run the server with the command line (Gradle wrapper)

If you want to run the application via the command line instead, make sure to pass the active profiles to the gradlew command like this:

./gradlew bootRun --args='--spring.profiles.active=dev,jenkins,gitlab,artemis,scheduling'