Next Previous Contents

3. Installation and configuration

This chapter details a fresh installation of DOMjudge. The first section is a Quick Installation Reference, but that should only be used by those already acquainted with the system. A detailed guide follows after that.

3.1 Quick installation

Note: this is not a replacement for the thorough installation instructions below, but more a cheat-sheet for those who've already installed DOMjudge before and need a few hints. When in doubt, always consult the full installation instruction.

External software:

DOMjudge:

On the domserver host: On the judgehosts: It should be done by now. As a check that (almost) everything works, the set of test sources can be submitted:
cd tests
make check

Note that this requires some configuration depending on the AUTH_METHOD selected in etc/domserver-config.php, see submit client configuration for more details.

Then, in the main jury web interface, select the admin link judging verifier to automatically verify most of the test sources, except for a few with multiple possible outcomes; these have to be verified by hand. Read the test sources for a description of what should (not) happen.

Optionally:

3.2 Prerequisites

For a detailed list of the hardware and software requirements, please refer to the previous chapter on contest planning.

Debian and RedHat installation commands

For your convenience, the following command will install needed software on the DOMjudge server as mentioned above when using Debian GNU/Linux, or one of its derivate distributions like Ubuntu.


sudo apt install gcc g++ make zip unzip mariadb-server \
        apache2 php php-cli libapache2-mod-php php-zip \
        php-gd php-curl php-mysql php-json php-xml php-intl php-mbstring \
        acl bsdmainutils ntp phpmyadmin python-pygments \
        libcgroup-dev linuxdoc-tools linuxdoc-tools-text \
        groff texlive-latex-recommended texlive-latex-extra \
        texlive-fonts-recommended texlive-lang-european
# To enable the command-line submit client, also add:
sudo apt install libcurl4-gnutls-dev libjsoncpp-dev libmagic-dev
# Replace apache2 and libapache2-mod-php with nginx, php-fpm and
# apache2-utils for nginx

Note that PHP modules may need to be enabled depending on your distribution. E.g. on Ubuntu run
sudo phpenmod json

to enable the JSON module.

The following command can be used on RedHat Enterprise Linux, and related distributions like CentOS and Fedora.


sudo yum install gcc gcc-c++ make zip unzip mariadb-server \
        httpd php-gd php-cli php-intl php-mbstring php-mysql php-xml \
        python-pygments ntp linuxdoc-tools libcgroup-devel \
        texlive-collection-latexrecommended texlive-wrapfig
# To enable the command-line submit client, also add:
sudo yum install libcurl-devel jsoncpp-devel file-devel

Note that the TeX Live packages expdlist, moreverb, and svn still have be installed manually to rebuild the team manuals. Furthermore, phpmyadmin is available from the Fedora EPEL repository. The package jsoncpp-devel is available in Fedora, but not in RHEL/CentOS.

Libmagic is not strictly required, but highly recommended for detecting binary file submissions. Pass the option --enable-static-linking to configure so that these libraries are statically linked into the submit binary and not needed on the team workstations where submit is installed.

On a judgehost, the following should be sufficient. The last two lines show some example compilers to install for C, C++, Java (OpenJDK), Haskell and Pascal; change the list as appropriate.

For Debian:


sudo apt install make sudo debootstrap libcgroup-dev lsof \
        php-cli php-curl php-json php-xml php-zip procps \
        gcc g++ openjdk-8-jre-headless \
        openjdk-8-jdk ghc fp-compiler

For RedHat:


sudo yum install make sudo libcgroup-devel lsof \
        php-cli php-mbstring php-xml php-process procps-ng \
        gcc gcc-c++ glibc-static libstdc++-static \
        java-1.7.0-openjdk-headless java-1.7.0-openjdk-devel \
        ghc-compiler fpc

Note that fpc is not available in RedHat 7.

3.3 Installation system

There is a separate maintainer installation method meant for those wishing to do development on the DOMjudge source code. See the appendix with developer information and skip the rest of this section.

The DOMjudge build/install system consists of a configure script and makefiles, but when installing it, some more care has to be taken than simply running './configure && make && make install'. DOMjudge needs to be installed both on the server and on the judgehosts. These require different parts of the complete system to be present and can be installed separately. Within the build system these parts are referred to as domserver, judgehost and additionally docs for all documentation.

