tmselte/backend-evaluator repository overview

⁠TMS Backend Evaluator Service

The Backend Evaluator Service for TMS is an automated computer science submission evaluation system written in PHP⁠ and based on the Yii 2 Framework⁠.

⁠CONTAINERIZATION

⁠Linux

On Linux-based host systems it is possible to run the backend-evaluator application in a Docker container. You can either build the image manually from the Dockerfile.linux file, ot pull the latest stable or nightly images from our DockerHub.

Before starting a new container from the image, you should create a config.yml file with the access token and address of backend-core, then mount it as the /app/config.yml file. The entrypoint of the container is set to the yii script so you can directly start the desired job with the docker run command.

Example usage:

docker run -d --pull=always \
  --restart unless-stopped \
  --name <container-name> \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$(pwd)/config.yml:/app/config.yml" \
  tmselte/backend-evaluator:latest <auto-tester/poll|environment-validator/poll>

Note: this command runs the evaluator in the background, you can run it in the foreground by removing the -d flag.

⁠Windows

Windows-based host systems are also supported, but the Docker Engine of the host machine must be exposed through a TCP connection, and a firewall rule has to be created. We consider this a working, but experimental solution, until a named pipe support is added to the Docker PHP SDK. You can either build the image manually from the Dockerfile.windows file, ot pull the latest stable or nightly images from our DockerHub.

⁠Configuring Docker for TCP connection

In the Docker daemon settings (usually C:\ProgramData\Docker\config\daemon.json), add the following line to the JSON configuration to make Docker listen to TCP connections, then restart the Docker service.

{
  "hosts":  [
    "npipe://",
    "tcp://0.0.0.0:2375"
  ]
}

When using Docker Desktop for Windows, you should disable the "Expose deamon on tcp://localhost:2375 without TLS" option in the GUI Settings, as it only exposes the daemon to localhost. Instead, expose the deamon through manually editing the configuration in the GUI (Settings → Docker Engine) or through the windows-daemon.json file in the %USERPROFILE%\.docker\ directory. Restart the Docker service after modifying the configuration.

Note: if you want keep the named pipe connection option, don't forget to add that as well. It is usually named npipe://, npipe:////./pipe/docker_engine or npipe:////./pipe/docker_engine_windows, depending on how you installed Docker. See your default configuration and copy it from there.

Finally, you should create a firewall rule to allow incoming connections to the Docker daemon port (2375 by default). You can do this from the Windows Defender Firewall with Advanced Security application. Make sure to restrict the rule to trusted IP addresses only, e.g. to the Docker NAT network: 172.16.0.0 - 172.31.255.255. You can achieve this by executing the following Batch command in an elevated command prompt:

netsh advfirewall firewall add rule name="Docker over NAT" dir=in action=allow protocol=TCP localport=2375 remoteip=172.16.0.0/12

Note: for production use, you should secure the TCP connection with TLS or protect that machine with strict firewall rules!

⁠Running the container

Before starting a new container from the image, you should create a config.yml file with the access token and address of backend-core, then mount its parent directory to the C:\app\config\docker-windows\ directory. (?ounting the config file directly is not supported due to Windows related limitations.)

Docker on Windows automatically creates a default NAT network for Windows containers, so containers can access the host machine over it. On your host machine, you can find the IP address of this network by executing the ipconfig command and looking for the vEthernet (DockerNAT) adapter. (Could be named vEthernet (nat) as well.) You should use this IP address to connect to the Docker daemon from the container, by setting the dockerSocket configuration value to tcp://<docker-nat-ip>:2375 in the config.yml file.

The entrypoint of the container is set to the yii.bat script so you can directly start the desired job with the docker run command.

Example usage:

docker run -d --pull=always`
  --restart unless-stopped `
  --name <container-name> `
  -v "C:\path\to\config\file\folder:C:\app\config\docker-windows\" ``
  tmselte/backend-evaluator:latest <auto-tester/poll|environment-validator/poll>

Note: this command runs the evaluator in the background, you can run it in the foreground by removing the -d flag.