Skip to content

Latest commit

 

History

History
211 lines (165 loc) · 13.3 KB

SETUP.md

File metadata and controls

211 lines (165 loc) · 13.3 KB

Setup Guide for Artemis

In this guide you learn how to setup the development environment of Artemis. Artemis is based on JHipster, i.e. Spring Boot development on the application server using Java 14, and TypeScript development on the application client in the browser using Angular and Webpack. To get an overview of the used technology, have a look at https://jhipster.github.io/tech-stack and other tutorials on the JHipster homepage.

You can find tutorials how to setup JHipster in an IDE (IntelliJ IDEA Ultimate is recommended) on https://jhipster.github.io/configuring-ide. Note that the Community Edition of IntelliJ IDEA does not provide Spring Boot support (see the comparison matrix). Before you can build Artemis, you must install and configure the following dependencies/tools on your machine:

  1. Java JDK: We use Java (>= JDK 14) to develop and run the Artemis application server which is based on Spring Boot.
  2. MySQL Database Server 8: Artemis uses Hibernate to store entities in a MySQL database. Download and install the MySQL Community Server (8.0.x) and configure the 'root' user with an empty password. (In case you want to use a different password, make sure to change the value in application-dev.yml and in liquibase.gradle). The required Artemis scheme will be created / updated automatically at startup time of the server application. Alternatively, you can run the MySQL Database Server inside a Docker container using e.g. docker-compose -f src/main/docker/mysql.yml up
  3. Node.js: We use Node (>=13.12.0) to compile and run the client Angular application. Depending on your system, you can install Node either from source or as a pre-packaged bundle.
  4. Yarn: We use Yarn 1.x (>=1.22.0) to manage client side Node dependencies. Depending on your system, you can install Yarn either from source or as a pre-packaged bundle. To do so, please follow the instructions on the Yarn installation page.

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.in.www1.artemis.ArtemisApp. Before the application runs, you have to configure the file application-artemis.yml in the folder src/main/resources/config.

artemis:
    repo-clone-path: ./repos/
    repo-download-clone-path: ./repos-download/
    encryption-password: <encrypt-password>     # arbitrary password for encrypting database values
    user-management:
        use-external: true
        external:
            url: https://jira.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://bitbucket.ase.in.tum.de
        user: <username>    # e.g. ga12abc
        password: <password>
        secret: <token>                 # VCS API token giving Artemis full Admin access. Not needed for Bamboo+Bitbucket
        ci-token: <token from the CI>   # Token generated by the CI (e.g. Jenkins) for webhooks from the VCS to the CI. Not needed for Bamboo+Bitbucket
    continuous-integration:
        url: https://bamboo.ase.in.tum.de
        user: <username>    # e.g. ga12abc
        password: <password>
        vcs-application-link-name: LS1 Bitbucket Server     # If the VCS and CI are directly linked (normally only for Bitbucket + Bamboo)
        empty-commit-necessary: true                        # Do we need an empty commit for new exercises/repositories in order for the CI to register the repo
        # Hash/key of the ci-token, equivalent e.g. to the ci-token in version-control
        # Some CI systems, like Jenkins, offer a specific token that gets checked against any incoming notifications
        # from a VCS trying to trigger a build plan. Only if the notification request contains the correct token, the plan
        # is triggered. This can be seen as an alternative to sending an authenticated request to a REST API and then
        # triggering the plan.
        # In the case of Artemis, this is only really needed for the Jenkins + GitLab setup, since the GitLab plugin in
        # Jenkins only allows triggering the Jenkins jobs using such a token. Furthermore, in this case, the value of the
        # hudson.util.Secret is stored in the build plan, so you also have to specify this encrypted string here and NOT the actual token value itself!
        # You can get this by GETting any job.xml for a job with an activated GitLab step and your token value of choice.
        secret-push-token: <token hash>
        # Key of the saved credentials for the VCS service
        # Bamboo: not needed
        # 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
        # Bamboo: not needed
        # 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.
        # Bamboo: The token value you use for the Server Notification Plugin
        # Jenkins: The token value you use for the Server Notification Plugin and is stored under the notification-token credential above
        authentication-token: <token>
    lti:
        id: artemis_lti
        oauth-key: artemis_lti_key
        oauth-secret: <secret>    # only important for online courses on the edX platform, can typically be ignored
        user-prefix_edx: edx_
        user-prefix_u4i: u4i_
        user-group-name_edx: edx
        user-group-name_u4i: u4i
    git:
        name: Artemis
        email: [email protected]
    automatic-text:
        embedding-url: http://localhost:8000/embed
        embedding-chunk-size: 50
        clustering-url: http://localhost:8000/cluster
        segmentation-url: http://localhost:8080/segment
        secret: null

