Cafe Grader Docker

A containerized version of the CU Cafe Grader competitive programming judging system.

Table of Contents

• Docker Architecture
• Platform Compatibility
• Host Machine Setup
• Quick Start
• Default Credential
• Language Setup
• Data Persistence
• Development
• Logging
• Acknowledgements
• Source
• License

Docker Architecture

This Docker Compose setup consists of 3 containers:

• cafe-grader-web: Web interface for Cafe Grader management
• cafe-grader-worker: Background worker for submission compilation and judging
• cafe-grader-db: MySQL database for storing data

Platform Compatibility

• ✅ Fully Supported:
  • Native Linux: Fully functionbility (requires kernel cgroup configuration)
  • macOS: Full functionality with Docker
• ⚠️ Limited Support:
  • WSL (Windows Subsystem for Linux): Works but may affect some binary integrations like VS Code due to systemd compatibility issues
• ❓ Untested:
  • Windows Docker Desktop: Compatibility not yet verified

Host Machine Setup

Since Docker uses the host's kernel, we need to enable memory cgroups for proper isolation and resource management. This is required for IOI Isolate to function correctly.

Note: This step is only required for Linux machines. macOS and Windows(WSL) users can skip this section.

Linux Machine

1. Edit the GRUB configuration file:

   sudo vi /etc/default/grub

2. Add cgroup_enable=memory to the GRUB_CMDLINE_LINUX_DEFAULT line:

   GRUB_CMDLINE_LINUX_DEFAULT="cgroup_enable=memory"

3. Update GRUB and reboot:

   sudo update-grub
   sudo reboot

Raspberry Pi

1. Edit the boot configuration:

   sudo vi /boot/firmware/cmdline.txt

2. Add cgroup_enable=memory to the existing line:

   console=serial0,115200 multipath=off ... fixrtc cgroup_enable=memory
   

3. Reboot the system:

   sudo reboot

Then reboot using sudo reboot.

Quick Start

1. Clone the repository:

   git clone --recurse-submodules https://github.com/folkiesss/cafe-grader-docker.git
   cd cafe-grader-docker

2. Create environment file: Create a .env file with the following variables:

   # Grader
   GRADER_PROCESSES=2
   
   # Python Packages for Judge Environment
   # Space-separated list of Python packages to install in the grader virtual environment
   # For example: PYTHON_PACKAGES=numpy pandas matplotlib scipy
   PYTHON_PACKAGES=
   
   # MYSQL
   MYSQL_ROOT_PASSWORD=superStr@ngP@ssw0rd
   MYSQL_DATABASE=grader
   MYSQL_USER=grader_user
   MYSQL_PASSWORD=superStr@ngP@ssw0rd
   
   # Database Connection
   SQL_DATABASE_CONTAINER_HOST=cafe-grader-db
   SQL_DATABASE_PORT=3306
   
   # Rails Configuration
   RAILS_TIME_ZONE=Asia/Bangkok
   SECRET_KEY_BASE=GENERATE_A_SECURE_KEY_BASE_FOR_PRODUCTION  # can generate using `openssl rand -hex 64`

3. Build and run:

   docker compose build
   docker compose up -d

4. Access the application: Web interface: http://localhost:3000.

Default Credential

• User: root
• Password: ioionrails

Language Setup

The worker container includes support for:

Tested:

• Python
• C/C++
• Java
• Ruby
• Go
• Rust

To be tested (and updated for some languages):

• Pascal
• PHP
• Haskell

Please refer to https://github.com/cafe-grader-team/cafe-grader-web/wiki/Language-Setup for specific details

Data Persistence

The setup uses Docker volumes for data persistence:

• Database data: Stored in cafe-grader-db volume
• Storage data: Stored in cafe-grader-storage volume (test cases, problem files, uploads)
• Cache data: Stored in cafe-grader-cache volume (judge working directory)
• Logs: Optional volume mounting (uncomment in compose.yaml)

Backup and Restore

This repository includes automated backup and restore scripts for easy data management.

Create a Backup

./backup.sh

This will create a timestamped backup archive in the archives/ directory:

cafe-grader-docker/
├── backup.sh
├── restore.sh
└── archives/
    └── cafe-grader-backup-dd-mm-yyyy-hhmmss.tar.gz

The backup archive contains:

• Database (SQL dump)
• Storage volume (test cases, problem files, Active Storage files)
• Cache volume (judge data, compiled submissions)

List Available Backups

./restore.sh

This shows all available backup archives.

Restore from Backup

./restore.sh <archive_file>

For detailed step-by-step output, use the --debug flag:

./restore.sh --debug <archive_file>

Note: The MYSQL_ROOT_PASSWORD in your .env file must match the password used when the backup was created.

Migrate to Another Machine

1. Copy the backup archive to the target machine's archives/ directory (using any method: USB drive, network transfer, cloud storage, etc.)

2. Place the backup in the archives/ directory.

3. Restore the backup.

Upgrading from an older version? If you have an existing backups/ directory, running ./restore.sh will automatically migrate its contents to archives/ for you.

Development

Fallback

This Dockerfile use git clone to clone the latest version of Cafe Grader from https://github.com/nattee/cafe-grader-web. However, in case the newer version can't be built, please try to follow the following instructions.

1. Update submodule (in case this repo is outdated):

   git submodule update --remote

2. Check out to a specific version that still works:

   cd cafe-grader-web
   git checkout <commit_sha>

3. Edit this section in the common stage of Dockerfile then try to rebuild:

   # clone cafe-grader-web
   RUN git clone https://github.com/nattee/cafe-grader-web.git /cafe-grader/web
   
   # fallback if the latest version of cafe-grader-web is not compatible
   # COPY cafe-grader-web /cafe-grader/web

   It should look like this:

   # clone cafe-grader-web
   # RUN git clone https://github.com/nattee/cafe-grader-web.git /cafe-grader/web
   
   # fallback if the latest version of cafe-grader-web is not compatible
   COPY cafe-grader-web /cafe-grader/web

Logging

Please uncomment the logs volume in the compose.yaml file for saving logs.

Acknowledgements

This containerization wouldn't be complete without the efforts of these people:

• My greatest TA of all time (PongDev): For advice during the isolate cgroup debugging process.

Source

• Cafe Grader - The cafe-grader forks at Chula
• IOI Isolate - Secure sandbox system

License

This Docker containerization setup (Dockerfiles, compose configuration, and related scripts) is licensed under the MIT License. See the LICENSE file for details.

This containerization is provided as-is for educational and development purposes. Please refer to the Cafe Grader project for licensing information about the main application.