Welcome to Judgels’ documentation!¶

Installing Jophiel¶

First, follow the main Judgels setup instructions if you haven’t. This means that you should have installed Jophiel by running

judgels pull jophiel

and should have modified the common configuration keys in conf/application.conf and conf/db.conf.

Configuring Jophiel¶

This section will cover the specific configuration keys for Jophiel.

play.mailer.{host, port, ssl, user, password}

SMTP credentials configuration for sending user account related emails.

jophiel.idToken.key.private

An RSA private key for generating ID token required for OpenID Connect protocol. You can generate one using ssh-keygen command. Make sure to select RSA as the algorithm.

jophiel.client.{labels, targets}

The list of public Judgels Play applications you want to inform to the users on the welcome page. This is useful in order to users that have just logged in not to get lost in SSO. Put the list of URLs in targets, and the corresponding link labels in labels.

noreply.{name, email}

The name and email of “noreply” user for sending user account related emails.

aws.avatar.s3.use

Whether to use AWS as the storage for user avatars. If set to true, then the rest of the aws.avatar.* keys below should be modified accordingly.

aws.avatar.s3.{bucket.name, bucket.regionId}

The bucket name and bucket region ID for the S3 storage.

aws.avatar.cloudFront.baseUrl

The base URL for CloudFront for the S3 storage. You must set up CloudFront.

aws.key.use

Whether a pair of keys must be used for connecting to S3. For example, if the EC2 that hosts Jophiel has been associated to a role that has permission for connecting to S3, then this value should be false.

aws.key.{access, secret}

If a pair of keys must be used, then these are the access and secret keys, respectively.

recaptcha.registration.use

Whether to use reCAPTCHA for the registration form.

recaptcha.registration.key.{site, secret}

If reCAPTCHA is used, then these are the site and secret keys, respectively.

Running Jophiel¶

See Running Judgels Play applications.

Adding initial admin¶

Jophiel has been successfully installed and configuring. Now, we need to have a user with admin role.

1. Open Jophiel. You will be presented with a login screen. Choose Register.
2. Register a user to be assigned as admin.
3. Validate the user by following the validation email. If you don’t have a valid SMTP server setup, you can do the validation manually by setting the emailVerified column to 1 in the corresponding row in the jophiel_user_email table.
4. Manually assign this user as admin, by setting the roles column to user,admin in the corresponding row in the jophiel_user table.
5. Log in to Jophiel. Verify that you can view the Users menu on the left.

User roles¶

There are two roles in Jophiel:

User

A normal user.

Admin

An administrator. Can do anything, for example, user CRUD and Jophiel client CRUD.

Adding Jophiel clients¶

A Jophiel client is an application that uses Jophiel for authentication and authorization. To add a Jophiel client, perform these steps.

1. Open Jophiel and click Clients menu on the left.

2. Click Create New.

3. Fill in these values:

   Client Name

   The client name. For example: Sandalphon #1.

   Application Type

   Choose Web Server.

   Redirect URIs

   Fill <client base URL>/verify. For example: http://localhost:9002/verify.

   Scopes

   For the current version, choose OPENID and OFFLINE_ACCESS.

4. Click Create New.

A Jophiel client has been successfully created with the corresponding client JID and client secret. The client can then connect to Jophiel using the JID and secret.

Installing dependencies¶

As described in the previous section, Sandalphon depends on Jophiel, Sealtiel, and Gabriel. Make sure you have installed them.

Installing Sandalphon¶

First, follow the main Judgels setup instructions if you haven’t. This means that you should have installed Sandalphon by running

judgels pull sandalphon

and should have modified the common configuration keys in conf/application.conf and conf/db.conf.

Configuring Sandalphon¶

First, let’s configure the dependencies so that they can work with Sandalphon. During the configuration, we will set some configuration keys in Sandalphon’s conf/application.conf.

