Deploying INGInious

Introduction

INGInious is an open-source automated code grading platform designed for computer science education. Developed at UCLouvain in Belgium, INGInious provides a secure environment for students to submit code that is automatically tested and graded against instructor-defined test cases. The platform supports virtually any programming language through its Docker-based grading infrastructure.

What sets INGInious apart is its security model - student code runs inside isolated Docker containers, protecting the host system from malicious or buggy submissions. This allows instructors to safely accept and evaluate arbitrary code from untrusted sources.

Key highlights of INGInious:

• Multi-Language Support: Grade code in Python, Java, C, C++, Rust, Go, and virtually any other language
• Secure Execution: Student code runs in isolated Docker containers
• Custom Grading: Write your own test scripts in any language
• LTI Integration: Connect to Moodle, Canvas, Blackboard, and other LMS platforms
• WebDAV Support: Manage tasks through file-based access
• Real-Time Feedback: Students receive immediate results on submissions
• Plagiarism Detection: Integration with plagiarism checking tools
• Collaborative Courses: Multiple instructors can manage courses together
• API Access: RESTful API for custom integrations
• Template System: Reuse grading containers and configurations
• Detailed Analytics: Track student performance and common errors

This guide walks through deploying INGInious on Klutch.sh using Docker, setting up an automated grading platform for programming courses.

Why Deploy INGInious on Klutch.sh

Deploying INGInious on Klutch.sh provides several advantages for code grading:

Simplified Deployment: Klutch.sh handles the container orchestration automatically. Push to GitHub and your grading platform deploys without manual server configuration.

Persistent Storage: Attach persistent volumes for courses, submissions, and user data. Your educational content survives container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure submission of student code and credentials.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on expected submission volume. Handle exam peaks by scaling up resources.

Secure Isolation: The container-based architecture ensures student code cannot affect other submissions or the platform itself.

Prerequisites

Before deploying INGInious on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your INGInious configuration
• Basic familiarity with Docker and containerization concepts
• A MongoDB database (can be deployed separately)
• Understanding of the programming languages you’ll be grading

Understanding INGInious Architecture

INGInious consists of several components:

Web Application: The Flask-based frontend that students and instructors interact with.

Agent System: Manages Docker containers for code execution and grading.

MongoDB Database: Stores courses, tasks, submissions, and user data.

Grading Containers: Language-specific Docker images that execute and test student code.

Task Repository: File-based storage for course definitions and test cases.

Preparing Your Repository

To deploy INGInious on Klutch.sh, create a GitHub repository containing your configuration.

Repository Structure

inginious-deploy/
├── Dockerfile
├── configuration.yaml
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ingi/inginious:latest

# Set environment variables
ENV INGINIOUS_WEBAPP_HOST=${INGINIOUS_WEBAPP_HOST:-0.0.0.0}
ENV INGINIOUS_WEBAPP_PORT=${INGINIOUS_WEBAPP_PORT:-8080}

# MongoDB configuration
ENV MONGO_HOST=${MONGO_HOST:-mongodb}
ENV MONGO_DATABASE=${MONGO_DATABASE:-inginious}

# Copy configuration
COPY configuration.yaml /opt/inginious/configuration.yaml

# Create directories for tasks and submissions
RUN mkdir -p /opt/inginious/tasks /opt/inginious/submissions

# Expose the web interface port
EXPOSE 8080

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/ || exit 1

# Volumes
VOLUME ["/opt/inginious/tasks", "/opt/inginious/submissions"]

# Start INGInious webapp
CMD ["inginious-webapp", "--config", "/opt/inginious/configuration.yaml"]

Configuration File (configuration.yaml)

Create a configuration.yaml file:

# Web application settings
webapp:
  host: "0.0.0.0"
  port: 8080

# MongoDB settings (using environment variables)
mongo:
  host: ${MONGO_HOST}
  database: ${MONGO_DATABASE}

# Task and submission directories
tasks_directory: /opt/inginious/tasks
submissions_directory: /opt/inginious/submissions

# Backend settings
backend: local

# Authentication
auth:
  - name: local
    type: local

# Superadmins
superadmins:
  - admin

# Plugin configuration
plugins: []

# WebDAV settings
webdav_host: "0.0.0.0"
webdav_port: 8081

Environment Variables Reference

