DOMjudge: a jury system for running a programming contest

A contest system, not a code runner

DOMjudge is a system for running a programming contest, like the ICPC regional and world championship programming contests, and it can also be used to run IOI style contents with partial scoring. The README calls it version 10.0.0DEV.

The thing to understand is that DOMjudge is not a grading service for an online judge with a queue of strangers. It is the infrastructure that a contest jury uses on the day: teams upload submissions, the system runs them against the test data, and jury members see the results, decide about penalties and manage the contest from the same interface.

That framing explains the shape of the repository. There is a webapp/ directory for the interface, a judge/ directory for the sandboxed execution, a submit/ directory, a sql/ directory for the schema, example_problems/ and example_scoring_problems/ directories that show what a problem set looks like in each of the two scoring styles, and a lib/ directory with shared code.

The repository topics match that world: competitive-programming, icpc, programming-contest-jury, linux, and prebuilt. The last of those matters, because the project distributes built packages rather than expecting you to assemble a stack by hand.

The audience is a contest organiser, a regional or national training camp, or a university programming society running its own competition. The licensing and a copyright history stretching back to 2004 fit an institution that intends to keep running it.

domserver and judgehost are deliberately separate

The Makefile lists the two central build targets, and separating them is the single most important structural fact about DOMjudge:

make domserver
make judgehost

The domserver is the web application and the database side, the part contestants and jury members talk to. The judgehost is the machine that actually executes submissions, and it is deliberately kept away from the web-facing server so that a submission cannot reach the contest database, the jury interface or the network. The separation is the security model.

In a real deployment that means at least two machines, or at minimum two strongly separated environments, with the judgehost reachable only by the domserver. The judging environment is the part that runs untrusted code written by contestants minutes before the deadline, and the design keeps that code away from everything else.

The build system reflects the separation too. There are install-domserver and install-judgehost targets alongside domserver and judgehost, and separate configuration steps for each, named domserver-configure and judgehost-configure in the target list. The Makefile also handles Apache configuration, including the difference between installing into the Apache global configuration directory for a default instance and into the sites directory for a named instance, so that the contest does not accidentally become the default virtual host for other hostnames on the same machine.

That level of detail in the build files is a fair proxy for the whole project: DOMjudge assumes a serious deployment with a web server, a database and a separate execution machine, and it does not try to hide that.

Install from a tarball, not from git

The README is unusually direct about this. It provides stable releases and daily snapshots of the latest code, and then says that bootstrapping from git is an advanced use case mostly needed for development, and that installing DOMjudge is almost never done via a git clone except for development or testing the latest code.

That is the advice to follow. The stable release tarball arrives with the configure script and the documentation already generated. A git checkout does not:

make dist

That command bootstraps a fresh copy of the source tree, generating the configure script and the documentation, as the README explains, with more detail in the online documentation under the section called Development.

Documentation comes in two prebuilt shapes, and both have caveats the README spells out. There is an HTML version prebuilt from reStructuredText sources, and team documentation prebuilt in PDF format, but the PDF contains default and example settings. To get the correct settings for a local environment, DOMjudge has to be properly configured first, because parts of the configuration are used in the documentation, for example the URL to the team interface.

All documentation is also available online at the DOMjudge homepage, with the warning that the online documentation is from the latest stable release and thus might not apply to the version you have installed. With a 10.0.0DEV tree and a stable release document set, that gap between documentation version and code version is worth keeping in mind.

The compose file is a development sandbox

The repository does include a docker-compose.yml, and the first thing to notice is the warning at the top of it: this compose stack should only be used for development purposes, and should not be used for production deployments. For production with Docker, the file points at a different image on Docker Hub, the domserver one, at hub.docker.com/r/domjudge/domserver.

The development stack starts two services, a database and the application:

services:
  mariadb:
    image: docker.io/mariadb
    environment:
      - MYSQL_ROOT_PASSWORD=domjudge
      - MYSQL_USER=domjudge
      - MYSQL_PASSWORD=domjudge
      - MYSQL_DATABASE=domjudge