1. Add Sandalphon as a client in Jophiel. Then, assign the client JID and secret values to Sandalphon’s jophiel.clientJid and jophiel.clientSecret. Assign jophiel.baseUrl to Jophiel’s base URL.
2. Add Sandalphon as a client in Sealtiel. Then, assign the client JID and secret values to Sandalphon’s sealtiel.clientJid and sealtiel.clientSecret. Assign sealtiel.baseUrl to Sealtiel’s base URL.
3. Add Gabriel as a client in Sealtiel. Then, assign the client JID and secret values to Gabriel‘s sealtiel.clientJid and sealtiel.clientSecret. Assign Gabriel‘s sealtiel.baseUrl to Sealtiel’s base URL. Finally, assign the client JID to Sandalphon‘s sealtiel.gabrielClientJid.
4. Add acquaintances between Sandalphon and Gabriel, vice-versa, in Sealtiel.

Running Sandalphon¶

See Running Judgels Play applications.

Configuring Gabriel¶

Finally, add Gabriel as a Sandalphon’s grader. This is required to allow Gabriel to fetch test cases from Sandalphon. It is worth noting that Gabriel connects directly to Sandalphon for fetching test cases, not via Sealtiel, since this should be a synchronous operation.

1. Open Sandalphon and click Graders menu on the left.

2. Click Create New.

3. Fill in these values:

   Name

   The grader name. For example: Gabriel #1.

4. Click Create New.

Assign the JID and secret you obtained to Gabriel’s sandalphon.clientJid and sandalphon.clientSecret. Assign Gabriel’s sandalphon.baseUrl to Sandalphon’s base URL.

Adding initial admin¶

Sandalphon has been successfully installed and configured. Now, we need to have a user with admin role.

1. Find your user JID in Jophiel.
2. Set the roles column to user,admin in the corresponding row (that contains your user JID) in the sandalphon_user table.
3. Re-log in to Sandalphon. Verify that you can view the Clients menu on the left.

Installing RabbitMQ¶

Sealtiel internally uses RabbitMQ. So, it must be installed first. Follow the installation instruction here: Downloading and Installing RabbitMQ. Make sure you install at least version 3.5.x.

After you installed RabbitMQ, enable the management plugin:

sudo rabbitmq-plugins enable rabbitmq_management

If everything goes well, you should be able to open the management web interface on http://localhost:15672. You can login with the default user (username: guest, password: guest).

Configuring RabbitMQ¶

For security, you must change the guest user password.

1. Log in to the management web interface.
2. Click Admin tab.
3. Click guest user.
4. On the Update this user section, enter new password.
5. Click Update user.

Installing Sealtiel¶

First, follow the main Judgels setup instructions if you haven’t. This means that you should have installed Sealtiel by running

judgels pull sealtiel

and should have modified the common configuration keys in conf/application.conf and conf/db.conf.

Configuring Sealtiel¶

This section will cover the specific configuration keys for Sealtiel.

sealtiel.{username, password}

The credentials for logging in to Sealtiel. Note that Sealtiel does not use Jophiel for logging in.

rabbitmq.{host, port, username, password, virtualHost}

The credentials for connecting to RabbitMQ. In most cases, you only need to change rabbitmq.password to the new guest password.

Running RabbitMQ¶

Run

sudo rabbitmqctl start_app

If RabbitMQ was installed correctly, this will be output:

                RabbitMQ 3.5.X. Copyright (C) 2007-2014 GoPivotal, Inc.
##  ##      Licensed under the MPL.  See http://www.rabbitmq.com/
##  ##
##########  Logs: /usr/local/var/log/rabbitmq/rabbit@localhost.log
######  ##        /usr/local/var/log/rabbitmq/rabbit@localhost-sasl.log
##########
            Starting broker... completed with X plugins.

Running Sealtiel¶

See Running Judgels Play applications.

To check whether Sealtiel can connect to RabbitMQ, choose the Connection menu in Sealtiel’s left sidebar. The connection status will be shown.

Adding Sealtiel clients¶

A Sealtiel client is an application that uses Sealtiel as a bridge for sending and receiving asynchronous messages. Since Sealtiel is currently only used for sending and receiving grading requests and responses, there are only two kinds of applications that use Sealtiel: Gabriel and the applications that can request grading (Sandalphon, Uriel, and Jerahmeel).

To add a Sealtiel client, perform these steps.