Variable	Required	Default	Description
INGINIOUS_WEBAPP_HOST	No	0.0.0.0	Web application bind address
INGINIOUS_WEBAPP_PORT	No	8080	Web application port
MONGO_HOST	Yes	-	MongoDB hostname
MONGO_DATABASE	No	inginious	MongoDB database name
REGISTRY	No	-	Docker registry for grading containers
VERSION	No	latest	Container version tag

Deploying INGInious on Klutch.sh

Once your repository is prepared, follow these steps to deploy INGInious:

Set Up MongoDB

INGInious requires MongoDB for storing data. You can:

• Deploy a MongoDB app on Klutch.sh
• Use MongoDB Atlas or another managed service
• Use an existing MongoDB instance

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile configuration.yaml .dockerignore
git commit -m "Initial INGInious deployment configuration"
git remote add origin https://github.com/yourusername/inginious-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “grading” or “inginious”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your INGInious Dockerfile.

Configure HTTP Traffic

INGInious serves its web interface over HTTP. In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 8080

Set Environment Variables

In the environment variables section, add the following:

Variable	Value
MONGO_HOST	Your MongoDB hostname
MONGO_DATABASE	inginious

Attach Persistent Volumes

Persistent storage is essential for courses and submissions. Add:

Mount Path	Recommended Size	Purpose
/opt/inginious/tasks	10 GB	Course definitions and test cases
/opt/inginious/submissions	50+ GB	Student submissions

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the INGInious container
• Provision an HTTPS certificate

Access INGInious

Once deployment completes, access your INGInious instance at https://your-app-name.klutch.sh. You can start creating courses and tasks.

Creating Courses and Tasks

Course Structure

Courses in INGInious are organized as:

tasks/
└── my-course/
    ├── course.yaml
    ├── task1/
    │   ├── task.yaml
    │   ├── run
    │   └── student/
    └── task2/
        ├── task.yaml
        └── run

Creating a Course

1. Create a folder in /opt/inginious/tasks/
2. Add a course.yaml file:

name: "Introduction to Programming"
admins:
  - instructor
accessible: true
description: "Learn basic programming concepts"

Creating a Task

Each task needs:

1. task.yaml: Task metadata and problem description
2. run: Grading script
3. student/: Template files for students

Example task.yaml:

name: "Hello World"
author: "Instructor"
accessible: true
context: |
  Write a Python program that prints "Hello, World!"

environment: python3

problems:
  code:
    type: code
    name: "Your Code"
    language: python
    header: "Write your solution here:"

Example run script:

#!/bin/bash
# Run student code and check output
output=$(python3 student/code.py 2>&1)
expected="Hello, World!"

if [ "$output" == "$expected" ]; then
    echo "Correct!"
    exit 0
else
    echo "Expected: $expected"
    echo "Got: $output"
    exit 1
fi

Grading Containers

INGInious provides pre-built containers for common languages:

Container	Languages
ingi/inginious-c-base	C, C++
ingi/inginious-python	Python 2/3
ingi/inginious-java	Java
ingi/inginious-multilang	Multiple languages

LMS Integration

LTI Configuration

Connect INGInious to your LMS:

1. Enable LTI in configuration
2. Generate consumer key and secret
3. Configure your LMS with INGInious as an external tool
4. Set up grade passback

Moodle Integration

1. In Moodle, add External Tool
2. Enter INGInious URL
3. Add consumer credentials
4. Students access tasks through Moodle

Troubleshooting Common Issues

Grading Not Working

Symptoms: Submissions hang or fail to grade.

Solutions:

• Verify Docker is available for grading containers
• Check grading container images are accessible
• Review agent logs for errors

MongoDB Connection Issues

Symptoms: Cannot save data, authentication errors.

Solutions:

• Verify MongoDB host is accessible
• Check database permissions
• Ensure MongoDB is running

Slow Grading

Symptoms: Long wait times for results.

Solutions:

• Increase CPU allocation for parallel grading
• Optimize grading scripts
• Pre-pull commonly used containers

Additional Resources

• INGInious Documentation
• INGInious GitHub Repository
• INGInious Docker Image
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying INGInious on Klutch.sh gives you a powerful automated code grading platform with secure execution, automatic builds, and persistent storage. The Docker-based grading architecture ensures student code cannot compromise your system while supporting virtually any programming language.

Whether you’re teaching introductory programming courses or advanced algorithm classes, INGInious on Klutch.sh provides the foundation for scalable, automated assessment that gives students immediate feedback on their work.