# HUSTOJ: a self-hosted online judge built on PHP, C++ and MySQL > HUSTOJ is a GPL-2.0 online judge for ACM/ICPC and NOIP training, installed from a shell script or a Docker image. It runs PHP on the web side and C++ judges on the worker side, and its licence notes draw a clear line between redistribution and SaaS use. **zhblue/hustoj** — Popular Simple Open Source Online Judge based on PHP/C++/MySQL/Linux for ACM/ICPC and NOIP training, with easy installation. 简单实用的开源OJ系统 - Repository: https://github.com/zhblue/hustoj - Website: http://www.hustoj.com/?cat=2 - Stars: 3,802 · Forks: 832 - Language: JavaScript - License: GPL-2.0 - Published: 2026-09-23 · Updated: 2026-09-23 · Language: en - Canonical page: https://hysenlabs.com/projects/zhblue-hustoj ## The problem HUSTOJ solves: running your own judge instead of renting one A programming contest needs three things at once: a place to publish problems, a sandbox that compiles and runs untrusted submissions, and a scoreboard that updates while the contest is running. Hosted judges give you the first and third for free and keep the second under their control. HUSTOJ takes the opposite route. It is a complete judge you install on a server you own, with the problem archive, the submission queue, the contest module and the admin panel in the same codebase. The README describes it as a popular OJ system that is cross-platform, easy to install, ships with a problem bank, and has a low barrier to secondary development. That last point matters: the project explicitly documents how to modify it, and the wiki directory in the repository holds the secondary development notes. The audience is teachers running NOIP-style training, university ACM/ICPC teams, and small contest organisers who need the judge on their own network, sometimes with no reliable internet access. It is not aimed at a single developer who wants to solve problems; it is aimed at the person who has to run the contest. ## How the PHP front end and the C++ judge split the work The repository is organised around a trunk directory, and the Dockerfile copies that whole tree into the image at /trunk. The web layer is PHP served by nginx with php-fpm, backed by MySQL or MariaDB, and the container installs php-mysql, php-gd, php-zip, php-mbstring, php-xml and php-yaml alongside the database server. The judging side is native code: the image installs make, flex, gcc and g++ together with libmysqlclient-dev and libmysql++-dev, which is what the judge needs to compile and link against the database. That split is the architecture in one sentence: PHP handles users, problems, contests and scoreboards, while compiled C++ binaries handle the actual evaluation of submissions. The changelog shows the sandbox evolving. An October 2025 entry records that the LiveCD base moved to Ubuntu 24.04 and that podman replaced docker as the judging container. The same log shows that SQL testing can now run in the browser through a Wasm build of SQLite, which moves some test runs off the server. On the AI side, a January 2026 entry states that AI calls were moved to an asynchronous mode so they no longer occupy the php-fpm process pool, and db_info.inc.php gained a variable named $OJ_AI_API_URL pointing at a file such as aiapi/qwen.php. That is a design that treats the model as an optional add-on rather than part of the judging path. ## Installing HUSTOJ on Ubuntu or with Docker The README lists several installation routes: Ubuntu 24.04, which it marks as the first choice for beginners because the software is recent and the steps are easiest to complete; Deepin 20+; CentOS; Docker; other distributions; and a LiveCD image. It also covers changing the Ubuntu package mirror and removing Aliyun Shield before installation, which suggests the target audience is often running on mainland Chinese cloud hosts. The repository ships a Dockerfile that starts from ubuntu:24.04, installs nginx, mysql-server, php-fpm and the build toolchain, copies trunk to /trunk, runs docker/setup.sh, exposes port 80 and starts through /opt/docker/entrypoint.sh. Two build arguments are declared: APT_MIRROR, which defaults to Y and controls whether the Aliyun mirror script runs, and APT_CA, which defaults to N. A single volume, /volume, is declared. The commented-out VOLUME line in the Dockerfile lists the paths the maintainers considered exposing, including /home/judge/data, /home/judge/etc, /home/judge/web and /var/lib/mysql, which is a useful hint about which directories hold state if you plan to persist them yourself. The changelog notes that a command line configuration tool, setup.sh, was added in December 2025. The README does not document a rollback procedure for a failed upgrade, and it does not list a supported PHP version range beyond the April 2025 note that PHP 8.4 compatibility was added. ## Switching templates through db_info.inc.php The visible face of the judge is chosen by one configuration value. The README states that changing $OJ_TEMPLATE in db_info.inc.php, whose default location is /home/judge/src/web/include, selects among the bundled templates. Five are demonstrated on the project's demo site: syzoj, sidebar, bs3, sweet, bshark and mdui, with the demo URLs carrying a tp parameter such as ?tp=sidebar. The practical consequence is that a school can rebrand the front page without touching the judging code, and a developer replacing the interface entirely can keep the database and API layer. The README makes that separation explicit in its licence note, stating that a completely new web interface coupled only at the database and API level is not affected by GPL-2.0. That is an unusually concrete statement of where the boundary sits, and it is worth reading before you decide how much of the front end to rewrite. ## Where HUSTOJ is the wrong tool The judging core is C++ and the web layer is PHP, and nothing in the repository suggests either is optional. If your team runs Python or Go services and has no appetite for maintaining a php-fpm pool, a MySQL server and a compiled judge binary on the same host, this stack will be a permanent operational cost rather than a one-off install. The README points readers to the FAQ site and to a documentation site for installation and usage questions, which is where the project expects you to look; the README itself is a directory of links rather than a troubleshooting guide. There is also a commercial layer inside the product. A May 2026 changelog entry states that downloading test data through download.php and the analysis of runtime errors and wrong answers through reinfo.php were upgraded to paid services using a points currency marked with a coin icon. The same log describes users earning points for solving problems and administrators granting or spending them. If your institution expects every feature to be free, that is a real constraint, and you should check which functions sit behind the points system before you promise anything to teachers. Finally, the README does not publish throughput figures, so a large open contest with thousands of simultaneous submissions is a sizing question you have to answer on your own hardware. ## How HUSTOJ differs from HydroOJ, QDUOJ and SYZOJ The search data around this project is dominated by other judge names, which is a fair reflection of how people choose: they compare judges before they install one. The relevant difference is the stack. HUSTOJ is PHP plus a compiled C++ judge plus MySQL, installed by a shell script or a container image, with a LiveCD option for machines that cannot be provisioned normally. The projects people search alongside it, HydroOJ, QDUOJ, SYZOJ and LibreOJ, are typically built around a Node.js or similar runtime with a plugin model, and the README of HUSTOJ thanks several of them, including uoj, loj, syzoj, zoj and qduoj, for code and ideas it borrows. So the choice is less about features than about which runtime you can operate. If your administrators already maintain PHP and MySQL, HUSTOJ fits an existing skill set. If your team lives in Node.js and wants to write judging extensions as plugins, one of the Node-based judges will be less friction. The secondary difference is packaging: HUSTOJ ships a Dockerfile, a kubernetes directory and an APK in the repository root, which is more deployment surface than a typical judge project offers. ## Licence, maintenance and what an upgrade costs you HUSTOJ is GPL-2.0 free software, and the README is unusually explicit about what that means in practice. It states that if you modify the project and distribute it, meaning you install your derivative on a customer's server, you must provide your modified source and the GPLv2 text to that customer. It also states that running a derivative as a SaaS service on your own servers does not count as distribution, so you may rent it out without publishing source, and that a web interface coupled only through the database or HTTP API is not covered by the licence. The README also says the footer attribution may be removed, while the GPLv2 file under the web directory must be kept when you distribute. That is a permissive reading of the licence for service operators and a strict one for anyone shipping to client hardware. This is the project's own description, not legal advice; if you plan to sell a derivative, have a lawyer read the GPLv2 text in trunk/web. On maintenance, the last push was on 2026-09-23 and the repository is not archived, with releases dated 2026-08-19, 2026-07-09 and 2026-06-23. The changelog shows frequent small changes, including entries marked as patches in March 2025. Upgrading therefore means reading a dense log rather than a versioned changelog file, and since the README does not document rollback, you should snapshot the database and the /home/judge tree before you pull a new revision. ## Conclusion Adopt HUSTOJ if you want a self-hosted judge for a school, training centre or campus contest and you are willing to run a LAMP stack and a C++ judging backend on your own hardware. Do not adopt it if you need a hosted service, a Python-only stack, or a judge you can embed in a closed product without reading the GPL-2.0 note in the README. Before committing, verify the install path for your distribution, check whether the PHP and MySQL versions you plan to run are covered by the compatibility notes, and confirm that your expected submission volume fits the machine you have, since the README documents hardware requirements but not throughput. ## FAQ ### What is HUSTOJ used for? It is an online judge for ACM/ICPC and NOIP training, used to publish problems, run submissions through a compiled C++ judge and show a scoreboard during contests. The README describes it as cross-platform, easy to install, with a bundled problem bank and a low barrier to secondary development. ### Can I install HUSTOJ with Docker? Yes. The README lists a Docker installation route, and the repository ships a Dockerfile based on ubuntu:24.04 that installs nginx, mysql-server, php-fpm and the build toolchain, copies trunk to /trunk, runs docker/setup.sh, exposes port 80 and starts via /opt/docker/entrypoint.sh. The build takes APT_MIRROR and APT_CA arguments, and a single /volume volume is declared. ### Which Linux distributions does HUSTOJ support? The README gives installation instructions for Ubuntu 24.04, which it recommends for beginners, as well as Deepin 20+, CentOS and other distributions, plus a LiveCD download. It also documents changing the Ubuntu package mirror and removing Aliyun Shield before installing. ### How do I change the HUSTOJ template? Set the $OJ_TEMPLATE value in db_info.inc.php, which the README says lives by default in /home/judge/src/web/include. The bundled templates are demonstrated on the demo site with URLs such as ?tp=sidebar and ?tp=mdui. ### Is HUSTOJ free to use commercially? The README says that running a derivative as a SaaS service on your own servers does not count as distribution, so you may rent it out without publishing source, and that a web interface coupled only through the database or HTTP API is not covered by GPL-2.0. It also says that installing a modified version on a customer's server requires providing the modified source and the GPLv2 text to that customer. ## Sources - [License: GPL-2.0](https://github.com/zhblue/hustoj/blob/master/LICENSE) - [Project website](http://www.hustoj.com/?cat=2) - [README](https://github.com/zhblue/hustoj/blob/master/README.md) - [Releases](https://github.com/zhblue/hustoj/releases) - [zhblue/hustoj on GitHub](https://github.com/zhblue/hustoj) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zhblue-hustoj