1. Open Sealtiel and click Clients menu on the left.

2. Click Create New.

3. Fill in these values:

   Name

   The client name. For example: Uriel #2.

4. Click Create New.

A Sealtiel client has been successfully created with the corresponding client JID and client secret. The client can then connect to Sealtiel using the JID and secret.

Adding acquaintances¶

For client A to be able to send message to client B, client B must registered as client A’s “acquaintance”. Think of acquaintance as a directed edge between clients.

To add acquaintances to a Sealtiel client, perform these steps.

1. Open Sealtiel and click Clients menu on the left.
2. Click the Enter icon on the rightmost column of the corresponding client row.
3. Add the client name(s) as a new acquaintance.

For example, when setting up Sandalphon and Gabriel to work together, you must:

• Add Sandalphon and Gabriel as Sealtiel clients.
• Add Gabriel as Sandalphon’s acquaintance.
• Add Sandalphon as Gabriel’s acquaintance.

Watching messages¶

You can watch the message flow between clients in the Queues tab on the management web interface.

Installing dependencies¶

As described in the previous section, Sandalphon depends on Jophiel, Sandalphon, Sealtiel, and Gabriel. Make sure you have installed them.

Installing Uriel¶

First, follow the main Judgels setup instructions if you haven’t. This means that you should have installed Uriel by running

judgels pull uriel

and should have modified the common configuration keys in conf/application.conf and conf/db.conf.

Configuring Uriel¶

First, let’s configure the dependencies so that they can work with Uriel. During the configuration, we will set some configuration keys in Uriel’s conf/application.conf.

1. Add Uriel as a client in Jophiel. Then, assign the client JID and secret values to Uriel’s jophiel.clientJid and jophiel.clientSecret. Assign jophiel.baseUrl to Jophiel’s base URL.
2. Add Uriel as a client in Sealtiel. Then, assign the client JID and secret values to Uriel’s sealtiel.clientJid and sealtiel.clientSecret. Assign sealtiel.baseUrl to Sealtiel’s base URL.
3. Add Uriel as a client in Sandalphon. Then, assign the client JID and secret values to Uriel’s sandalphon.clientJid and sandalphon.clientSecret. Assign sandalphon.baseUrl to Sandalphon’s base URL.
4. Add Gabriel as a client in Sealtiel. Then, assign the client JID and secret values to Gabriel‘s sealtiel.clientJid and sealtiel.clientSecret. Assign Gabriel‘s sealtiel.baseUrl to Sealtiel’s base URL. Finally, assign the client JID to Uriel‘s sealtiel.gabrielClientJid.
5. Add acquaintances between Uriel and Gabriel, vice-versa, in Sealtiel.

The rest of configuration keys are:

aws.{teamAvatar, submission, file}.s3.use

Whether to use AWS as the storage for {team avatars, submission files, contest files}. If set to true, then the rest of the aws.{teamAvatar, submission, file}.* keys below should be modified accordingly.

aws.{teamAvatar, submission, file}.s3.bucket.name

The bucket name for the S3 storage.

aws.{teamAvatar, submission, file}.s3.bucket.regionId

The bucket region ID for the S3 storage. If not present, aws.global.s3.bucket.regionId will be used.

aws.teamAvatar.cloudFront.baseUrl

The base URL for CloudFront for the S3 storage. You must set up CloudFront.

aws.{teamAvatar, submission, file}.key.use

Whether a pair of keys must be used for connecting to S3. For example, if the EC2 that hosts Jophiel has been associated to a role that has permission for connecting to S3, then this value should be false. If not present, then aws.global.key.use will be used.

aws.{teamAvatar, submission, file}.key.{access, secret}

If a pair of keys must be used, then these are the access and secret keys, respectively. If not present, then aws.global.key.{access, secret} will be used.

Running Uriel¶

See Running Judgels Play applications.

Adding initial admin¶

Uriel has been successfully installed and configured. Now, we need to have a user with admin role.

1. Find your user JID in Jophiel.
2. Set the roles column to user,admin in the corresponding row (that contains your user JID) in the uriel_user table.
3. Re-log in to Uriel. Verify that you can view the Users menu on the left.