DOMjudge can be installed with two different directory layouts:

Single directory tree

With this method all DOMjudge related files and programs are installed in a single directory tree which is specified by the prefix option of configure, like


./configure --prefix=$HOME/domjudge --with-baseurl=https://domjudge.example.com/

This will install each of the domserver, judgehost, docs parts in a subdirectory $HOME/domjudge/domserver etc. These subdirectories can be overridden from the defaults with options like --with-domserver_root=DIR, see configure --help for a complete list. The prefix defaults to /opt/domjudge.

Besides the installed files, there will also be directories for logging, temporary files, submitted sources and judging data:

log

contains all log files.

tmp

contains temporary files.

submissions

(optionally) on the domserver contains all correctly submitted files: as backup only, the database is the authoritative source. Note that this directory must be writable by the web server for this feature to work.

judgings

location on judgehosts where submissions are tested, each in its own subdirectory.

This method of installation is the default and probably most practical for normal purposes as it keeps all files together, hence easily found.

FHS compliant

This method installs DOMjudge in directories according to the Filesystem Hierarchy Standard. It can be enabled by passing the option --enable-fhs to configure and in this case the prefix defaults to /usr/local. Files will be placed e.g. in PREFIX/share/domjudge, PREFIX/bin, PREFIX/var/log, PREFIX/etc/domjudge, while /tmp will be used for temporary files. You may want to pass options --sysconfdir=/etc and --localstatedir=/var to configure to disable the prefix for these.

Note that the --with-baseurl configure option is not required but highly recommended, as it allows building the submit client and team documentation with the correct URL preset. If needed, the setting can later be updated in etc/domserver-static.php on the domserver, and in etc/submit-config.h in the source tree for rebuilding the submit client.

After running the configure script, the system can be built and installed. Each of the domserver, judgehost, docs parts can be built and installed separately, respectively by:


make domserver && sudo make install-domserver
make judgehost && sudo make install-judgehost
make docs && sudo make install-docs

Note that root privileges are required to set permissions and user and group ownership of password files and a few directories. If you run the installation targets as non-root, you will be warned that you have to perform these steps manually. Although DOMjudge can be installed as root, one should not run DOMjudge programs and daemons under the root user, but under a normal user: runguard is specifically designed to be the only part invoked as root (through sudo) to make this unnecessary. Also, running as root will give rise to problems, see runguard: root privileges not dropped in the common problems section.

For a list of basic make targets, run make in the source root directory without arguments.

3.4 Database installation

DOMjudge uses a MySQL or MariaDB database server for information storage. Where this document talks about MySQL, it can be understood to also apply to MariaDB.

The database structure and privileges are included in MySQL dump files in the sql subdirectory. The default database name is domjudge. This can be changed manually in the etc/dbpasswords.secret file: the database name as specified in this file will be used when installing.

Installation of the database is done with bin/dj_setup_database. For this, you need an installed and configured MySQL server and administrator access to it. Run


dj_setup_database genpass
dj_setup_database [-u <mysql admin user>] [-p <password>|-r] install

This first creates the DOMjudge database credentials file etc/dbpasswords.secret (optionally change the random generated password, although it is not needed for normal operation). Then it creates the database and user and inserts some default/example data into the domjudge database. The option -r will prompt for a password for mysql; when no user is specified, the mysql client will try to read credentials from $HOME/.my.cnf as usual. The command uninstall can be passed to dj_setup_database to remove the DOMjudge database and users; this deletes all data!

The script also creates the initial "admin" user with password stored in etc/initial_admin_password.secret.

The domjudge database contains a number of tables, some of which need to be manually filled with data before the contest can be run. See the database section of Contest setup for details.

Setting up replication or backups

The MySQL server is the central place of information storage for DOMjudge. Think well about what to do if the MySQL host fails or loses your data.

A very robust solution is to set up a replicating MySQL server on another host. This will be a hot copy of all data up to the second, and can take over immediately in the event of failure. The MySQL manual has more information about setting this up.

Alternatively, you can make regular backups of your data to another host, for example with mysqldump, or using a RAID based system.

Replication can also be used to improve performance, by directing all select-queries to one or more replicated slave servers, while updates will still be done to the master. This is not supported out of the box, and will require making changes to the DOMjudge source.

