Project

General

Profile

Documentation » Documentation 2024-1 »

Linux and Docker Support 2024-1

Back to Table of Contents

Summary of changes.

  • Support for server mode implementations of GIFT in Linux and Docker.
  • All Linux and Docker support files are now included in the GIFT release and no longer require a separate download.
  • Simplified installation for Linux with the entire process handled by a single script and no additional commands needed after unzipping the download.

Linux

Setting Up GIFT in Linux (everythings still referring to 2023 release here)

The general process for setting up GIFT to run in Linux consists of pulling GIFT's Linux dependencies into the release folder and then running the installer to enable the use of some terminal commands in Linux. The general process for doing this is outlined below.

  1. Download the .zip file of the 2023-1 GIFT release from the Downloads page to your Linux machine
  2. Extract the .zip after downloading.
  3. Open a terminal window and navigate to the folder where the zip was extracted
  4. Run the following command to automatically build and install GIFT for Linux: 
    GIFT_2023-1/release_2023-1/GIFT/scripts/dev-tools/Linux/installGIFT
  5. Wait for GIFT to finish installing, which will be indicated by a "BUILD SUCCESSFUL" message. You should see some messages in the command terminal while the install completes.
  6. If you are using a headless machine without a GUI, you'll also likely want to modify GIFT_2022-1/release_2022-1/GIFT/common.properties to replace all instances of "localhost" with the IP address of the Linux machine. Machines with GUIs can skip this step.
    • This is needed to ensure that another machine connecting to this Linux instance of GIFT uses the same host address for all of GIFT's webpages.

Since the GIFT release was already precompiled in Windows, the bulk of the build will be skipped in Linux. In general, this should be fine, since the JAR files in GIFT_2023-1/release_2023-1/GIFT/bin should work the same in Windows and in Linux because they use the same Java bytecode. If you want to completely recompile GIFT in Linux for whatever reason, such as if you are making code changes to it, you can run GIFT_2023-1/release_2023-1/GIFT/cleanBuild before running the installer so that GIFT rebuilds from scratch.

Running GIFT in Linux

Running GIFT in Linux is a bit more manual than in Windows, since the existing Linux scripts were designed for terminals, but the general process involves kicking off the same Java processes that are used in Windows. Steps to perform this startup process are outlined below

  1. Run the following command to launch GIFT: 
    GIFT_2023-1/release_2023-1/launchGIFT &
    • The & is useful if you plan on running other commands in the same terminal afterwards but can be omitted if desired.

Experiences from here will differ slightly depending on whether your machine has a usable GUI.

For machines with GUIs

  1. Once GIFT is fully running, a message will appear in the system tray indicating that GIFT is running. GIFT should generally start within a minute, though this can vary with the RAM available to the system
  2. Open a browser to http://localhost:8080/dashboard. You should see the GIFT login page.
  3. Sign in using your gifttutoring.org credentials. You should be taken to the "Take a Course" page and should see a list of courses.

For machines without GUIs

  1. A series of console statements will be printed out while GIFT is starting. Once a few seconds have gone by without any more of these statements appearing, GIFT can be considered started.
  2. On another machine with a browser, open http://Host.Machine.IP.Address:8080/dashboard using the browser, replacing "Host.Machine.IP.Address" with a network address for the host machine. You should see the GIFT login page.
  3. Sign in using your gifttutoring.org credentials. You should be taken to the "Take a Course" page and should see a list of courses.

Once GIFT is running, you can proceed to run courses or use other features of the GIFT Dashboard.

If the machine hosting GIFT does not have a GUI, you may find it useful to use the Web Monitor in GIFT's Dashboard to view the status of GIFT's modules and internal messages. This can be accessed using the Modules tab at the top of the Dashboard, as seen below:

Running Courses

Running courses using GIFT in Linux works the same as it does in Windows. To confirm that all of GIFT's modules are properly prepared to run courses, you can use the following steps to test their interactions.

  1. Sign into GIFT's login page if you have not already done so. Steps to do this are outlined in the previous section.
  2. Hover your mouse over the "Hello World" course and click "Take Course". After the page loads, you should see a welcome message appear in the center of the page.
  3. Click the arrow button to the right of "Example Guidance". The course should end and you should be taken back to the "Take a Course" page.

A successful completion requires coordination from GIFT's Domain, UMS, LMS, Pedagogical, Learner, and Tutor modules as well as the GIFT Dashboard, so these steps act as a quick and easy way to confirm that the majority of GIFT's core modules and processes are working. The remaining two modules, Gateway and Sensor, are discussed in the limitations section below.

Stopping GIFT in Linux

  1. Run the following command to stop all processes launched by GIFT: 
    GIFT_20233-1/release_2023-1/stopGIFT &
    • You should see a series of "Stopping GIFT process" messages appear. Once a few seconds have gone by and no more of these messages appear, GIFT can be considered stopped.
    • Again, the & is unneeded if you don't plan on running more terminal commands.

If your Linux machine has a GUI, you can alternatively close GIFT using the system tray icon, just like in Windows. To do this, right-click the system tray icon, click "Exit", then click "Yes

Once GIFT has been stopped, it can be started again using the instructions in the previous sections.

Notable Limitations of GIFT in Linux

Since support for Linux in the 2023-1 release of GIFT is new, there are a few known problem areas that are planned to be refined in future GIFT releases. The section below outlines a few of these problem areas and suggest ways to either avoid known problems or work around them if possible.

Training Applications

Many of GIFT's existing interoperability classes in the Gateway module currently rely on Windows .dll files in order to interact with the training applications that they support. As a result, using GIFT with these training applications is unlikely to work unless Linux-specific libraries for these interoperability classes can be found. In some cases, this might not be possible, such as when an training application does not support Linux in the first place, such as with PowerPoint. Other training applications that only rely on network communications, such as TCP socket connections, stand a much better chance to work, but firewall and other network rules may need to be handled differently to support them, particularly for Docker containers.

