This tutorial will walk you through the steps to set up an instance of the ISLE server program to serve your students.
Running the server requires the following software tools:
The ISLE server should run on a POSIX-based system (preferably a Linux distribution). For this guide, we assume that you are on the latest Ubuntu LTS release. The steps will be similar for other distributions (e.g., Debian or CentOS), but might need to be slightly adapted.
We will use
nvm allows you to install the newest versions of Node.js (which are not currently available through
apt) and manage multiple installations at once. Following the official
nvm documentation, we can use
wget to download and run a script to install
nvm in your home directory (specifically to
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.2/install.sh | bash
$ wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.2/install.sh | bash
nvm right away, you need to either log out and in again or source the
~/.profile file again:
$ source ~/.profile
To ensure that
nvm is up and running, we can print its version
We can now install the latest LTS release of Node.js via
$ nvm install --lts
nvm ls-remote will print a list of all available versions)
This will also install
npm, the official package manager used by Node.js to install external dependencies.
Let's first run the following command to update the packages list to ensure that you have the most recent version of the listings:
$ sudo apt update
To install MongoDB, we can use
apt since Ubuntu's package repositories include an up-to-date version of MongoDB:
$ sudo apt install -y mongodb
After installation, the database server should automatically be started. To check, run
$ sudo systemctl status mongodb
You can install Git by running
$ sudo apt-get install git-core
Afterwards, you can clone the git repository to acquire the source code:
$ git clone https://github.com/isle-project/isle-server
After changing into the new directory
$ cd isle-server
we can install its external dependencies via
$ npm install
You will now need to make a few changes to the contents of the
isle-server directory. For example, you might have noticed that the files in the
credentials folder have been encrypted (or rather transcrypted) to protect sensitive information. Please get in touch in case you would like to get access to our configuration.
Otherwise, you want to override the JSON files in this folder.
By default, we use Mailgun to send email notifications. The mailgun.json file should look as follows:
<pass> are your Mailgun credentials.
The tokens.json file is a JSON file with two keys:
<instructor_key> should be replaced with a chosen key that can be handed to faculty to obtain instructor access to the server on the isle-dashboard. The
<passphrase> can be any confidential string. It is used to sign the JSON web tokens used for user authentication.
Finally, you want to change the
etc/config.json file. It looks like this:
You should change the
server field to the server address from where your requests will be processed. Since ISLE requires HTTPS, you will need a SSL certificate and key. The paths for the certificate and key should be entered into the
key fields, respectively. You will need to receive these files from a certificate authority. Let's Encrypt is a popular certificate authority which generates certificates for free. You can leave the
mongodb field as-is unless you desire to host your MongoDB instance on a separate database server than your ISLE application server.
Setting up nginx
We suggest to use nginx as the web server for the ISLE server program. You can obtain a recent version of the software via
$ sudo apt install nginx
isle-server repository contains server configuration files for use with nginx in the /etc/nginx sub-directory. To use the contents of this configuration directory in place of the existing nginx confinpm install -g npmguration directory, you can copy the contents of the configuration directory to
$ sudo cp -R /path/to/isle-server/etc/nginx /etc/nginx
Warning: you might want to backup an existing
/etc/nginx directory first via
sudo mv /etc/nginx /etc/nginx-backup.
After editing the ISLE server configuration located in
sites-available to point to the correct certificate locations and changing the server name, create a symlink to enable it:
$ sudo ln -s /etc/nginx/sites-available/isle /etc/nginx/sites-enabled/isle
Finally, restart nginx.
$ sudo service nginx restart
Serving Compressed Files
To reduce the amount of data sent over the wire, we enable the lossless brotli compression algorithm, a successor to gzip. The latter is newer and not supported in nginx by default. To install brotli, run the following:
$ sudo apt-add-repository -y ppa:hda-me/nginx-stable
$ sudo apt-get update
$ sudo apt-get install brotli nginx nginx-module-brotli
To enable the Brotli module, we uncomment the following commands in
# ngx_brotli filter module - used to compress responses on-the-fly.
# ngx_brotli static module - used to serve pre-compressed files.
# Both modules could be used separately
We can then add Brotli compression by adding the following:
Start the ISLE server program
Navigate again into the isle-server directory. To start the server program in the background, we advise to use a program like pm2 to ensure that the process runs continuously. As
sudo, install it with the command
npm install pm2 -g
pm2, we can start the server as follows:
pm2 start lib/index.js --name isle-server
Automatically restart on reboot
To restart the ISLE server on system reboot, initialize the
pm2 startup script via:
You can save the currently running
pm2 processes to the startup script via
The ISLE server should now be up and running and accept requests!