DOMjudge

DOMjudge is a mature, open‑source contest management platform designed to automate the entire lifecycle of programming competitions such as ICPC regional and world championships. From a developer’s viewpoint, it functions as a full‑stack web application that orchestrates problem ingestion, test harness execution, result aggregation, and real‑time scoreboard updates while exposing a rich set of APIs for integration with external tooling. The system is written primarily in PHP (Laravel‑like structure) for the web layer, Python for the judging engine, and JavaScript/TypeScript for the interactive UI. Data persistence relies on a relational database (PostgreSQL or MySQL), and the judging engine runs inside isolated Docker containers to guarantee reproducible verdicts across heterogeneous languages.

Key Features

• Language Plug‑in Architecture – Each supported language is defined by a JSON descriptor that specifies compiler flags, runtime environment, and resource limits. New languages can be added by implementing a small wrapper script that follows the existing descriptor contract.
• Real‑time WebSocket Scoreboard – The front end consumes a ws:// feed that pushes verdict updates, allowing judges and teams to see results instantly without polling.
• Extensible API Layer – REST endpoints expose contest metadata, problem statements, submissions, and verdicts. OAuth2 authentication is available for third‑party integrations such as custom scoreboard widgets or CI pipelines.
• Robust Validation Pipeline – The judge uses the Kattis problemtools suite for input validation, time‑limit enforcement, and memory profiling. The validator is pluggable, enabling alternative checker programs or custom grading scripts.
• Administrative CLI – A command‑line tool (domjudgectl) facilitates bulk operations (e.g., importing contests, resetting teams) and can be scripted in CI/CD workflows.

Technical Stack

Core Capabilities

• Submission API – POST /api/submissions accepts source files, language identifiers, and optional test cases. The API returns a submission ID that can be polled for status.
• Webhook Support – External services can register to receive submission_finished events, enabling integrations like custom leaderboards or automated notifications.
• Problem Importer – Supports ZIP bundles containing problem statements, test cases, and checker scripts. The importer validates structure against a schema before committing to the database.
• Scoring Algorithms – Multiple scoring modes (ICPC, ACM‑ICPC, custom) are selectable per contest. The engine recalculates standings after each verdict and emits updates via WebSocket.

Deployment & Infrastructure

DOMjudge is designed for self‑hosting on a single server or a small cluster. The primary requirements are:

• OS: Linux (Debian/Ubuntu or RHEL/CentOS) with Docker daemon.
• Resources: At least 2 GB RAM and a multi‑core CPU; more is recommended for large contests with many simultaneous submissions.
• Containerization: The judging engine runs inside Docker containers; the system ships with a docker-compose.yml that provisions the web server, database, Redis, and worker processes.
• Scalability: Workers can be scaled horizontally by adding more instances of the judge service; Redis pub/sub ensures all workers receive new submission tasks. The web tier can be load‑balanced behind a reverse proxy (NGINX/Traefik).

Integration & Extensibility

• Plugin System – Language plugins are just JSON files plus a wrapper script; the judge loads them at runtime without code changes.
• Custom Checkers – Replace the default validator with a bespoke checker (e.g., for interactive problems) by specifying its entry point in the problem descriptor.
• Webhooks & APIs – Expose custom endpoints or subscribe to events; the REST API is fully documented in OpenAPI format.
• Theme & UI Customization – The front end uses CSS variables and a component registry, allowing teams to brand the scoreboard or add new widgets.

Developer Experience

• Documentation – Comprehensive HTML and PDF manuals are generated from reStructuredText sources. The API is auto‑generated, and the wiki hosts community tips for advanced configurations.
• Community & Support – Active GitLab repository with issue tracking, CI pipelines, and a dedicated Discord/Slack channel for real‑time help.
• Licensing – GPLv2+, ensuring freedom to modify and redistribute. All third‑party libraries are appropriately licensed (MIT, etc.).

Use Cases