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

   • If you get Error: EMFILE: too many open files, watch on macOS, run:

     brew install watchman
     

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

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.

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

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

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

6. 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 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-staging
     clientSecret: sandalphon-staging
   

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

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-legacy/sandalphon).

3. Copy the example config:

   cp conf/application_default.conf 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 runPlayBinary.

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

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

Optional: setting up Sealtiel

To be able to submit solutions, you can connect your Uriel to TOKI's staging Sealtiel 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 sealtiel: keys as follows:

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

4. Verify that you can submit solutions in the contests. Note that currently, your solutions won't be graded yet.

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

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

  • This is due to the Docker not setup yet—we can ignore Docker errors for now.

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