Requirements¶

The following are necessary for install Gabriel and the Moe sandbox correctly.

• Linux. We have only tested Gabriel in Ubuntu 14.04, so we recommend you to use it. Note that Moe cannot be installed in Windows or OS X.
• GCC.

Currently, programming languages that are supported are hardcoded to Gabriel: C, C++, Pascal, and Python 3. The following are necessary in order to use the languages:

• GCC >= 4.7 (for C/C++ language support)
• Free Pascal (for Pascal language support)
• Python >= 3 (for Python 3 language support)

Installing Gabriel¶

First, follow the main Judgels setup if you haven’t. Then, install Gabriel:

judgels pull gabriel

This will clone Gabriel and Moe repositories to your Judgels base directory. Next, we will need to build the Moe sandbox program.

Building Moe¶

Run these commands inside judgels-moe repository.

./configure
make

If the above commands finished correctly, then you will have two executable files:

• Isolate (obj/isolate/isolate): the main sandbox
• Interactive wrapper (obj/eval/iwrapper): wrapper for interactive problems

The above executables are necessary for Gabriel. If you cannot find them, that means your build failed. Resolve the errors and try again.

Installing control groups in Linux¶

Isolate needs control groups feature in Linux for sandboxing contestants’ programs. You need to install it:

sudo apt-get install cgroup-bin

Then, we have to enable the memory and swap accounting in control groups. Follow these steps.

1. Add swap partition to your system if it does not have any. Note that a swap partition is mandatory for Isolate to function properly.

2. Open the /etc/default/grub using sudo privilege.

3. Modify the line containing GRUB_CMDLINE_LINUX as follows:

   GRUB_CMDLINE_LINUX="cgroup_enable=memory swapaccount=1"
   

4. Update the GRUB:

   sudo update-grub
   

5. Reboot the machine.

6. Verify that either the /sys/fs/cgroup/memory/memory.memsw.limit_in_bytes file or /sys/fs/cgroup/memory/memory.soft_limit_in_bytes file exists.

Enabling quota support in Linux¶

Quota support must be enabled so that Isolate can limit the disk usage of contestants’ programs.

1. Install the kernel that support quota.

   sudo apt-get install linux-image-extra-virtual
   

   If prompted, choose “keep the local version currently installed”.

2. Edit /etc/fstab using sudo. Iinclude usrquota and grpquota in the desired partition:

   LABEL=cloudimg-rootfs   /    ext4   defaults,usrquota,grpquota  0 0
   

3. Reboot the machine.

4. Enable quota modules:

   sudo depmod -a
   sudo modprobe quota_v1
   sudo modprobe quota_v2
   sudo echo quota_v1 >> /etc/modules
   sudo echo quota_v2 >> /etc/modules
   

5. Install quota package:

   sudo apt-get install quota
   

6. Verify that quota support has been enabled. Go to judgels-moe directory and run:

   obj/isolate/isolate -b1 -q50000,50 -vvv --init
   

   This line must be output:

   Quota: Set block quota 50000 and inode quota 50
   

Configuring Gabriel¶

Copy the default conf file by running this command in judgels-gabriel directory:

cp src/main/resources/conf/application_default.conf src/main/resources/conf/application.conf

Then, fill the correct configuration values in src/main/resources/conf/application.conf. Some guides:

gabriel.baseDataDir

The root directory for performing grading. For example: /var/judgels/data/gabriel.

sandalphon.{baseUrl, clientJid, clientSecret}

Sandalphon’s base URL and the required credentials to which this Gabriel connect for fetching test cases. This Gabriel must be registered in the Sandalphon, in Graders menu.

sealtiel.{baseUrl, clientJid, clientSecret}

Sealtiel’s base URL and the required credentials to which this Gabriel connect for fetching grading requests and sending grading results. This Gabriel must be registered in the Sealtiel as a client.

moe.{isolatePath, iwrapperPath}

The absolute paths to Isolate and interactive wrapper executable files, respectively.

You can use more than one Gabriel for a single Sealtiel credentials. For example, you may want to use 5 machines each containing one Gabriel for running a contest in Uriel, to make grading process fast. Simply use identical Sealtiel configuration for all Gabriels.