No training applications are officially supported as of yet. Some training applications may work with minor changes, such as adjustments to GIFT's configuration files, but an exact list of these is not known. Problems with training applications can be avoided altogether by only using course objects within GIFT that do not have Real-Time Assessment components and therefore do not use external training applications, such as Information as Text, Survey/Test, media (images, videos, etc.), Authored Branch, etc.

Remote Gateway Module

The downloadable version of the Gateway module that is used when GIFT is run in Server mode currently only supports Windows, and cannot be run in Linux. For context, this remote Gateway module is used when a course requires access to a training application while GIFT is running in server mode, which is done to allow the Gateway module to run on the operating system where the training application in question is present. Server mode in general will work just fine in Linux, and any Windows clients connecting to GIFT's webpages will be able to run the Gateway module as usual. Linux clients connecting to a Linux server, however, will not be able to run courses that rely on training applications.

If support for Linux clients is needed, rebuilding the remote Gateway module for Linux is feasible and would likely only require changing the .bat files and Ant configurations that are used to build and run it, though this was not implemented for the 2023-1 release. That said, running specific training applications using the remote Gateway module in Linux is another matter entirely, due to the reasons mentioned in the previous section.

Sensors

Like with training applications, most of GIFT's sensor implementation classes in the Sensor module rely heavily on .dll files, .exe files and other Windows-specific utilities and, as a result, will not work in Linux. Since GIFT doesn't connect to any sensors by default, this will only be apparent if GIFT_2023-1/release_2023-1/config/sensor/sensor.properties is changed to use a sensor configuration file in an attempt to connect to a sensor.

As with training applications, no sensors are officially supported when running GIFT in Linux. The default Self Assessment Sensor (pictured below) should generally work just fine since it is entirely Java-based, but attempting to use other sensor configuration files will likely cause an error and prevent GIFT from launching.

Docker

The 2023-1 release of GIFT also contains supporting files to allow GIFT to run as a Docker container using Docker Compose. The scripts that are included were designed primarily with Docker Desktop for Windows in mind, but the important logic all uses core Docker commands and should work fairly consistently on any platform that supports Docker Compose.

Setting Up GIFT for Docker

When using Docker, most of the setup for GIFT will be handled automatically using the Dockerfile.

  1. Download the .zip file of the 2023-1 GIFT release from the Downloads page to your machine
  2. Extract the .zip after downloading.
  3. When utilizing GIFT in server mode via docker you will also need to make use of the DomainContentServerHost setting in GIFT's GIFT_2023-1\release_2023-1\GIFT\config\common.properties file. Uncomment the setting by removing the preceding # and enter localhost as the value.

Building the GIFT Docker Image

Before GIFT can be run as a container in Docker, an image for it first needs to be created. The steps to do this are outlined below:

In Windows using Docker Desktop

  1. Navigate to GIFT_2023-1\release_2023-1\GIFT\scripts\docker and run buildImage.bat
  2. A console window should appear showing the build output. If the build succeeds, a BUILD SUCCESSFUL message should briefly appear before the console disappears automatically.

In Linux using Docker

  1. Navigate to GIFT_2023-1/release_2023-1 and run 
    docker build --progress=plain -t gift-image -f GIFT/scripts/docker/Dockerfile .
    • The console window should begin showing the build output. If the build succeeds, a BUILD SUCCESSFUL message should appear.

Running the GIFT Docker container

With the GIFT Docker image created, GIFT can now be run as a Docker container using the instructions below:

In Windows using Docker Desktop

  1. Navigate to GIFT_2023-1\release_2023-1\GIFT\scripts\docker and run composeUpContainers.bat
  2. A console window should appear showing the console output of the Docker container. If the launch succeeds, a "GIFT is Running" message will appear in the console.

In Linux using Docker

  1. Navigate to GIFT_2023-1/release_2023-1/GIFT/scripts/docker and run 
    docker compose up
    • If the container launch succeeds, a "GIFT is Running" message will appear in the console.

Once the Docker container is running, interacting with GIFT and running courses generally works identically to how it does when running GIFT in Linux normally. The instructions in the previous sections on how to connect to the GIFT webpage and run courses can be used again here to verify that GIFT's core processes are running as intended.

Stopping the GIFT Docker container

While the GIFT container is running, you can use the following commands to stop the container:

In Windows using Docker Desktop

  1. Navigate to GIFT_2023-1\release_2023-1\GIFT\scripts\docker and run composeDownContainers.bat
  2. A console window should briefly appear to show the status of closing the containers. Once the containers are closed, the console window should close automatically.

In Linux using Docker

  1. Navigate to GIFT_2023-1/release_2023-1/GIFT/scripts/docker and run 
    docker compose down

Configuring the GIFT Docker container

Since GIFT is using Docker Compose, it has a docker-compose.yml file at GIFT_2023-1/release_2023-1/GIFT/scripts/docker that can be used to change the configuration settings of GIFT's modules. As things currently stand, most of GIFT's configurations still rely on the configs folder rather than environment variables, so most of these settings cannot be changed in the Docker compose file and currently require rebuilding the GIFT image when they are changed.

It's worth noting that the docker-compose.yml file also defines the port mappings for the GIFT Dashboard at :8080, Tutor server at :8090, and Domain content server at :8885, so if you want to change the ports that the Docker container uses, you can change the port numbers in these mappings. That said, if you do this, make sure to change the same port numbers in common.properties as well and then rebuild the Docker image, otherwise GIFT's processes will still try to use the old port numbers.