README.md

kjudge

• kjudge
  • Project Goals
  • Quick start
    • Need more details?
  • Runtime dependencies
  • Command line switches
  • Build Instructions
    • Production build
    • Development build
  • Directory Structure
  • License

Project Goals

• As lightweightedly deployable as possible (single binary, minimal dependencies, Docker-compatible)
• User friendly
• Doesn't get in the way (take minimal resources)

Quick start

The fastest way to get kjudge up and runnning is through the official Docker image.

It contains:

• kjudge itself
• Compilers for C++, Pascal, Java, Go, Rust, Python 2 and 3
• The isolate sandbox

Please checkout the wiki for more information on how to get it up and running.

Need more details?

Check out the wiki or join our chatroom!

Runtime dependencies

It should run on all platforms Go compiles to.

Required binaries:

• isolate: The recommended sandbox. This is actually optional, however the only alternate sandbox implementation available (as of now) is the raw sandbox, which DOES NOT PROVIDE ANY GUARDS AGAINST FOREIGN CODE (which makes it okay to run when you are the only user). isolate is available on Linux systems only.

Command line switches

> ./kjudge -h
Usage of ./kjudge:
  -file string
    	Path to the database file. (default "kjudge.db")
  -https string
    	Path to the directory where the HTTPS private key (kjudge.key) and certificate (kjudge.crt) is located. If omitted or empty, HTTPS is disabled.
  -port int
    	The port for the server to listen on. (default 8088)
  -sandbox string
    	The sandbox implementation to be used (isolate, raw). If anything other than 'raw' is given, isolate is used. (default "isolate")
  -verbose
    	Log every http requests

Build Instructions

Warning: Windows support for kjudge is a WIP (and by that we mean machine-wrecking WIP). Run at your own risk.

External Dependencies:

cc:      anything that compiles SQLite 3
go:      >= 1.16
node.js: >= 12
yarn:    >= 1

Go dependencies: See tools.go. All Go dependencies can be installed with

scripts/install_tools.sh

Production build

Build steps:

scripts/production_build.sh

Development build

First time contributors: Please check out the Code of Conduct and Contributor Guidelines!

First, start the template generator and updater with

cd frontend
yarn && yarn dev

Note that it would block and watch for any updates on the front-end templates.

Now open a new terminal, run

go generate

to generate the models and load a development (live-reloading) version of the template packager.

Finally, run

go run cmd/kjudge/main.go

to run kjudge.

Directory Structure

embeds:   # Static assets that gets compiled into the binary
    templates # Generated templates from frontend
    assets:
        - sql # SQL migration schemas
cmd:          # Main commands
    - kjudge  # Main compile target
    - migrate # Database migration tool, useful for development
db # Database interaction library
docker    # Dockerfile and other docker-related packaging handlers
scripts   # Scripts that helps automating builds
models:          # Database entities
    - generate   # Generator for models
    - verify     # Model verification helpers
frontend:   # Template files and front-end related source codes
    - html  # HTML [template] files
    - css   # CSS files
    - ts    # TypeScript files
worker:        # Automatic judging logic
    - raw      # Raw and isolate are 2 sandbox implementations
    - isolate
server:        # Root of server logic
    - auth     # Authentication logic and session handlers
    - template # Template resolver and renderer implementation
    - user     # /user page handling and contexts
    - admin    # /admin (Admin Panel) page handling and contexts
    - contests # /contests (main contest UI) page handling and contexts
test: # Go code testing handling logic and data
    - integration # Integration tests
tests # Test-handling logic

License

GNU Affero General Public License v3.0, which disallows distributing closed-source versions, so don't do it.