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 frontend project
• Setting up Jophiel
• Setting up Uriel
• Setting up Jerahmeel
• Running the microservices
• Optional: setting up Sandalphon (staging)
• Optional: setting up Sandalphon (locally)
• Optional: setting up Sealtiel
• Miscellaneous
• Troubleshooting

Prerequisites

• Java 8 JDK
  • Earlier or later versions of Java might not work.
• MySQL 5.7
  • Earlier or later versions of MySQL might not work.
• 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 (except for Docker errors, see the Troubleshooting section below).

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.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.

Setting up Jophiel

1. Create a new local database called judgels_jophiel.

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

3. Copy the example config:

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

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

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

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

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

8. Go to Judgels repository root.

9. Import the seed data (seeds/judgels_jophiel.sql) to the database.

10. Verify that there data 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.

Additionally, untar the tar.gz files from seeds/jerahmeel/var/data/* to jerahmeel-dist/var/data/, to be able to see submission files.

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 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.

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

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

7. Make sure that you can log in successfully.

Congratulations, you have successfully run Judgels from source!

Optional: setting up Sandalphon (staging)

To be able to view problems, you can connect your Uriel and Jerahmeel to TOKI's staging Sandalphon as follows:

1. Go to Uriel directory (judgels-backends/uriel).

2. Open the config file uriel-dist/var/conf/uriel.yml.

3. Under uriel:, set the sandalphon: keys as follows:

   sandalphon:
     baseUrl: https://sandalphon.tlx-staging.toki.id
     clientJid: JIDSACL-uriel
     clientSecret: sandalphon-staging
   

4. Verify that you can view the problems in the contests.

5. Do the similar steps for Jerahmeel.

Optional: setting up Sandalphon (locally)

You can also run Sandalphon from source locally.

1. Create a new local database called judgels_sandalphon.

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

3. Copy the example config:

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

4. Open the config file application.conf.

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

6. Run Sandalphon locally, run ../gradlew runPlay.

7. To connect Uriel and Sandalphon, edit the config file judgels-backends/uriel/uriel-dist/var/conf/uriel.yml. Under uriel:, set the sandalphon: keys as follows:

   sandalphon:
     baseUrl: https://localhost:9002
     clientJid: JIDSACL-uriel-local
     clientSecret: sandalphon-local
   

8. Now, you can access Sandalphon at localhost:9002 to add problem and insert into contest.

9. Do similar steps for Jerahmeel.

Optional: setting up Sealtiel

To be able to submit solutions, you can connect your Uriel to TOKI's staging Sealtiel as follows:

NOTE: Sealtiel in staging might be down from time to time for resource saving. These steps MIGHT FAIL.

1. Go to Uriel directory (judgels-backends/uriel).

2. Open the config file uriel-dist/var/conf/uriel.yml.

3. Under uriel:, set the sealtiel: keys as follows:

   sealtiel:
     baseUrl: https://sealtiel.tlx-staging.toki.id
     clientJid: JIDSECL-uriel
     clientSecret: sealtiel-staging
   

4. Verify that you can submit solutions in the contests.

5. Do similar steps for Jerahmeel.

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.

• java.lang.IllegalStateException: Could not find a valid Docker environment. when running ./gradlew check

  • This is due to the Docker not set up yet. Docker is required for running Sealtiel integration tests. This is not blocking if you don't want to install Docker.

• java.sql.SQLException: Unable to load authentication plugin 'caching_sha2_password'. when running ../gradlew dbMigrate

  • Please make sure that you are using MySQL 5.7 (and not later versions)
  • Or, follow this guide: https://stackoverflow.com/a/50433762

• 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.