Docker

Introduction

At this time, we don't provide any official Docker image for TRAX LRS. However, TRAX LRS comes with some Docker facilities which are used during the development and testing of the application, and which could help you understand how the platform can be configured and deployed with Docker. We encourage you to play with this tool, explore the generated configuration files, and then implement your own use case with all the things your learned.

Laravel Sail

If you are familiar with the Laravel ecosystem, you propably already heard about Laravel Sail, which is a "command-line interface for interacting with Laravel's default Docker development environment". We use Sail with some customizations and complementary tools to develop and test TRAX LRS.

Before starting using Sail, be sure to have the folowwing tools installed on your server:

  • Git
  • Composer
  • PHP CLI (8.2 or 8.3)
  • Docker

Furthermore, you should create an alias to the Sail binary file which is always located at ./vendor/bin/sail in Laravel projects. In order to do that, you can add the following line at the end of your ~/.bashrc file:

alias sail='[ -f sail ] && sh sail || sh vendor/bin/sail'

TRAX LRS

The next step is to clone the TRAX LRS repository on your server and install the PHP dependencies:

git clone https://github.com/trax-project/trax3-extended-lrs trax3
cd trax3
composer install

If Composer complains about missing Redis and MongoDB PHP extensions, you can use the --ignore-platform-req option with the composer install command:

composer install --ignore-platform-req=ext-mongodb --ignore-platform-req=ext-redis

Configuration

Now that we have our TRAX LRS application, we need to configure it and we have a wonderful command for that:

php artisan docker:compose

This command will ask you a series of questions, including:

  • The version of PHP you want to use
  • The services you would like to run in separate containers
  • The database driver you would like to use for the app
  • The database driver you would like to use for xAPI data
  • The version of Redis you would like to use
  • The HTTP server you would like to use
  • If you want to install an Nginx reverse proxy to serve the application over HTTPS
  • If you want to apply the production configuration (debug mode disabled, cache enabled)

At the end of the process, we get 3 files configured properly at the root of the application folder:

  • docker-compose.yml
  • .env
  • .env.testing

Using Sail

If you ran the php artisan docker:compose command for the first time, or if you selected a different version of PHP, you must build a Docker image with:

sail build --no-cache

Then, you can start the Docker containers with: 

sail up -d

Then, if you start TRAX LRS for the first time, or if you selected a different database, you must migrate the database with:

sail artisan database:install

Now, you can open TRAX LRS in a browser at http://localhost or https://localhost.

To stop the Docker containers:

sail down

Unit tests

Beyond manual testing in the browser at http://localhost or https://localhost, you can run some PHPUnit tests with:

sail test

You can focus on a given service with the --testsuite option. For instance:

sail test --testsuite statements

You can also focus on a given test file. For instance:

sail test trax/back/core/statements/tests/StandardApiGetTest.php

Or you can focus on a given test function with the --filter option. For instance:

sail test trax/back/core/statements/tests/StandardApiGetTest.php --filter testGetOne

ADL LRS conformance test suite

The ADL LRS conformance test suite is already deployed in the Docker containers.

In order to run the test suite, simply use:

sail artisan testsuite

You can focus on a specific section of the specification with the --section option. For instance:

sail artisan testsuite --section"Communication 1.3"

Limitations

The php artisan docker:compose console command is intended to be used for testing the most common scenarios and does not pretend to implement all the possible use cases.

Here are a few restrictions due to the way listeners are deployed with the configuration tool:

  • As soon as you decide to run a service remotely, you should also run the logging service remotely.
  • As soon as you decide to run an xAPI service remotely, you should also run the vocab service remotely.
  • If you decide to run the statements service remotely, you should also run the activities and agents services remotely.

Note that the configuration tool does not allow to group multiple services in a remote container. However, this is something you can easily do if you play a bit with the configuration files.

Finally, be aware that if you deploy the statements and activities services in separated containers, the ADL LRS conformance test suite will fail. This is because the test suite assumes that activity definitions are updated synchronously when statements are recorded into the LRS.