and the application service runs as privileged with cgroup host mode, which the comment flags as requiring Docker Compose greater than 2.15:

  domjudge:
    image: docker.io/domjudge/domjudge-contributor
    hostname: domjudge-contributor

The privileged flag and the cgroup setting are not incidental. The judgehost needs to create sandboxes, control processes and manage cgroups, which in practice means elevated privileges inside the container. The stack also mounts /sys/fs/cgroup and a chroot directory, and sets the user namespace mode to keep-id for uid and gid 1000 so that files created inside the container land on the host with the right ownership.

The practical reading: this compose file is a comfortable way to develop against DOMjudge or to try it out on a laptop, and it is not a contest deployment. The production path is the packaged install, or the domserver image.

Two scoring models in one system

The two example directories, example_problems/ and example_scoring_problems/, are the clearest statement of what DOMjudge is built for.

ICPC style contests are all or nothing. A submission either solves the problem or it does not, the score is the number of solved problems, and the penalty is the time of the last accepted submission plus a fixed amount for each wrong attempt. A system that only handled that would be a thin wrapper around a compile-and-run loop.

IOI style contests are partial scoring. Each submission produces a score between zero and the full value for that problem, judged against several test cases with partial credit, and the ranking is the total score across problems. Supporting that requires the judge to report a score rather than a verdict, and it requires the jury interface to display a distribution of results per test case so a jury member can see why a submission scored what it did.

DOMjudge supporting both means the per-problem configuration carries a choice of validation and scoring model, and it means the interface has to present two very different kinds of results. That is why the project also documents a Default validator from the Kattis problemtools package, which is included in the tree under the MIT licence, and it is why the README points to example problem sets rather than to a single tutorial: a contest organiser copies and adapts the example directories for their own problems.

The repository also contains a ChangeLog and a SECURITY.md, along with static analysis configuration in .phpmd-ruleset.xml, phpstan.dist.neon and a phpstan bug exclusion file, and a CODINGSTYLE.md, which together describe a project with a considered development process behind it.

GPL-2.0 with a mixed licence tail

DOMjudge is Copyright from 2004 to 2026 by the DOMjudge developers and their contributors, and the README names the current developers: Jaap Eldering, Nicky Gerritsen, Keith Johnson, Thijs Kinkhorst, Mart Pluijmaekers, Michael Vasseur and Tobias Werth, with a full list in the manual.

The base licence is the GNU General Public License, version 2 or, at your option, any later version, with the file COPYING at the top of the tree and also COPYING.BSD and COPYING.MIT alongside it.

Those extra files are not decoration. Parts of the system are based on other programs covered by other copyrights, and the README says those attributions are noted in the files themselves and are listed in the manual. The default validator from the Kattis problemtools package is included and covered by the MIT licence in COPYING.MIT, and the M4 autoconf macros under m4/ are licensed under all-permissive and GPL3+ terms. The shipped tarball also bundles external library dependencies in webapp/vendor and webapp/node_modules, covered by their individual licences as recorded in composer.lock and in webapp/LICENSES.txt.

For a contest organiser this matters in two places. Redistributing a modified DOMjudge carries the GPL-2.0 obligations, and the version 2 or later clause means you can ship it under GPL-3 instead if that suits your institution better. And if you build a contest system on top and distribute it, the bundled webapp dependencies come with their own terms that the project has already documented rather than left for you to discover.

There is no GitHub release stream for the project, but the homepage publishes stable releases and daily snapshots, and announcements go out on a low volume mailing list.

Editorial conclusion

DOMjudge suits a contest organiser who needs submissions judged against per-problem test cases, a scoring model that works for both ICPC and partial scoring formats, and a web interface for teams and jury members. It does not suit a laptop user who wants to try it in ten minutes, since the judgehost runs sandboxed submissions and needs a real Linux environment, nor a team that wants a hosted judge with no infrastructure of its own. Before adopting, read the installation documentation under doc/manual, confirm your host can run the judgehost with the privileges it needs, and check whether your problem set can be expressed as the example_problems and example_scoring_problems directories show.

Frequently asked questions

Official sources

1. DOMjudge/domjudge on GitHub
2. Issues
3. License: GPL-2.0
4. Project website
5. README