Docker Installation

• Requirements
• Installation
  • Download the Full version
  • Download the Mini version
• Running for the first time
  • tl;dr: One command deploy
  • Available options
    • --cap-add
    • --rm
    • --name kjudge
    • --volume kjudge:/data
    • -p 8080:80
    • -e ADMIN_KEY=sample_key
  • Detached mode: -d

Requirements

All you need is Docker.

To run Docker on Windows and Mac, you will need your computer to have Virtualization enabled.

For OSX machines (Mac Pro, Macbooks), this should be enabled by default.

For Windows machines, Docker will complain if Virtualization is not enabled. Consult Google to find out how to enable it. For most computers, this involves changing a single setting in the BIOS setup.

Installation

With Docker installed, open up your favourite command line environment:

• Windows PowerShell on Windows
• Terminal on Linux and OSX

At this point, kjudge offers two versions of its Docker image:

• The full image with all compilers shipped (g++, fpc, Java, Python 2 and 3, Rust and Go). It has a quite large download size of around 600MBs and unpacked to about 1.6GB.
• The mini image with only g++ installed, with a smaller download size of around 70MBs.

However, both images ship the latest version of kjudge and updating the version should only incur a few MBs of download, as opposed to first-time downloads.

Download the Full version

Run the following command

docker pull natsukagami/kjudge:latest

Download the Mini version

Run the following command

docker pull natsukagami/kjudge:gcc

Running for the first time

tl;dr: One command deploy

Note: HTTPS is highly recommended, and the HTTPS setup guide is available here.

Replace sample_key in the following command with an actual secret key, then run it:

• For the full version

docker run --cap-add=CAP_SYS_ADMIN --cap-add=CAP_NET_ADMIN --rm --name kjudge --volume kjudge:/data -p 8080:80 -e ADMIN_KEY=sample_key natsukagami/kjudge:latest

• For the mini version

docker run --cap-add=CAP_SYS_ADMIN --cap-add=CAP_NET_ADMIN --rm --name kjudge --volume kjudge:/data -p 8080:80 -e ADMIN_KEY=sample_key natsukagami/kjudge:gcc

Either would start the kjudge system and make it listen on http://localhost:8080.

You can now move on to Hosting a contest.

To understand what each option do, read on.

Available options

--cap-add

Docker docs

--cap-add option grants kjudge's isolate sandbox additional Linux capabilities to freely use the Linux cgroups feature to limit and measure memory usage and CPU time when the contestant's program.

• CAP_SYS_ADMIN: Grants remount privilege to remount /sys/fs/cgroups as read-write (since Docker mounts Control Groups as read-only).
• CAP_NET_ADMIN: Grants network interface management privilege to create loopback interface for isolated environment.

If you receive errors similar to [isolate v2 daemon] mount: /sys/fs/cgroup: permission denied., use --privileged instead of --cap-add=CAP_XXXX to grant the container full privileges.

--rm

Docker docs

--rm tells Docker to remove any temporary file system when kjudge stops running.

--name kjudge

Docker docs

Gives a name to the container. This is useful later on, when we need to restart the judge (for example, after a machine reboot).

You can change kjudge to any name you want. This is also optional, Docker will give the container a random name (which you can see by running docker ps)

--volume kjudge:/data

Docker docs

Stores the kjudge database (inside the container's /data directory) into a Docker-managed volume named kjudge, so that restarting kjudge does not reset the entire database.

Docker gives you many more options regarding volumes, please read its docs to find out how you can bind /data to a directory on your own computer, or give the mounted volume a name.

-p 8080:80

Docker docs

Takes the container's port 80 (where kjudge is listening on) and bind it to your computer's port 8080.

You can change 8080 to any port you like.

-e ADMIN_KEY=sample_key

Give kjudge a pre-defined Admin Panel access key. It should be at least 6 characters long.

You can omit this option, and kjudge will give you a random key every time it starts.

Detached mode: -d

This can be used to tell Docker to run kjudge in the background, so you don't have to keep the command line window open.

kjudge log can still be accessed with docker logs kjudge (with kjudge replaced with the name given with --name).