Advanced configuration topics¶
DOMjudge can optionally present country flags, affiliation logos, team pictures and a page-wide banner on the public interface.
You can place the images under the path public/images/ (see the Config checker in the admin interfae for the full filesystem path of your installation) as follows:
Country flags are shown when the
show_flagsconfiguration option is enabled. The flag-icon-css is used for the flag images.
Affiliation logos: these will be shown with the teams that are part of the affiliation, if the
show_affiliation_logosconfiguration option is enabled. They can be placed in public/images/affiliations/1234.png where 1234 is the numeric ID of the affiliation as shown in the DOMjudge interface. There is a separate option
show_affiliationsthat independently controls where the affiliation names are shown on the scoreboard. These logos should be square and be at least 64x64 pixels, but not much bigger.
Team pictures: a photo of the team will be shown in the team details page if public/images/teams/456.jpg exists, where 456 is the team’s numeric ID as shown in the DOMjudge interface. DOMjudge will not modify the photos in any way or form, so make sure you don’t upload photos that are too big, since that will incur a lot of network traffic.
Contest Banners: a page-wide banner can be shown on the public scoreboard if that image is placed in public/images/banners/1.png where 1 is the contest’s numeric ID as shown in the DOMjudge interface. Alternatively, you can place a file at public/images/banner.png which will be used as a banner for all contests. Contest-specific banners always have priority. Contest banners usually are rectangular, having a width of around 1920 pixels and a height of around 300 pixels. Other ratio’s and sizes are supported, but check the public scoreboard to see how it looks.
The IDs for affiliations, teams and contests need to be the external ID
data_source setting of DOMjudge is set to external.
If you add or remove any of the above files, you need to clear the cache for changes to be detected.
Authentication and registration¶
Out of the box users are able to authenticate using username and password.
Two other native authentication methods are available:
IP Address - authenticates users based on the IP address they are accessing the system from;
X-Headers - authenticates users based on some HTTP header values.
Besides this, DOMjudge can be configured with any provider that can set
the environment variable
REMOTE_USER to an existing username,
for example LDAP, SAML, CAS or OpenID connect modules for Apache.
There’s an option to let teams register themselves in the system.
To enable the IP Address authentication method, you will need to edit
the configuration option
auth_methods to include
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 or pre-fill the IP address associated with an account from the Users page. When using IPv6, ensure that you enter the address in the exact representation as the webserver reports it (e.g. as visible in the webserver logs) - no canonicalization is performed.
To enable the X-Headers authentication method, you will need to edit
the configuration option
auth_methods to include
To use this method, the following HTTP 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
X-DOMjudge-Login- Contains the username
X-DOMjudge-Pass- Contains the user’s password, base64 encoded
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
DOMjudge supports generic authentication by various existing providers that
can authenticate a user and set the
REMOTE_USER environment variable
to the authenticated username.
Examples of this are several Apache modules: mod LDAP, Shibboleth or Mod Mellon for SAML 2.0, mod Auth CAS, mod OpenID Connect, or mod Kerb for Kerberos.
This does not currently allow for auto-provisioning or self-registration,
the users must already exist in DOMjudge and their DOMjudge username must
match what is in the
Set up the respective module to authenticate incoming users for the URL
path of your installation. Then, in
main section of your source tree to add a
form_login that looks like this:
main: pattern: ^/ … form_login: login_path: login check_path: login csrf_token_generator: security.csrf.token_manager use_referer: true remote_user: provider: domjudge_db_provider
And re-run the “make install” command to deploy this change.
Or alternatively remove the entire
var/cache/prod/ directory when
security.yaml on an already deployed location.
If the thus authenticated user is not found in DOMjudge, the application will present the standard username/password login screen as a fallback.
Changing the User password hashing cost¶
The hashing cost can be changed in
webapp/config/packages/security.yaml, change the encoder section:
algorithm: ‘bcrypt’ cost: 7
For bcrypt (current encoder) each increase in cost will double the time per password.
See the Symfony docs for more info on this subject.
Teams can be allowed to self-register with the system. To enable it, go to the team category you want the self-registered teams to become part of and enable self-registration for that category. The option will be shown on the login screen if it has been enabled for at least one category. When multiple categories are set to allow, teams can choose one of them during registration. You can assign the respective categories to the contest(s) these teams may participarte in.
During registration, teams can also specify their affiliation, if the global configuration option ‘show affiliations’ is enabled.
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
run. When deploying a new (or changed)
executable to a judgehost
build is executed once if
present (inside the chroot environment that is also used for
compiling and running submissions). Afterwards an executable
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.
Compilers can be configured by creating or selecting/editing an executable in
the web interface. When compiling a set of source files, the
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
java_javac_detect in the web interface. For many common languages
compile scripts are already included.
Interpreted languages and non-statically linked binaries (for example, Python or Java) can in also be used, but require that all runtime dependencies are added to the chroot environment. For details, see the 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 Python and 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
java_javac_detect in the list of executables.
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
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.
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>;
testdata.ans are the jury
reference input and output files,
feedbackdir the directory
containing the judging response files
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
For more details on writing and modifying a compare (or validator)
script, see the
boolfind_cmp example and the comments at the
top of the file
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
boolfind is included as an example interactive
doc/examples/boolfind.pdf for the description.
The calling syntax is:
/path/to/run_script/run <testdata.in> <testdata.ans> <feedbackdir> <run args> < <program.out>;
Usage is similar to compare programs. DOMjudge wraps the run program to handle bi-directional communication between the run program and the contestants’ program. Anything you write to stdout is forwarded to the contestants’ program, anything the contestants’ program writes is forwarded to your stdin.
validate.h file in the
boolfind_run executable for some
convenience functions you might want to use when implementing your own run
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
print_command configuration option in
the administrator interface. Here you can enter a command that will
be run to print the files. The command you enter can have the
[file]: the location on disk of the file to print.
[original]: the original name of the file.
[language]: the ID of the language of the file. Useful for syntax highlighting.
[username]: the username of the user who is printing.
[teamname]: the teamname of the user who is printing.
[teamid]: the team ID of the user who is printing.
[location]: the location of the user’s team.
[location] can be empty. Placeholders will be shell-escaped before
passing them to the command. The standard output of the command will
be shown in the web interface. If you also want to show standard error,
2>&1 to the command.
For example, to send the first 10 pages of the file to the default printer
enscript and add the username in the page header,
you can use this command:
enscript -b [username] -a 0-10 -f Courier9 [file] 2>&1
Multiple judgedaemons per machine¶
You can run multiple judgedaemons on one multi-CPU or multi-core machine, dedicating one CPU core to each judgedaemon using Linux cgroups.
To that end, add extra unprivileged users to the system, i.e. add users
X runs through
useradd as described in the section Removing apport.
You can then start each of the judgedaemons with:
judgedaemon -n X
to bind it to core
X and user
domjudge-run-X. If you use
systemd, then edit the
domjudge-judgehost.target unit file and add
more judgedaemons there.
Although each judgedaemon process will be bound to one single CPU core, shared use of other resources such as disk I/O might still have effect on run times.
This manual assumed you are running a singe-site contest; that is, the teams are located closely together, probably in a single physical location. In a multi-site or distributed contest, teams from several remote locations use the same DOMjudge installation. An example is a national contest where teams can participate at their local institution.
One option is to run a central installation of DOMjudge to which the teams connect over the internet. It is here where all submission processing and judging takes place. Because DOMjudge uses a web interface for all interactions, teams and judges will interface with the system just as if it were local. Still, there are some specific considerations for a multi-site contest.
Network: there must be a relatively reliable network connection between the locations and the central DOMjudge installation, because teams cannot submit or query the scoreboard if the network is down. Because of traversing an unsecured network, you should consider HTTPS for encrypting the traffic. If you want to limit teams’ internet access, it must be done in such a way that the remote DOMjudge installation can still be reached.
Team authentication: the IP-based authentication will still work as long as each team workstation has a different public IP address. If some teams are behind a NAT-router and thus all present themselves to DOMjudge with the same IP-address, another authentication scheme must be used (e.g. PHP sessions).
Judges: if the people reviewing the submissions will be located remotely as well, it’s important to agree beforehand on who-does-what, using the submissions claim feature and how responding to incoming clarification requests is handled. Having a shared chat/IM channel may help when unexpected issues arise.
Scoreboard: by default DOMjudge presents all teams in the same scoreboard. Per-site scoreboards can be implemented either by using team categories or team affiliations in combination with the scoreboard filtering option.
As an alternative, each site can run their own DOMjudge installation, and
each site will have a local scoreboard with their own teams. It is possible
to create a merged scoreboard out of these individual installations with the
scoreboard:merge. You need to know for each site which
contest ID to use, and the IDs of the team categories you want to include
(comma separated). You can then run it like this:
webapp/bin/console scoreboard:merge 'Combined Scoreboard Example' \ https://judge.example1.edu/api/v4/contests/3/ 3 \ https://chipcie.example2.org/api/v4/contests/2/ 2,3 \ https://domjudge.aapp.example.nl/api/v4/contests/6/ 3
Clearing the DOMjudge cache¶
Some operations require you to clear the DOMjudge cache. To do this, execute the webapp/bin/console (see the Config checker in the admin interfae for the full filesystem path of your installation) binary with the cache:clear subcommand:
Note that this is different than clearing the scoreboard cache.
Sending errors to Sentry¶
DOMjudge has the possibility to send any errors to Sentry. First, create an
organization and project in Sentry and copy the Sentry DSN. Then create the file
webapp/.env.local and add to it the setting
<dsn> is the Sentry DSN you copied. Then clear the cache
for this change to take effect. Now all errors should appear in Sentry