Homework Submission Server

This server provides a secure way to accept and run student homework submissions using Docker.

Setup and Installation

Prerequisites

• Python 3.6+
• Docker
• pip for installing Python packages

Installation

1. Clone the repository or download the files.

2. Install Python dependencies:

   pip install Flask docker

3. Build the Docker Image:

   Before running the server, you need to build the Docker image that will be used to run the submissions.

   docker build -t homework-runner .

4. Set a Secret Token:

   Open server.py and change the SECRET_TOKEN variable to a strong, randomly generated string. This is crucial for securing the /run endpoint.

   SECRET_TOKEN = 'YOUR_SECRET_TOKEN'  # Change this!

Running the Server

To start the server, run the following command:

python server.py

The server will start on http://127.0.0.1:8080.

API Endpoints

1. Submit Homework

• Endpoint: /submit
• Method: POST
• Content-Type: multipart/form-data

Each submission for a student is versioned automatically. If a student submits multiple times, they will be stored in numbered directories (e.g., submission-1, submission-2).

Form Fields:

• student_id (text): The ID of the student.
• password (text): The password for the student.
• file (file): The compressed homework file (.zip or .tar.gz). The archive should contain a run.sh script at its root.

Example Usage (using curl):

1. Create a sample run.sh script:

   echo '#!/bin/sh' > run.sh
   echo 'echo "Hello from my submission!"' >> run.sh
   chmod +x run.sh

2. Create a compressed archive:

   # For .tar.gz
   tar -czvf submission.tar.gz run.sh
   
   # For .zip
   zip submission.zip run.sh

3. Send the request:

   curl -X POST -F "student_id=12345" -F "password=password123" -F "file=@submission.tar.gz" http://127.0.0.1:8080/submit/homework1

2. Run Arbitrary Command (Instructor Only)

• Endpoint: /run
• Method: POST
• Content-Type: application/json
• Authentication: Authorization: Bearer YOUR_SECRET_TOKEN

This endpoint can run a command either inside a student's latest submission or in an empty temporary directory.

JSON Payload:

• command (string): The command to execute inside the container.
• student_id (string, optional): The ID of the student whose latest submission you want to run the command against. If omitted, the command runs in an empty directory.

Example 1: Run command on a student's latest submission

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SECRET_TOKEN" \
  -d '{"command": "ls -la", "student_id": "12345"}' \
  http://127.0.0.1:8080/run

Example 2: Run command in an empty directory

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SECRET_TOKEN" \
  -d '{"command": "echo Hello World"}' \
  http://127.0.0.1:8080/run

How It Works

1. Submission & Versioning: When a file is uploaded to /submit, the server saves it to a uniquely numbered directory named after the student's ID and submission number (e.g., submissions/12345/submission-1/).
2. Extraction: The server extracts the archive within that versioned directory.
3. Execution: A new Docker container is started using the homework-runner image. The student's versioned submission directory is mounted as a volume.
4. Logging: The server executes the run.sh script (for submissions) or a custom command (for /run), captures the output, and returns it in the JSON response.
5. Cleanup: The Docker container is automatically removed after execution.