Chirun LTI server
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 thePROCESSDIR
directory. -
When uploading raw
.tex
or.md
files a standalone Chirun compatiblecourse.yml
file is created. If a Chirunconfig.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 thePROCESSDIR
directory. -
If successful, the output is copied from the
PROCESSDIR
directory into theCONTENTDIR
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.