Linux Support 2022-1¶

!!! NOTE !!!
Support for Linux in the 2022-1 release of GIFT is an experimental feature that has not been through rigorous testing and is currently intended for developers only. Certain distributions of Linux may require installing additional software or changing some configurations, and certain features of GIFT may not work the same as on Windows or may not work at all in Linux. Known problems and limitations are listed in the documentation below. If you encounter any bugs or would otherwise like technical support with running GIFT in Linux, please use the forum:"Troubleshooting" forum.

• Linux Support 2022-1
  • Setting Up GIFT in Linux
  • Running GIFT in Linux
    • For machines with GUIs
    • For machines without GUIs
  • Running Courses
  • Stopping GIFT in Linux
  • Notable Limitations of GIFT in Linux
    • Training Applications
    • Remote Gateway Module
    • Sensors
• Docker Support 2022-1
  • Setting Up GIFT for Docker
    • For Windows using Docker Desktop
    • For Linux using Docker
  • Building the GIFT Docker Image
    • In Windows using Docker Desktop
    • In Linux using Docker
  • Running the GIFT Docker container
    • In Windows using Docker Desktop
    • In Linux using Docker
  • Stopping the GIFT Docker container
    • In Windows using Docker Desktop
    • In Linux using Docker
  • Configuring the GIFT Docker container

Setting Up GIFT in Linux¶

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 2022-1 GIFT release from the Downloads page to your Linux machine
2. Download release_2022-1_Linux_deps.zip. This contains the dependencies needed to run GIFT in Linux, as well as a few minor script changes.
3. Extract both .zips next to each other in the same folder, similar to what's shown below:
   • 
4. Open a terminal window and navigate to the folder where these zips were extracted
5. Run the following command to copy the Linux dependencies into the extracted GIFT release:

   cp -RT release_2022-1_Linux_deps/ GIFT_2022-1/

   • Note: If you renamed the .zip files upon downloading them, replace the file names in the above command with your own.
6. Check that GIFT_2022-1/GIFT/external now contains a file named opendkf-11-linux.x64.GIFT.tar.gz
7. Run the following command to automatically build and install GIFT for Linux:

   GIFT_2022-1/release_2022-1/GIFT/scripts/dev-tools/Linux/installGIFT

   • If you get a "Permission denied" error, you'll need to give the installer execute permission by running this command first and then rerunning the previous command:

     chmod +x GIFT_2022-1/release_2022-1/GIFT/scripts/dev-tools/Linux/installGIFT

8. 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.
9. 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_2022-1/release_2022-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_2022-1/release_2022-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_2022-1/release_2022-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. Run 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_2022-1/release_2022-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 2022-1 release of GIFT is experimental, 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.

As GIFT has not been fully regression-tested in Linux, no training applications are officially supported in Linux 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 2022-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_2022-1/release_2022-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 Support 2022-1¶

The .zip of Linux dependencies 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. That said, the Linux dependencies still need to be added to the downloaded GIFT release just like when manually installing in Linux. The steps for this are outlined below:

1. Download the .zip file of the 2022-1 GIFT release from the Downloads page to your Linux machine
2. Download release_2022-1_Linux_deps.zip. This contains the dependencies needed to run GIFT in Linux, as well as a few minor script changes.
3. Extract both .zips next to each other in the same folder, similar to what's shown below:
   • 
4. Copy the Linux dependencies into the extracted GIFT release. The steps here will vary depending on your plaform.

For Windows using Docker Desktop¶

• Drag the release_2022-1_Linux_deps\release_2022-1 folder onto the GIFT_2022-1 folder. If you are asked whether you want to overwrite existing files, choose "Yes"

For Linux using Docker¶

• Open a terminal window and navigate to the folder where these zips were extracted and run the following command :

  cp -RT release_2022-1_Linux_deps/ GIFT_2022-1/

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_2022-1\release_2022-1\GIFT\scripts\docker and run buildImage.bat
2. A console window should appear showing the build output. If the build succeeds, the a BUILD SUCCESSFUL message should briefly appear before the console disappears automatically.

In Linux using Docker¶

1. Navigate to GIFT_2022-1/release_2022-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, the a BUILD SUCCESSFUL message should briefly appear before the console disappears automatically.

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_2022-1\release_2022-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_2022-1/release_2022-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_2022-1\release_2022-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_2022-1/release_2022-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_2022-1/release_2022-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.