Dev's Guide: Running from source

This section explains how to run the Judgels platform locally from source, with default configuration. This is a good starting point for new developers to ensure that they can run Judgels on their machine.

• Prerequisites
• Setting up backend project
• Setting up Jophiel
• Setting up Uriel
• Setting up Jerahmeel
• Setting up Sandalphon
• Importing seed data
• Setting up frontend project
• Running the microservices
• Miscellaneous
• Troubleshooting

Prerequisites

• Java 8/11 JDK
• MySQL 8
• Yarn 1.3+
• Docker
• IntelliJ IDEA
  • Community Edition is sufficient.

Setting up backend project

1. Go to the backend directory (judgels-backends).

2. Run: ./gradlew check

   This will download all required JAR dependencies, and run all unit and integration tests. Note that it may take quite a while for the first time.

3. Make sure the tests pass before moving on to the next sections.

4. Create a new local database called judgels.

Setting up Jophiel

1. Go to Jophiel directory (judgels-backends/jophiel).

2. Copy the example config:

   cp jophiel-dist/var/conf/jophiel.yml.example jophiel-dist/var/conf/jophiel.yml
   

3. Open the config file jophiel-dist/var/conf/jophiel.yml.

4. Under database:, modify url, user, and password as necessary.

5. Run database migration: ../gradlew dbMigrate.

6. Verify that there are tables generated in the database.

Setting up Uriel

The steps are similar to Jophiel's above. Just replace all occurrences of jophiel to uriel.

Setting up Jerahmeel

The steps are similar to Jophiel's above. Just replace all occurrences of jophiel to jerahmeel.

Setting up Sandalphon

1. Go to Sandalphon directory (judgels-backends/sandalphon).

2. Copy the example config:

   cp sandalphon-app/conf/application_default.conf sandalphon-app/conf/application.conf
   

3. Open the config file application.conf.

4. Under db.default, modify url, username, and password as necessary.

5. Run Sandalphon server:

   • Go to judgels-backends/sandalphon.
   • Run: ../gradlew runPlay.
   • By default, it will listen to port 9002.
   • Open http://localhost:9002

6. Sandalphon will run the database migration automatically.

7. Verify that there are tables generated in the database.

Importing seed data

1. Import the seed data (seeds/judgels.sql) to the database.
2. Untar the tar.gz files from seeds/jerahmeel/var/data/* to jerahmeel-dist/var/data/, to be able to see submission files.
3. Untar the tar.gz files from seeds/sandalphon/var/data/* to sandalphon-app/var/data/, to be able to see problems / lessons.
4. Verify that there data generated in the database.

Setting up frontend project

1. Go to Raphael directory (judgels-frontends/raphael).

2. Copy the example config:

   cp public/var/conf/raphael.js.example public/var/conf/raphael-v4.js
   

3. Run: yarn && yarn test

   This will download all required NPM dependencies and run the tests. Note that it may take quite a while for the first time.

4. Make sure the tests pass before moving on to the next sections.

Running the microservices

1. Run Jophiel server:

   • Go to judgels-backends/jophiel.
   • Run: ../gradlew run.
   • By default, it will listen to port 9001.
   • To make sure that it is running correctly, hit the version endpoint: http://localhost:9001/api/v2/version. It should return the current version string.

2. Similary, run Uriel server. By default, it will listen to port 9004.

3. Similary, run Jerahmeel server. By default, it will listen to port 9005.

4. Run Sandalphon server:

   • Go to judgels-backends/sandalphon.
   • Run: ../gradlew runPlay.
   • By default, it will listen to port 9002.

5. Run Raphael server:

   • Go to judgels-frontends/raphael.
   • Run: yarn start.
   • By default, it will open your default web browser and navigate to http://localhost:3000.

6. Make sure that you can see the Judgels homepage with no errors.

7. Log in to Judgels using superadmin account (username: superadmin, password: superadmin).

8. Make sure that you can log in successfully.

Congratulations, you have successfully run Judgels from source!

Miscellaneous

• The seed data contains a superadmin and 6 users with the following usernames: andi, budi, caca, dudi, emir, fuad. Passwords are equal to the usernames.

Troubleshooting

• Error: EMFILE: too many open files, watch on macOS when running yarn test

  • To fix this, run:

    brew install watchman
    

    See https://github.com/facebook/create-react-app/issues/4540 for more details.

• error: method transform in class Lists cannot be applied to given types when running ./gradlew check

  • This is compilation error when using Java version 1.8.0_25, not sure which exact minimum version that compiles successfully but Java version 1.8.0_201 works.