Skip to content

Connecting the ICPC Tools with DOMjudge

Jump to bottom
Nicky Gerritsen edited this page Sep 11, 2019 · 6 revisions

NOTE: this guide will be updated when the new ICPC Tools build is stable

The ICPC Tools are a set of tools that can be used for ICPC-style contests. This page describes setting up some of them with DOMjudge:

  • The CDS, which is needed for other tools to connect to.
  • The resolver, which can be used to resolve a frozen scoreboard and announce winners.
  • The presentation admin, a tool that can be used to control presentation clients.
  • The presentation client, a tool that can display useful and nice information during a contest.

Requirements

To use the ICPC Tools the following is needed:

  • A running DOMjudge 7.0+ installation.
  • Admin access to the DOMjudge installation.
  • An active contest in that DOMjudge instance.
  • A server (or other machine) to run the CDS. The CDS can run on Windows, Linux and macOS. This server should be able to reach the DOMjudge installation and the machines named below should be able to reach the server.
  • A GUI machine to run the presentation admin.
  • A GUI machine to run the resolver. This can be the same machine as the presentation admin, since the tools will not have to run at the same time. This machine should be hooked up to a beamer or big screen in the room where you will announce the results.
  • One or more GUI machines to run presentation clients. Normally these are set up in the room(s) where the teams are sitting during the contest and hooked up to a beamer or big screen.
  • A recent build of the ICPC Tools. Note that the builds on the ICPC Tools home page are not new enough; the builds that are linked there at the bottom are, so use these. This guide is written using build 2.1.2100.

Note that the resolver supports running multiple connected machines in client/server mode, but this will not be explained in this guide.

All machines that will run (one of) the ICPC Tools will require Java.

Setting up DOMjudge

In DOMjudge, create a user with the API reader, API writer and Source code reader roles and give it some (secure) password (note that the password will be stored in an XML file, so better not use characters like &). Note down the username and password somewhere. Also note down the CID of the contest you want to use, which can be found on the jury contest page.

Note: if you run DOMjudge with the configuration option data_source set to either 1 or 2, you need to use the external ID of the contest instead of the CID. By default DOMjudge runs with data_source=0 and unless you know what you are doing you should not have to change this. However, DOMjudge Demoweb runs with data_source=1 so if you use that for testing use the external ID!

Setting up the CDS

Download the CDS from here and upload the ZIP to the server that will run the CDS. Unpack the ZIP file. Rename the wlp directory to cds so there is no confusion as to what the directory contains.

Replace the contests of the cds/usr/servers/cds/config/cdsConfig.xml file with the following, replacing the values as instructed:

<cds>
    <!-- Set location= to a directory that the user running the CDS can write to -->
    <contest location="/home/cds/contest-data" recordReactions="false">
        <!-- Set the url to the URL of your DOMjudge installation, followed by /api/contests/<cid>, where <cid> is your CID or external ID -->
        <!-- Set the user and password to the user you created in the previous step -->
        <ccs
            url="https://www.domjudge.org/demoweb/api/contests/nwerc18"
            user="cds"
            password="somepassword" />
    </contest>
</cds>

Now edit the file cds/usr/servers/cds/users.xml and change the password of all the users to something secure. Do not change the usernames, otherwise you also need to update server.xml in the same directory.

Now you can start the CDS by running cds/bin/server run cds. This will keep a window open with some logging. If you want to run it in the background, use cds/bin/server start cds (use stop to stop it again).

Browse to https://:8443 and ignore the SSL error (see the last section of this page if you want to use a Let's Encrypt certificate). Click on Overview just below the contest and it will pop up a login prompt. Enter the admin credentials from the users.xml file and you should get a page with some information. The first time you do this the CDS will get information from the DOMjudge event feed, so it might take a while, especially if the connection between DOMjudge and the CDS server is not very fast. You can click around a bit in the interface to see what it contains. At some point the value after Last event: on the overview page should show the (contest-relative) time of the last event that occurred. You can check this value to be sure that the whole event feed up to the current point in time has been processed.

