• Docker Container
  • Building the Docker container
    • Steps to build the Linux Docker image:
  • Running the Docker Container
    • Steps to run the Docker container:
    • Steps to stop the Docker container:
  • Exporting the Docker Image for Distribution
    • Steps to Export the Docker Image
  • Loading the Exported Docker Image
    • Steps to Load and Run an Exported Docker Image
    • Signing in to the GIFT Dashboard:
  • Inspecting Output Logs
  • Troubleshooting:

Docker Container¶

Despite normally running on Windows, GIFT provides utilities to package an instance of GIFT within a Linux-based Docker image that can be run in a Docker environment in order to allow GIFT to run on platforms that normally would not be capable of running on it.

The instructions below describe how to use these utilities to build and run Docker containers that provide and launch prebuilt GIFT instances. These instructions assume that a Windows machine will build GIFT Docker containers using Docker for Windows and that the container will use a Linux-based platform (such as CentOS) within the container itself.

Building the Docker container¶

The resources needed to build the docker image are currently saved in the Docker folder inside your GIFT installation folder. This folder contains a number of resources used to build the docker image:

• Docker/scripts/windows/containers/linux - Contains scripts that can be used with Docker for Windows to easily build the GIFT Linux Docker image and run the GIFT Docker container using that image
• Docker/scripts/windows/container/linux/Dockerfile - The Dockerfile that defines the building process for the Linux image. This performs the bulk of the building operations.
• Docker/scripts/windows/container/linux/docker-compose.yml - A configuration file used to control how the Linux image created by the Dockerfile is run using Docker Compose.
• Docker/deploy - Contains GIFT configuration files specific to each deployment, as well as some scripts that allow GIFT to be more easily managed in a headless docker environment. Any GIFT files defined in this folder will overwrite what is copied from GIFT, allowing each deployment of the Docker container to have different configurations

Steps to build the Linux Docker image:¶

1. Copy the Linux JDK at ThirdParty/Linux/x86 to the external folder of the GIFT distribution you are using to run the Docker container. If the Linux JDK is already present in GIFT/external, then you do not need to copy it again.
2. Install GIFT using installGIFT.bat at the base of your GIFT distribution. If GIFT has already been installed, you do not need to install it again.
   • All of the default installation settings will work with the Docker container, so you can simply keep pressing Next to get through the installer.
3. Run Docker/scripts/windows/containers/linux/buildDockerImage.bat. This will rebuild GIFT's Java code if needed and will remove any existing instance of the gift-image Docker image and build a new one. The process of building the Docker image will take around 2 minutes to complete, though the total build time can be longer if the Java code needs to be recompiled.
4. Run Docker Desktop and look at your Images. You should see a new image named gift-image.
   

Running the Docker Container¶

Once the Linux Docker image has been built, it can be used to run a container (i.e. a virtual machine) that already has GIFT inside of it.

Steps to run the Docker container:¶

1. Run Docker/scripts/windows/containers/linux/composeUpContainers.bat to run the Docker container using Docker Compose. Internally, this runs the 'docker compose up' command, which runs every container defined in docker-compose.yml.
   • Once the container is running, a console window will appear to display the standard output of GIFT's processes.
   • When GIFT has successfully started all of its modules, it will display "GIFT is running!" to the console.

Steps to stop the Docker container:¶

1. Run Docker/scripts/windows/containers/linux/composeDownContainers.bat to stop the Docker container using Docker Compose. Internally, this runs the 'docker compose down' command, which stops every container defined in docker-compose.yml.

Exporting the Docker Image for Distribution¶

Docker images can be saved to .tar files in order to distribute them and load them into other Docker environments:

Steps to Export the Docker Image¶

1. Run Docker/scripts/windows/container/linux/saveDockerImage.bat. This will save a gift-image.tar file to Docker/export/linux.
2. The contents of the Docker/export/linux folder alongside the image .tar should be distributed to any groups using the that need the exported .tar, since these contents are intended to help with testing.

Loading the Exported Docker Image¶

The exported gift-image.tar file can be loaded into and run other Docker environments.

Steps to Load and Run an Exported Docker Image¶

1. Save the folder containing gift-image.tar to some location on the machine that will load the image and run GIFT
2. Navigate to the docker folder inside the release folder
3. Load gift-image.tar.gz into Docker. This will import an image named gift-image.
   

   docker load -i gift-image.tar

4. Create and run a container named gift from the gift-image image. This will run GIFT’s core software inside of Docker.
   • Once the container has been run once, steps 1-3 can be skipped until a new image for the GIFT Docker container needs to be loaded.
     

     docker compose up

5. Wait for GIFT’s processes to fully start up, which should complete within 90 seconds. When GIFT has finished starting up it will print a GIFT is running message.
6. To stop GIFT when finished with it, stop the container running it.
   

   docker compose down

Signing in to the GIFT Dashboard:¶

1. Use a browser to connect to GIFT’s Dashboard at http://localhost:8080/dashboard/#login
   • Note: If a different machine from the Docker host is connecting to GIFT’s Dashboard, that machine will need to use the host machine’s IP address instead of localhost
2. Enter your gifttutoring.org credentials into the login page to sign in

Inspecting Output Logs¶

When running in the Docker container, GIFT's output logs are stored in a gift-output volume on the host that can be accessed from outside the container. This volume also persists between executions, so domain session logs from previous executions can be maintained and accessed.

To locate GIFT’s log files, you will first need to navigate to the folder where your Docker volumes are stored on your operating system/platform

For Linux, this is at

• /var/lib/docker/volumes

For Windows, this is at

• \\wsl$\docker-desktop-data\version-packdata\community\docker\volumes
• Note: Shortcuts to these folders exist at Docker/scripts/windows/containers/linux

Within the Docker volumes folder will be a gift-output/_data folder, which is where the contents of GIFT/output within the Docker container are stored.

GIFT’s domain session logs are located within gift-output/_data/domainSessions, while its module and tool logs are located at gift-output/_data/logger/module and gift-output/_data/logger/tools, respectively.

Troubleshooting:¶

• Detecting problems with starting GIFT
  • If one or more of GIFT’s modules fail to start within the 90 second startup period, you
    will likely see the following message.
    

    GIFT failed to start.

  • If this error appears, you should inspect GIFT's module and tool output logs to find where the failure occurred. See the Inspecting Output Logs section above for instructions for how to find GIFT's log files. When looking for errors, be sure to inspect the most recent log file for each module/tool.