Storage of submissions

The database is the authoritative version for submission source files; file system storage is available as an easy way to access the source files and as backup, but only when the web server has write permissions to <domjudge_submitdir>. File system storage is ignored if these permissions are not set. The programs bin/save_sources2file and bin/restore_sources2db are available to store and recover the submission table in the database to/from these files.

3.5 Web server configuration

For the web interface, you need to have a web server (e.g. nginx or Apache) installed on the domserver and made sure that PHP correctly works with it. Refer to the documentation of your web server and PHP for details.

To configure the Apache web server for DOMjudge, use the Apache configuration snippet from etc/apache.conf. It contains examples for configuring the DOMjudge pages with an alias directive, or as a virtualhost, optionally with SSL; it also contains PHP and security settings. Reload the web server for changes to take effect.

ln -s <DOMSERVER_INSTALL_PATH>/etc/apache.conf /etc/apache2/conf-available/domjudge.conf
a2enmod rewrite
a2enconf domjudge
# Edit the file /etc/apache2/conf-available/domjudge.conf to your needs
service apache2 reload

An nginx webserver configuration snippet is also provided in etc/nginx-conf. Furthermore the file etc/domjudge-fpm.conf contains the PHP FPM configuration you can use. You still need htpasswd from apache2-utils though. To use this configuration file, perform the following steps

ln -s <DOMSERVER_INSTALL_PATH>/etc/nginx-conf /etc/nginx/sites-enabled/domjudge
ln -s <DOMSERVER_INSTALL_PATH>/etc/domjudge-fpm.conf /etc/php/7.0/fpm/pool.d/domjudge.conf
# Edit the files /etc/nginx/sites-enabled/domjudge and
# /etc/php/7.0/fpm/pool.d/domjudge.conf to your needs
service php7.0-fpm reload
service nginx reload

The judgehosts connect to DOMjudge via the DOMjudge API so need to be able to access at least this part of the web interface.

3.6 Fine tuning server settings

For Apache, there are countless documents on how to maximize performance. Of particular importance is to ensure that the MaxClients setting is high enough to receive the number of parallel requests you expect, but not higher than your amount of RAM allows. Furthermore, we recommend to turn KeepAlive off, or at least make sure that KeepAliveTimeout is set to only a few seconds. Otherwise, a large number of page view requests from teams and public can easily exhaust the Apache workers, resulting in an unresponsive website, which will also affect the judgedaemons.

As for PHP, the use of an opcode cache like the Alternative PHP Cache (Debian package: php-apc) is beneficial for performance. For uploading large testcases, see the section about memory limits.

It may be desirable or even necessary to fine tune some MySQL default settings:

3.7 Installation of a judgehost

Some extra steps have to be taken to completely install and configure a judgehost.

Unprivileged user and group