You should keep the CDS running at all times or at least while presentation clients are running or when you are starting up the resolver.

Setting up the presentation admin

Download the presentation admin ZIP on the machine that will administer the presentation clients and unpack it. Open a terminal and run:

cd <directory where the presentation admin has been unpacked to, normally called presentationAdmin-2.1>
./presAdmin.sh https://<server ip>:8443/ presAdmin <presAdmin password>

Replace <presAdmin password> with the password of the presAdmin user from users.xml.

This will start up a GUI interface, that will later show all connected clients. More on this below

Starting presentation clients

Download the presentation client on the machines that will run the presentation clients and unpack it. Open a terminal and run:

cd <directory where the presentation client has been unpacked to, normally called presentations-2.1>
./client.sh <someid> https://<server ip>:8443/ presentation <presentation password>

Replace <someid> with a unique ID that can be used to recognize this machine and <presentation password> with the password of the presentation user from users.xml.

This will start up a full screen presentation client on the primary display of the machine, which can be controlled by the presentation admin.

Controlling the presentation clients

In the presentation admin interface you will see all the connected clients to the left. You can click on one of them to start configuring them.

On the right side you see a list of presentations. Not all of them work, but here is a list of which ones work for sure and what they do:

  • Judgement time: view judgement times per problem
  • Languages: see a bar graph of used languages
  • Problem comparison: see a graph of submissions over time per problem
  • Problem summary: see a bar graph of attempts and correct submissions per problem
  • Total problems: see a graph of failed, pending and solved submissions over time
  • Contest clock: show the contest clock with optional banner (see below)
  • Countdown: see a countdown with ready symbols
  • Polar countdown: see a countdown with circles representing hours, minutes seconds
  • Problem colours: show the balloon colours
  • Problem summary: show the problem stats with coloured blocks
  • Message: show a message with optional banner (see below). Type the message in the box called "Properties"
  • Presentations inside the "Scoreboard" group: show different views of the current scoreboard
  • Presentations inside the "Tile Scoreboards group (except "Team scoreboard"): show multi-column scoreboards

Note that the presentations will only show pending submissions during the freeze, so some of them might not bee too useful the last hour.

After clicking on a presentation, you can click on "Apply" at the bottom right to use that presentation on the selected client.

The "New" button at the bottom allows you to build up a "slide deck" with different presentations that will "rotate", including transitions.

Presentation clients should auto-reconnect if they fail.

Resolving results

Download the resolver on the machines that will run the resolver and unpack it. Open a terminal and run:

cd <directory where the presentation client has been unpacked to, normally called resolvers-2.1>
./awards.sh

Select the "REST" tab and enter <cds url>/api/contests/<contest ID>, replacing <cds url> with the URL to the CDS and <contest ID> with the contest ID. Use the admin credentials from users.xml and click connect. Let the tool retrieve the feed from the CDS.

Now you can configure which awards you want to show:

  • Rank: highlight the top X teams
  • Group: highlight the top X teams per group ("Team categories" in DOMjudge)
  • First to Solve: highlight the teams that first solved a problem
  • Medal: show medals for the given number of teams
  • Group Highlight: highlight the top X teams from one group; normally not really used
  • World Finals: use the settings from the World Finals; probably not too useful

When you are done click the Save button and save the file as event-feed.json in an empty directory. Quit the award util.

After saving the JSON from from the awards tool, we can run the resolver on it by running the following:

cd <directory where the presentation client has been unpacked to, normally called resolver-2.1>
 ./resolver.sh <path to directory containing event-feed.json>

Some useful arguments for the resolver are (add them after the directory):

  • --fast 0.15: speed up the resolver by a lot; useful for testing and verifying results.
  • --display 2: display the resolver on the secondary screen.

The resolver is controlled using the keyboard. The following keys are useful to know:

  • Q (capital q): quit the resolver
  • space: move one step forward
  • b: move one step backwards
  • + / -: speed up / slow down the resolver one step

Advanced setup

Contest logo and banner

If you want a banner and/or logo to appear on presentations or in the resolver, you can place a file called logo.png (square) or banner.png (a wide rectangle) in:

  • The directory specified by location from the cdsConfig.xml for presentations.
  • The directory with event-feed.json for the resolver.