Running grader¶

After the installation and configuration are finished, Gabriel can be run using Activator. Run this command in judgels-gabriel directory:

./activator

Then, in the Activator console, run:

run X

where X is the desired number of threads. It can be omitted if you want to use default recommended number of threads based on your processor.

Technology stack¶

Language

• Java 8 for most code.
• Scala for Play’s views.

Framework

Play Framework 2.4.2 (Java) for Judgels Play applications.

Template engine

Twirl for Judgels Play applications.

Database

MySQL for Judgels Play applications.

ORM

JPA (Java Persistence API) implemented with Hibernate for Judgels Play applications.

Build system

SBT, wrapped in Typesafe Activator.

Sandbox

Moe Contest Environment (the Isolate module) for Gabriel.

Project structure¶

Judgels repositories are hosted on GitHub, in IA TOKI organization (https://github.com/ia-toki).

The main repository is the judgels repository. The responisibilites of this repository are:

• Hosting Judgels command-line tool, which will be used for installing Judgels applications.
• Hosting Judgels documentation.
• Being the central GitHub issue tracker for all Judgels applications.

The other Judgels repositories are prefixed with judgels-. For each Judgels application <app>, there will be a repository named judgels-<app>, which hosts the application code.

In addition, for each Judgels applications, there will be judgels-<app>-commons repository, which contains parts of the application that can be used by other applications that depend on it.

judgels-commons

Consists of basic dependencies used by all applications.

judgels-play-commons

Mainly consists of:

• Base model components and their connection management with the database.
• Base view components that are shared across all Judgels Play applications. For example: base look-and-feel layout.
• Base controller components.

judgels-jophiel-commons

Consists of components used by Jophiel clients for connecting to Jophiel.

judgels-sandalphon-commons

Consists of components used by other Judgels applications for rendering problems and submitting solutions to Sandalphon.

judgels-uriel-commons

Consists of components used by external applications for manipulating contest scoreboards. Currently it is not used yet by any applications other than Uriel.

judgels-sealtiel-commons

Consists of components used by other Judgels applications for fetching and sending messages from Sealtiel.

judgels-jerahmeel-commons

Consists of components used by other Judgels applications that depend on Jerahmeel (currently none).

judgels-michael-commons

Consists of components used by other Judgels applications that depend on Michael (currently none).

judgels-gabriel-commons

Consists of interfaces and implementations of grading engines.

Judgels Play application layers¶

Judgels Play applications are built on top of Play framework. In Play framework, the MVC (Model-View-Controller) pattern is used. In Judgels, we use two other patterns: Service and DAO (Data access object).

It will be easier to explain with a diagram. Suppose that a user wants to change his profile on Jophiel. Here is the flow of events that will happen in Jophiel, numbered from 1 through 11. For completeness, we will explain from the start of Jophiel. Each component will be explained along with the explanation of the events.

1. Admin starts Jophiel, using judgels start jophiel or judgels run jophiel command.
2. The Play’s Global object is loaded and run. It will construct all controller classes and their dependencies (services), using dependency injection with Spring Framework.
3. User makes HTTP request to change his profile, by opening the URL http://localhost:9001/profile on his browser.
4. The request is passed to the Play’s Routes object. Based on the request string (/profile), the correct controller class and the action method is called. In this case, UserProfileController‘s profile() method is called.
5. The controller checks whether the user has the right permission to perform the action. Then, controller calls the correct method in the service object responsible for user management. Services are objects that do business processes of the system. In this case, UserProfileService‘s updateProfile() is called.
6. The service calls the DAO (Data Access Object) to retrieve the user entity model from the database. DAO is an object that provides interface to do queries to the database, regardless of the database’s SQL variants. We use Hibernate for wrapping the SQL queries. In this case, UserDao‘s findByJid() is called. The user’s JID is passed to the method.
7. The DAO finds the correct user record in the database, wraps it into an entity model object, and return it. Entity model is the Java class representation of a row in the database table. Fields in entity model represent columns in the database table. We use JPA (Java Persistence API) for describing the table and columns in Java. In this case, the user entity model class is UserModel. We also use metamodels; see Syntactically correct and type-safe JPA queries in Play 2.0 for more details.
8. The service retrieves the returned user entity model, and wraps into a user business model object. This business model represent data structure that does not depend on database, and is used by controllers, views, and the other services. They do not care how the business model was constructed. In this case, the user business model class is User. Normally, the business model class is similar to its entity model class counterpart. Then, the user business model object is returned by the service.
9. The controller retrieves the returned user business model. Then the controller uses the user’s properties to construct the form object. In this case, the form class is UserProfileForm.
10. The controller passes the form to the view object to render. We use Twirl, the default Play’s templating engine. The whole view and form are rendered as HTML page.
11. The controller returns an HTTP response to the user. The user is then able to fill the form for changing his profile. The flow finishes.

Database design¶

Judgels adapts the database design explained here: Phabricator Database Schema. Some highlights:

• Each object in Judgels has a JID (Judgels ID) in the form of JID-XXX-YYYYYYYYYYYYYYYYYYYY, where X is object type code and Y is a shortened UUID.
• No foreign keys, since we want that objects can be transferred between Judgels applications. For example, we may want to create a set of Judgels instance for OSN, and then transfer the problems back to the central repository.
• Properties that are not to be queried and have complex structure, are stored either in harddisk or in database as JSON strings.

Additionally, each object has the following fields:

• userCreate, timeCreate, ipCreate: user, time, and IP when this object is created.
• userUpdate, timeUpdate, ipUpdate: user, time, and IP when this object is updated.

Codebase setup¶

Basically, you have to follow all instructions on main Judgels setup. Make sure you are able to run/start the Judgels applications you want to develop.

IDE setup¶

Java¶

1. Use 4 spaces for indentation (not tabs).

2. Use curly braces in a block even it contains only one statement.

3. Put the opening curly brace on the right of the statement:

   if (condition) {
       //
   }
   

4. Do not use star import (import xxx.*;). Import individual classes.

5. Mark classes as final whenever possible.

6. Use Google Guava’s immutable collection whenever possible.

7. Make classes immutable whenever possible. Do not introduce setters unless really required. Initialize the class properties inside the constructor.

8. Prefer this:

   public void someFunction() {
       if (!requiredCondition1) {
           return failureMethod1();
       }
   
       if (!requiredCondition2) {
           return failureMethod2();
       }
   
       // main function code
   
   }
   

   to:

   public void someFunction() {
       if (requiredCondition1) {
           if (requiredCondition2) {
   
               // main function code
   
           } else {
               return failureMethod2();
           }
       } else {
           return failureMethod1();
       }
   }
   

9. Put only statements that can really throws exception, inside a try-block. Pull the ones that don’t outside.

Introduction¶

All Judgels documentation is stored in judgels repository, in the directory docs. The documentation is published on Read the Docs, here: http://judgels.readthedocs.org. The documentation will be updated every time there is a commit pushed to judgels repository.

The documentation is written using Sphinx. To use Sphinx, we need Python. To simplify Sphinx installation, we will use virtualenv.

Setup¶

1. Install Python.

   On Ubuntu:

   sudo apt-get install python
   

   On OS X (via Homebrew):

   brew install python
   

2. Install pip.

   On Ubuntu:

   sudo apt-get install python-pip
   

   On OS X: automatically installed along with Python.

3. Install virtualenv via pip:

   pip install virtualenv
   

4. Go to main documentation directory.

   cd $JUDGELS_BASE_DIR/judgels/docs
   

5. Create virtual environment.

   virtualenv env
   

6. Activate the virtual environment.

   source env/bin/activate
   

7. Install Sphinx.

   pip install sphinx
   

Sphinx will be ready in the directory.

Writing documentation¶

First, try to build the documentation. Run

make html

If everything goes well, a file $JUDGELS_BASE_DIR/judgels/docs/_build/html/index.html will be built. Open it on your browser to see the documentation.

The documentation is written in reStructuredText (RST) syntax. The root documentation source file is docs/index.rst. Please consult reStructuredText Primer for more details on the syntax.