Change all entries with <...> with proper values, e.g. your TUM Online account credentials to connect to the given instances of JIRA, Bitbucket and Bamboo. Alternatively, you can connect to your local JIRA, Bitbucket and Bamboo 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, either with Jenkins and GitLab or Bamboo, Bitbucket and Jira. Be careful that you don't commit changes in this file. Best practice is to specify that your local git repository ignores this file or assumes that this file is unchanged.

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

One typical problem in the development setup is that an exception occurs during the database initialization. Artemis uses Liquibase to automatically upgrade the database scheme after changes to the data model. This ensures that the changes can also be applied to the production server. In case you encounter errors with liquibase checksum values, run the following command in your terminal / command line:

./gradlew liquibaseClearChecksums

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

Important: 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 JIRA, Bitbucket and Bamboo:

--spring.profiles.active=dev,bamboo,bitbucket,jira,artemis

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,bamboo,bitbucket,jira,artemis

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

dev,bamboo,bitbucket,jira,artemis

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,bamboo,bitbucket,jira,artemis'

As an alternative, you might want to use Jenkins and Gitlab with an internal user management in Artemis, then you would use the profiles:

dev,jenkins,gitlab,artemis

Client Setup

After installing Node and Yarn, you should be able to run the following command to install development tools and dependencies. You will only need to run this command when dependencies change in package.json.

yarn install

To start the client application in the browser, use the following command:

yarn start

This compiles TypeScript code to JavaScript code, starts the hot module replacement feature in Webpack (i.e. whenever you change a TypeScript file and save, the client is automatically reloaded with the new code) and will start the client application in your browser on http://localhost:9000. If you have activated the JIRA profile (see above in Server Setup) and if you have configured application-artemis.yml correctly, then you should be able to login with your TUM Online account.

For more information, review Working with Angular. For further instructions on how to develop with JHipster, have a look at Using JHipster in development.

Customize your Artemis instance

You can define the following custom assets for Artemis to be used instead of the TUM defaults:

  • The logo next to the "Artemis" heading on the navbar → ${artemisRunDirectory}/public/images/logo.png
  • The favicon → ${artemisRunDirectory}/public/images/favicon.ico
  • The privacy statement HTML → ${artemisRunDirectory}/public/content/privacy_statement.html
  • The contact email address in the application-{dev,prod}.yml configuration file under the key info.contact
  • The imprint link in the application-{dev,prod}.yml configuration file under the key info.imprint

Alternative: Using docker-compose

A full functioning development environment can also be set up using docker-compose:

  1. Install docker and docker-compose
  2. Configure the credentials in application-artemis.yml in the folder src/main/resources/config as described above
  3. Run docker-compose up
  4. Go to http://localhost:9000

The client and the server will run in different containers. As yarn is used with its live reload mode to build and run the client, any change in the client's codebase will trigger a rebuild automatically. In case of changes in the codebase of the server one has to restart the artemis-server container via docker-compose restart artemis-server.

(Native) Running and Debugging from IDEs is currently not supported.

Get a shell into the containers:

  • app container: docker exec -it $(docker-compose ps -q artemis-app) sh
  • mysql container: docker exec -it $(docker-compose ps -q artemis-mysql) mysql

Other useful commands:

  • Stop the server: docker-compose stop artemis-server (restart via docker-compose start artemis-server)
  • Stop the client: docker-compose stop artemis-client (restart via docker-compose start artemis-client)

Text Assessment Clustering Service

The semi-automatic text assessment relies on the text assessment clustering (TAC) service, which is currently closed-source. (Contact @jpbernius if you require access.)

To enable automatic text assessments, special configuration is required:

Enable the automaticText Spring profile:

--spring.profiles.active=dev,bamboo,bitbucket,jira,artemis,automaticText

Configure API Endpoints:

The TAC service is running on a dedicated machine and is adressed via HTTP. We need to extend the configuration in the file src/main/resources/config/application-artemis.yml like so:

artemis:
  # ...
  automatic-text:
    embedding-url: http://localhost:8000/embed
    embedding-chunk-size: 50
    clustering-url: http://localhost:8000/cluster
    secret: null