Team photo's and organization logo's

If you have taken team photo's and want to show them, create a directory called teams in one of the locations mentioned above and create a subdirectory for every team named after the team ID from DOMjudge. In it, create a file called photo.jpg.

If you have organization logo's, create a directory called organizations in one of the locations mentioned above and create a subdirectory for every organization named after the organization ID (use the external ID when data_source is 1 or 2) from DOMjudge. In it, create a file called logo.png.

Using a Let's Encrypt certificate for the CDS

If you have a Let's Encrypt certificate (or another certificate if you modify the script) for a domain and you want to use it for the CDS, you can use the following script (make sure the CDS is stopped when running this):

#!/bin/bash
#################################
# Let's Encrpyt CDS v0.1
##################################
# AUTHOR
##################################
# Name: Nicky Gerritsen
# Contact: [email protected]
######################################################
script_name="Let's Encrypt CDS v0.1"

domain="some.domain.here" # Replace this with the name of the domain you want to use
cds_install_dir="/home/cds/cds/usr/servers/cds/resources/security" # Replace this with the path to usr/servers/cds/resources/security in your CDS directory

log_file="/var/log/cds_lets_encrypt.log"
log () {
        if [ "$1" ]; then
                echo -e "[$(date)] - $1" >> $log_file
        fi
}

[[ -f ${log_file} ]] || touch ${log_file}
[[ -n ${cds_install_dir} ]] || cds_install_dir="/var/lib/cds" 2>> ${log_file}
[ -d ${cds_install_dir}/letsencrypt ] || mkdir ${cds_install_dir}/letsencrypt 2>> ${log_file}

log "Started ${script_name}"
[[ -f /etc/letsencrypt/live/${domain}/fullchain.pem ]] || log "Let's Encrypt certificates for ${domain} don't exist or you don't have enough permissions... exiting" || exit 0
openssl pkcs12 -export -in /etc/letsencrypt/live/${domain}/fullchain.pem -inkey /etc/letsencrypt/live/${domain}/privkey.pem -out ${cds_install_dir}/letsencrypt/${domain}.p12 -name default -passout pass:ICPCTools 2>> ${log_file}
if [ $? -ne 0 ]; then { log "Error occoured while creating PKCS12 certficate"; exit 0; } fi
cp ${cds_install_dir}/key.jks ${cds_install_dir}/key.jks.old 2>> ${log_file}
keytool -noprompt -importkeystore -deststorepass ICPCTools -destkeypass ICPCTools -destkeystore ${cds_install_dir}/key.jks -srckeystore ${cds_install_dir}/letsencrypt/${domain}.p12 -srcstoretype PKCS12 -srcstorepass ICPCTools -srcalias default -destalias default
if [ $? -ne 0 ]; then { cp ${cds_install_dir}/key.jks.old ${cds_install_dir}/key.jks; log "Error occoured while creating keystore, copied back old keystore... exiting"; exit 0; } fi
chmod 600 ${cds_install_dir}/key.jks && chown cds: ${cds_install_dir}/key.jks 2>> ${log_file}
log "Finished ${script_name}"

Common issues

Help! I see problems or teams in the CDS / presentations / resolver that I should not see 😢

This is probably because you added these problems to the contest or created the teams and later removed them. DOMjudge keeps track of events, but doesn't handle delete events correctly in these cases.

First of all, stop the CDS. Then, depending on whether there are any submissions done already:

  • If not, remove everything from the events database table for the current contest.
  • If there are, you need to manually remove the events that you do not want.

Afterwards start the CDS again and all should be OK.

I want to resolve twice: once for student teams and once for company teams

If you set a Team category in DOMjudge to not be visible, the CDS and resolver will not pick it up. So just (temporarily) make only the category you want to show visible. Note that you might need to restart the CDS for this to work.

My presentation clients do all kind of strange things and I have the CDS running behind an nginx proxy

Do not run the CDS behind an nginx proxy. It will break stuff.

Clone this wiki locally