For running solution programs under a non-privileged user, a user and group have to be added to the system(s) that act as judgehost. This user does not need a home-directory or password, so the following command would suffice to add a user and group `domjudge-run' with minimal privileges.

On Debian and Redhat based Linux distributions use:

useradd -d /nonexistent -U -M -s /bin/false domjudge-run

For other systems check the specifics of your useradd command. This user must also be configured as the user under which programs run via configure --enable-runuser=USER; the default is domjudge-run. By default the group is set to the same, this can be modified with the option --enable-rungroup=GROUP

Sudo permissions

Runguard needs to be able to become root for certain operations like changing to the runuser and performing a chroot. Also, the default chroot-startstop.sh script uses sudo to gain privileges for certain operations. There's a pregenerated /etc/sudoers.d/ snippet in etc/sudoers-domjudge that contains all required rules. You can put the lines in the snippet at the end of /etc/sudoers, or, for modern sudo versions, place the file in /etc/sudoers.d/. If you change the user you run the judgedaemon as, or the installation paths, be sure to update the sudoers rules accordingly.

Creating a chroot environment

The judgedaemon executes submissions inside a chroot environment for security reasons. By default it mounts parts of a prebuilt chroot tree read-only during this judging process (using the script lib/judge/chroot-startstop.sh). This is needed to support extra languages that require access to interpreters or support libraries at runtime, for example Java, C#, and any interpreted languages like Python, Perl, Shell script, etc.

This chroot tree can be built using the script bin/dj_make_chroot. On Debian and Ubuntu the same distribution and version as the host system are used, on other Linux distributions the latest stable Debian release will be used to build the chroot. Any extra packages to support languages can be passed with the option -i or be added to the INSTALLDEBS variable in the script. The script bin/dj_run_chroot runs an interactive shell or a command inside the chroot. This can be used for example to install new or upgrade existing packages inside the chroot. Run these scripts with option -h for more information.

Finally, if necessary edit the script lib/judge/chroot-startstop.sh and adapt it to work with your local system. In case you changed the default pre-built chroot directory, make sure to also update the sudo rules and the CHROOTORIGINAL variable in chroot-startstop.sh.

When using the default chroot-start-stop.sh script, a static POSIX shell has to be available for copying it into the chroot environment. For Linux i386, a static Dash shell is included, which works out of the box, also for the Linux Intel/AMD 64 architecture. For other architectures or operating systems, a shell has to be added manually. Then simply point the lib/sh-static symlink to this file.

Linux Control Groups

DOMjudge uses Linux Control Groups or cgroups for process isolation in the judgedaemon. Linux cgroups give more accurate measurement of actually allocated memory than traditional resource limits (which is helpful with interpreters like Java that reserve but not actually use lots of memory). Also, cgroups are used to restrict network access so no separate measures are necessary, and they allow running multiple judgedaemons on a multi-core machine by using CPU binding.

The judgedaemon needs to run a recent Linux kernel (at least 3.2.0). The following steps configure cgroups on Debian wheezy. Instructions for other distributions may be different (send us your feedback!). Edit grub config to add cgroup memory and swap accounting to the boot options. Edit /etc/default/grub and change the default commandline to

GRUB_CMDLINE_LINUX_DEFAULT="quiet cgroup_enable=memory swapaccount=1"
Then run update-grub and reboot. After rebooting check that /proc/cmdline actually contains the added kernel options. On VM hosting providers such as Google Cloud or DigitalOcean, GRUB_CMDLINE_LINUX_DEFAULT may be overwritten by other files in /etc/default/grub.d/.

You have now configured the system to use cgroups, but you need to create the actual cgroups that DOMjudge will use. For that, you can use the script under misc-tools/create_cgroups. Edit the script to match your situation first. This script needs to be re-run after each boot (it has already been added to the judgedaemon init script).

REST API credentials

The judgehost connects to the domserver via a REST API. You need to create an account for the judgedaemons to use (this may be a shared account between all judgedaemons) with a difficult, random password and the 'judgehost' role. On each judgehost, copy from the domserver (or create) a file etc/restapi.secret containing the id, URL, username and password whitespace-separated on one line, for example:

default http://example.edu/domjudge/api/  judgehosts  MzfJYWF5agSlUfmiGEy5mgkfqU
Note that the password must be identical to that of the judgehost user in the admin web interface. Multiple lines may be specified to allow a judgedaemon to work for multiple domservers. The id is used to differentiate between multiple domservers, and should be unique within the restapi.secret file.

Starting the judgedaemon

Finally start the judgedaemon (optionally binding it to CPU core X):


bin/judgedaemon [-n X]

If using the -n X option, then an extra user domjudge-run-X must also be created. Additionally, you could add a kernel parameter isolcpus=X to make the Linux kernel not schedule any processes on CPU X, except those explicitly bound to it. This might improve runtime consistency under some circumstances; however, in a test running a single judgedaemon on 6 CPU core machines, we did not see any significant improvement of runtime or decrease in variations.

Upon its first connection to the domserver API, the judgehost will be auto-registered and will be by default enabled. If you wish to add a new judgehost but have it initially disabled, you can add it manually through the DOMjudge web interface and set it to disabled before starting the judgedaemon.

3.8 Building and installing the submit client

DOMjudge supports two submission methods: via the command line submit program and via the web interface. From experience, both methods have users that prefer the one above the other.

The command line submit client sends submissions using the API interface internally. This requires the libcURL and libjsonCPP library development files at compile time. The submit client can be statically linked using the --enable-static-linking configure option to avoid a runtime dependency.

The submit client can be built with make submitclient. There is no make target to install the submit client, as its location will very much depend on the environment. You might e.g. want to copy it to all team computers or make it available on a network filesystem. Note that if the team computers run a different (version of the) operating system than the jury systems, then you need to build the submit client for that OS.

The submit client needs to know the URL of the domserver. This can be passed as a command line option or environment variable. The latter option makes for easier usage. A sample script submit_wrapper.sh is included, which sets this variable. See that script for more details on how to set this up.

The submit client authenticates to the DOMjudge API via either the configured authentication scheme, or can use the DOMjudge internal username and password combination for a given user account regardless of authentication scheme. For example, when the IPADDRESS scheme is used, no additional configuration is required because submissions will come from the correct IP address of the team. When another scheme is used, it may be necessary to place username and password combinations in the team's account so the submit client can use those. In this case these are always the DOMjudge internal password, so not e.g. LDAP passwords when using that scheme. The credentials are placed in the file ~/.netrc, with example content:

machine domserver.example.com login user0123 password Fba^2bHzz
See the netrc(4) manual page for more details. You may want to distribute those .netrc files in advance to the team accounts. Make sure they are only readable for the user itself.

The submit client under Windows/Cygwin

Note: this feature is not well supported anymore; we recommend using the web interface for submitting in Windows.

The submit client can also be built under Windows when the Cygwin environment is installed. First install Cygwin, and include GCC, curl-devel and maybe some more packages. When Cygwin is correctly installed with all necessary development tools, the submit binary can be created by running configure followed by make submit.exe in the submit directory.

3.9 Configuration

Configuration of the judge system is mostly done by editing the configuration variables on the page Configuration settings available in the administrator interface, and changes take effect immediately. The administrator interface can be reached on http(s)://yourhost.example.edu/domjudge/jury/ and the default username is admin with initial password stored in etc/initial_admin_password.secret.

Some settings that are tightly coupled to the filesystem can be configured in the files in etc: domserver-config.php, judgehost-config.php, common-config.php for the configuration options of the domserver, judgehost and shared configuration options respectively. Descriptions of settings are included in these files. The judgedaemon must be restarted for changes to take effect, while these are directly picked up by the webinterfaces.

Besides these settings, there are a few other places where changes can be made to the system, see other configurable scripts.

3.10 Authentication Methods

Out of the box users are able to authenticate using basic username and password. There is also a configuration option to allow teams to self-register with the system.

Two other authentication methods are available:

IP Address

To enable the IP Address authentication method, you will need to edit the database configuration option auth_methods to include ipaddress.

Once this is done, when a user first logs in their IP Address will be associated with their account, and subsequent logins will allow them to log in without authenticating.

If desired, you can edit the IP Address associated with an account from the Users page in the jury interface.

X-Headers

To enable the IP Address authentication method, you will need to edit the database configuration option auth_methods to include xheaders.

To use this method, the following headers need to be sent to the /login URL. This can be done using the squid proxy for example, to prevent teams from needing to know their own log in information but in an environment where IP address based auth is not feasible(multi site over the internet contest).

Squid configuration for this might look like:


acl autologin url_regex ^http://localhost/domjudge/login
request_header_add X-DOMjudge-Login "$USERNAME" autologin
request_header_add X-DOMjudge-Pass "$BASE64_PASSWORD" autologin

3.11 Executables

DOMjudge supports executable archives (uploaded and stored in ZIP format) for configuration of languages, special run and compare programs. The archive must contain an executable file named build or run. When deploying a new (or changed) executable to a judgehost build is executed once if present. Afterwards an executable file run must exist (it may have existed before), that is called to execute the compile, compare, or run script. The specific formats are detailed below.

Executables may be changed via the web interface in an online editor or by uploading a replacement zip file. Changes apply immediately to all further uses of that executable.

3.12 Configuration of languages

Compilers can be configured by creating or selecting/editing an executable in the web interface. When compiling a set of source files, the run executable is invoked with the following arguments: destination file name, memory limit (in KB), main (first) source file, other source files. For more information, see for example the executables c or java_javac_detect in the web interface. Note that compile scripts are included for most common languages already.

Interpreted languages and non-statically linked binaries (for example, Oracle Java) can in principle also be used, but require that all runtime dependencies are added to the chroot environment. See section creating a chroot environment.

Interpreted languages do not generate an executable and in principle do not need a compilation step. However, to be able to use interpreted languages (also Oracle's Java), during the compilation step a script must be generated that will function as the executable: the script must run the interpreter on the source. See for example pl and java_javac_detect in the list of executables.

3.13 Configuration of special run and compare programs

To allow for problems that do not fit within the standard scheme of fixed input and/or output, DOMjudge has the possibility to change the way submissions are run and checked for correctness.

The back end script testcase_run.sh that handles the running and checking of submissions, calls separate programs for running submissions and comparison of the results. These can be specialised and adapted to the requirements per problem. For this, one has to create executable archives as described above. Then the executable must be selected in the special_run and/or special_compare fields of the problem (an empty value means that the default run and compare scripts should be used; the defaults can be set in the global configuration settings). When creating custom run and compare programs, we recommend re-using wrapper scripts that handle the tedious, standard part. See the boolfind example for details.

Compare programs

Compare scripts/programs should follow the Kattis/problemarchive output validator format. DOMjudge uses the default output validator specified there as its default, which can be found at https://github.com/Kattis/problemtools/blob/master/support/default_validator/.

Note that DOMjudge only supports a subset of the functionality described there. In particular, the calling syntax is


/path/to/compare_script/run <testdata.in> <testdata.ans> <feedbackdir> <compare_args> < <program.out>

where testdata.in testdata.ans are the jury reference input and output files, feedbackdir the directory containing e.g. the judging response file judgemessage.txt to be written to (the only other permitted files there are teammessage.txt score.txt judgeerror.txt diffposition.txt), compare_args a list of arguments that can set when configuring a contest problem, and program.out the team's output. The validator program should not make any assumptions on its working directory.

For more details on writing and modifying a compare (or validator) scripts, see the boolfind_cmp example and the comments at the top of the file testcase_run.sh.

Run programs

Special run programs can be used, for example, to create an interactive problem, where the contestants' program exchanges information with a jury program and receives data depending on its own output. The problem boolfind is included as an example interactive problem, see docs/examples/boolfind.pdf for the description.

Usage is similar to compare programs: you can either create a program run yourself, or use the provided wrapper script, which handles bi-directional communication between a jury program and the contestants' program on stdin/stdout (see the run file in the boolfind_run executable).

For the first case, the calling syntax that the program must accept is equal to the calling syntax of run_wrapper, which is documented in that file. When using run_wrapper, you should copy it to run in your executable archive. The jury must write a program named exactly runjury, accepting the calling syntax


runjury <testdata.in> <program.out>

where the arguments are files to read input testdata from and write program output to, respectively. This program will communicate via stdin/stdout with the contestants' program. A special compare program must probably also be created, so the exact data written to <program.out> is not important, as long as the correctness of the contestants' program can be deduced from the contents by the compare program.

3.14 Alerting system

DOMjudge includes an alerting system. This allows the administrator to receive alerts when important system events happen, e.g. an error occurs, or a submission or judging is made.

These alerts are passed to a plugin script alert which can easily be adapted to fit your needs. The default script emits different beeping sounds for the different messages when the beep program is available, but it could for example also be modified to send a mail on specific issues, connect to monitoring software like Nagios, etc. For more details, see the script lib/alert.

3.15 Other configurable scripts

There are a few more places where some configuration of the system can be made. These are sometimes needed in non-standard environments.

3.16 Logging & debugging

All DOMjudge daemons and web interface scripts support logging and debugging in a uniform manner via functions in lib.error.*. There are three ways in which information is logged:

Each script also defines a default threshold level for messages to be logged to stderr (VERBOSE: defaults to LOG_INFO in daemons and LOG_ERR in the web interface) and for log file/syslog (LOGLEVEL: defaults to LOG_DEBUG).

In case of problems, it is advisable to check the logs for clues. Extra debugging information can be obtained by setting the config option DEBUG to a bitwise-or of the available DEBUG_* flags in etc/common-config.php, to e.g. generate extra SQL query and timing information in the web interface.

3.17 (Re)generating documentation and the team manual

There are three sets of documentation available under the doc directory in DOMjudge:

the admin-manual

for administrators of the system (this document),

the judge-manual

for judges, describing the jury web interface and giving some general information about this system,

the team-manual

for teams, explaining how to use the system and what restrictions there are.

The team manual is only available in PDF format and must be built from the LaTeX sources in doc/team after configuration of the system. A prebuilt team manual is included, but note that it contains default/example values for site-specific configuration settings such as the team web interface URL and judging settings such as the memory limit. We strongly recommend rebuilding the team manual to include site-specific settings and also to revise it to reflect your contest specific environment and rules.

Besides a standard LaTeX installation, the team manual requires the svn and expdlist packages. These are available in TeX Live in the texlive-latex-extra package in any modern Linux distribution. Alternatively, you can download and install them manually from their respective subdirectories in http://mirror.ctan.org/macros/latex/contrib.

When the docs part of DOMjudge is installed and site-specific configuration set, the team manual can be generated with the command genteammanual found under docs/team. The PDF document will be placed in the current directory or a directory given as argument. The following should do it on a Debian-like system:


sudo apt install make texlive-latex-extra texlive-latex-recommended texlive-lang-european
cd <INSTALL_PATH>/docs/team
./genteammanual [targetdir]

The administrator's and judge's manuals are available in PDF and HTML format and prebuilt from SGML sources. Rebuilding these is not normally necessary. To rebuild them on a Debian-like system, the following commands should do it:


sudo apt install linuxdoc-tools make zip ghostscript groff texlive-latex-recommended
make -C doc/admin docs
make -C doc/judge docs

3.18 Optional features

Multiple judgedaemons per machine

You can run multiple judgedaemons on one multi-cpu or multi-core machine, dedicating one cpu core to each judgedaemon.

To that end, add extra unprivileged users to the system, i.e. add users domjudge-run-<X> (where X runs through 0,1,2,3) with useradd as described in section installation of a judgehost. Finally, start each of the judgedaemons with


judgedaemon -n <X>

to bind it to core X.

Encrypted communications (HTTPS)

DOMjudge can be configured to run on HTTPS, so teams and judgedaemons communicate with the domserver securely over encrypted SSL/TLS connections. Setting up SSL for Apache is documented in the Apache manual and in many tutorials around the web.

The judgedaemons must recognise the CA you're using, otherwise they will refuse to connect over HTTPS. If your judgedaemon gives an error message about an untrusted certificate, put your domserver's certificate in /etc/ssl/certs/yourname.crt of each judgehost (and on the team machines when using the commandline submit client) and run:


sudo c_rehash

When loading teams from the ICPC registration system through the import feature in DOMjudge, the certificate from icpc.baylor.edu must similarly be accepted by your local installation or if not, added via the procedure above.

NTP time synchronisation

We advise to install an NTP-daemon (Network Time Protocol) to make sure the time between domserver, judgehosts, and jury and team computers is in sync.

Printing

It is recommended to configure the local desktop printing of team workstations where ever possible: this has the most simple interface and allows teams to print from within their editor.

If this is not feasible, DOMjudge includes support for printing via the DOMjudge web interface: the DOMjudge server then needs to be able to deliver the uploaded files to the printer. It can be enabled via the enable_printing configuration option in the administrator interface. By default printouts are formatted with enscript and and printed with local lpr. The exact command used to send the files to a printer can be changed by overriding the send method of the \DOMJudgeBundle\Utils\Printing class.

Judging consistency

The following issues can be considered to improve consistency in judging.

3.19 Upgrading

There is some support to upgrade DOMjudge to newer versions. Note that this functionality is not extensively tested, so when you plan to upgrade, you are strongly advised to backup the DOMjudge database and other data before continuing. We also advise to check the ChangeLog file for important changes.

Upgrading the filesystem installation is probably best done by installing the new version of DOMjudge in a separate place and transferring the configuration settings from the old version.

There are SQL upgrade scripts to transform the database including its data to the layout of a newer version. The scripts can be found under sql/upgrade and each script applies changes between two consecutive DOMjudge versions. At the beginning of each script, a check is performed which will let MySQL bail out with an error if it should not be applied anymore. Note that the scripts must be applied in order (sorted by release). These scripts can be applied by running dj_setup_database upgrade. Be aware that these scripts are conservative in adding and upgrading SQL data, so check that e.g. new compile scripts are present or add them manually, and check the upgrade scripts manually for any other data upgraded.

If you have any active contests, it may be advisable to run "Refresh scoreboard cache" from the DOMjudge web interface after the upgrade.


Next Previous Contents