README

kjudge

Build Status Docker Image Version (latest semver) godoc License is AGPLv3

Project Goals

  • As lightweightedly deployable as possible (single binary, minimal dependencies)
  • 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!

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 --help
Usage of ./kjudge:
  -file string
    	Path to the database file (default "kjudge.db")
  -sandbox string
    	The sandbox implementation to be used (isolate, raw). If anything other than 'raw' is given, isolate is used. (default "isolate")

Build Instructions

External Dependencies:

cc:      anything that compiles SQLite 3
go:      >= 1.13
node.js: >= 9
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, 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

assets:   # Static assets that gets compiled into the binary
    - sql # SQL migration schemas
cmd:          # Main commands
    - kjudge  # Main compile target
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
static # [GENERATED BY FILEB0X]
templates   # Generated templates from frontend
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

License

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

Expand ▾ Collapse ▴

Documentation

Overview

    Package kjudge (and the entire module) provides a little contest management system that can.

    Index

    Constants

    View Source
    const (
    	Version  = "0.4.1"
    	Codename = "Misaki Shokuhou"
    )

      The version and codename of the system. We typically pick an anime JK name as the codename for every minor version.

      Variables

      This section is empty.

      Functions

      This section is empty.

      Types

      This section is empty.

      Source Files

      Directories

      Path Synopsis
      cmd
      migrate
      Command migrate performs migration on a given database.
      Command migrate performs migration on a given database.
      Package db manages the DB part of the kjudge package.
      Package db manages the DB part of the kjudge package.
      Package models defines all the data models used in the database, as well as methods to acquire and modify them.
      Package models defines all the data models used in the database, as well as methods to acquire and modify them.
      generate
      Command "generate-models" reads the model information from the "models/models.json" file, and generate the relevant "models/generated.go" file.
      Command "generate-models" reads the model information from the "models/models.json" file, and generate the relevant "models/generated.go" file.
      verify
      Package verify implements certain verification methods for simple data structures.
      Package verify implements certain verification methods for simple data structures.
      Package server provides the back-end implementation of the kjudge app.
      Package server provides the back-end implementation of the kjudge app.
      admin
      Package admin defines admin routes.
      Package admin defines admin routes.
      auth
      Package auth implements the authentication functions for the server.
      Package auth implements the authentication functions for the server.
      httperr
      Package httperr provides some convenience functions to create echo HTTP errors.
      Package httperr provides some convenience functions to create echo HTTP errors.
      user
      User implements a group that handle /user requests.
      User implements a group that handle /user requests.
      Package tests handles multiple test uploading.
      Package tests handles multiple test uploading.
      Package worker provides a job-processing interface based on a sandbox implementation.
      Package worker provides a job-processing interface based on a sandbox implementation.
      isolate
      Package isolate provides a safe sandbox on Linux using the "isolate" program.
      Package isolate provides a safe sandbox on Linux using the "isolate" program.
      raw
      Raw implements a "raw" sandbox.
      Raw implements a "raw" sandbox.