Chirun LTI Tool

The Chirun LTI tool provides a simple to use interface for instructors to upload content to a VLE to be automatically converted into accessible and flexible documents with Chirun. With this tool, the instructor does not need to have any knowledge of running Unix software or uploading content to a web-server in order to share the web-based output generated by Chirun.

Installation

Prerequisites

• A web server supporting PHP, such as Apache.
• PHP must be configured to allow calling the exec() function and have at least the following extensions enabled:
  • pdo
  • pdo_mysql or pdo_sqlite
  • yaml
• The following system packages must be installed:
  • curl
  • rsync
  • libyaml
  • docker
• Write access to an empty MySQL/SQLite database

LTI Tool Setup

Clone this repo and copy the software into an install directory (referred to as INSTALLDIR) visible to your web server. Copy the file config.dist.php to config.php and then edit the file to include your own site settings. Take particular note of the following variables,

Name | Description | Example -------------|-------------|--------- WEBDIR | The intended web path for accessing the tool | /lti INSTALLDIR | The full file system path to the tool's install directory | /var/www/webroot/lti PROCESSUSER | The "processing user" that will run the Chirun build tools via docker | programs DB_NAME | A database DSN specifying a database host and name | mysql:dbname=chirun;host=database.example.com DB_USERNAME | Database username | DB_PASSWORD | Database password |

User Permission Setup

Uploaded documents are compiled by running the Chirun software in a docker container. Since allowing access to docker is equivalent to giving root access to a user, this must be handled carefully. For separation of privileges a new Unix user must be created to be used as the Chirun processing user. This user should have access to docker via membership of the docker group.

Assuming your processing user will be named programs, the following commands creates the user and adds it to the docker group, ```

adduser programs

usermod -aG docker programs

```

Directory Permission Setup

The user running the web server process should be able to write to UPLOADDIR, CONTENTDIR and PROCESSDIR/logs, but not permitted to write to anything else in INSTALLDIR. As such, ensure directory permissions are setup as follows, where programs is your processing user and www-data is the primary unix group for the user running the web server process.

Directory | Mode | Owner:Group ----------|------|-------------- INSTALLDIR | 755 | programs:programs UPLOADDIR | 775 | programs:www-data CONTENTDIR | 775 | programs:www-data PROCESSDIR/logs |775 | programs:www-data

Sudo Permission Setup

The sudo command should be configured so that the user running the web server process (e.g. www-data) can start the Chirun processing script as the processing user with some particular environment variables populated. This can be setup by adding the following lines to the /etc/sudoers file,

``` www-data ALL = (programs) NOPASSWD: [PROCESSDIR]/process.sh Defaults env_keep += "PROCESSDIR" Defaults env_keep += "CONTENTDIR" Defaults env_keep += "UPLOADDIR" Defaults env_keep += "DOCKER_PROCESSING_VOLUME"

```

replacing [PROCESSDIR] with the full path to the processing directory.

Docker Setup

Prepare the docker daemon by pulling the Chirun image on the server. For example, log into the server as the processing user and run the command: $ docker pull chirun/chirun-docker:latest

Admin Directory Setup

The web server's rewriting engine should be used to direct all requests of the form lti/content/[...] to lti/index.php?req_content=[...]. In addition, the following directories should be made forbidden for public access:

• UPLOADIR
• PROCESSDIR
• INSTALLDIR/lib

The path WEBPATH/admin should also be protected and allow only server administrator access. An example Apache setup using Basic Authentication is shown below.

<Location /> Require all granted DirectorySlash Off RewriteEngine on RewriteRule /lti/content/(.*)$ /lti/index.php?req_content=$1 [L,QSA] </Location> <Location /lti/upload> Require all denied </Location> <Location /lti/process> Require all denied </Location> <Location /lti/lib> Require all denied </Location> <Location /lti/admin> AuthType Basic AuthName "Restricted admin section" AuthUserFile /etc/apache2/.htpasswd Require user admin </Location>

In this example a username and password for admin access can be setup by running the following command on the server,

```

htpasswd /etc/apache2/.htpasswd admin

```

LTI Setup

To use the Chirun LTI tool with your VLE, an administrator will need to add the tool to your own instance of the VLE. To do this, the VLE needs to be setup beforehand as a tool consumer in the admin panel accessible on your web server at https://chirun.example.com/lti/admin/.

Create a Name, Key, and Secret for your VLE using the Add New Consumer form on the admin page, and then forward that information on to your VLE administrator to be added as an external LTI tool. They might also need the URL for the LTI XML configuration: https://chirun.example.com/lti/xml/ or the LTI launch URL, https://chirun.example.com/lti/connect.php.

Build Process Information

When content is uploaded to the LTI tool for processing, the following series of steps occurs.

• First, a file is uploaded to the UPLOADDIR by the web server process. On upload a GUID is generated for the uploaded bundle of files. .zip files are extracted in-place.

• The processing script is started. The script runs partially in a container, and so sudo is used to start the script as the processing user with permission to use to docker.

• The source content is copied from the UPLOADDIR directory to the PROCESSDIR directory.

• When uploading raw .tex or .md files a standalone Chirun compatible course.yml file is created. If a Chirun config.yml file already exists as part of the upload, it is modified to inject the correct content web path and GUID.

• Chirun is run in a docker container using the newly prepared course.yml in the PROCESSDIR directory.

• If successful, the output is copied from the PROCESSDIR directory into the CONTENTDIR directory with the required directory permissions.

• Clean up is performed and the copy of the uploaded files in PROCESSDIR are deleted.

• Finally, the output of the process script is written to a log file at PROCESSDIR/logs/<guid>.log and the log is shown to the user.

Other Information

The UPLOADDIR directory should be emptied periodically to avoid filling the disk. For example, this can be handled by adding a cron job or systemd timer for the programs user.

An example command that clears the upload directory of all files could be,

find [INSTALLDIR]/upload/ -mindepth 1 -maxdepth 1 -exec rm -r -- {} +

replacing [INSTALLDIR] with the full path to the install directory. The find command can be tweaked with arguments such as -mtime to more finely tune what files are deleted.