TXTRAX LRS
Community→
Installation

Get Started

Features

Advanced usage

APIs

Installation

Server Requirements

Apache 2.4

  • mod_rewrite

PHP

PHP 8.2, 8.3 or 8.4 is required. PHP 8.5 is partially supported (without ElasticSearch and micro-services).

The following PHP extensions are required:

  • Ctype
  • cURL
  • DOM
  • Fileinfo
  • Filter
  • Hash
  • Mbstring
  • OpenSSL
  • PCRE
  • PDO (MySQL / PgSQL)
  • Session
  • Tokenizer
  • XML

Be sure to enable these extensions both for PHP Apache and PHP CLI, which may have to different INI files!

2 more PHP extensions may be required depending of your TRAX LRS configuration:

  • MongoDB
  • Redis

Finally, be sure to allocate enough memory to PHP, the default value (128M) being too small. Once again, change this setting both for PHP Apache and PHP CLI.

memory_limit = 1024M

Database

Application: the TRAX LRS application requires MySQL or PostgreSQL. PostgreSQL should be prefered in production. MySQL may be convenient for developers.

  • MySQL 8.0 to 9.5
  • PostgreSQL 13 to 17 (18 not supported yet)

xAPI stores: TRAX LRS may store xAPI data into dedicated database(s), including:

  • MySQL 8.0 to 9.5
  • PostgreSQL 13 to 17 (18 not supported yet)
  • MongoDB 6 to 8
  • Elasticsearch 8.0 to 8.19
  • OpenSearch 2.0 to 2.19 (3.x not supported yet)

Events streaming: Redis is required if you want to deploy TRAX LRS as micro-services.

  • Redis 5 to 7

Utilities

  • Git
  • Composer 2.2.0

Installation

Hereafter is the standard installation procedure of TRAX LRS as a monolithic application. If you are interested in deploying TRAX LRS as a set of micro-services, we recommend first to get familiar with the standard installation, and then to read the micro-services documentation page.

First Steps

Assuming that you want to install TRAX LRS in a folder named trax3:

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

This composer install command will require the PHP MongoDB and Redis extensions to be installed on your platform. If you don't want to use MongoDB and/or Redis, you can ignore these requirements with the --ignore-platform-req option. For instance:

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

With Composer v2.3.0, you can event add these options in environment variables:

COMPOSER_IGNORE_PLATFORM_REQ=ext-mongodb,ext-redis

File Permissions

The folders storage and bootstrap/cache must be writable both by the web server and the console user. Assuming that the ownership has been properly set, you should be able to assign a 0775 permission to the folders and subfolders and a 644 permission to the files.

Check this post for further details: https://laracasts.com/discuss/channels/laravel/proper-folder-permissions

If you are not sure how to configure this, you can use the following commands FOR TESTING PURPOSE ONLY.

chmod -R 777 bootstrap/cache storage

Web Server

For security reasons, only the public folder should be accessible thru the web server. So create a virtual host and set the document root to trax3/public.

Configuration file

At the root of the application folder, make a copy of the .env.example file, rename it .env and set the public URL of your TRAX LRS application. For example:

APP_URL=http://trax3.test

Then, run the following command:

php artisan key:generate

Database

Hereafter is an example of basic configuration to run TRAX LRS with a single database. If you are interested by more complex strategies, such as storing xAPI data in dedicated databases, you should read the databases documentation page.

First, create an empty database. If it's a MySQL database, choose the utf8mb4_unicode_ci encoding. Then, configure the database in the .env file.

MySQL example:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=trax3
DB_USERNAME=root
DB_PASSWORD=

PostgreSQL example:

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=trax3
DB_USERNAME=postgres
DB_PASSWORD=aaaaaa

Finally, run the following command:

php artisan database:install

Admin Account

The database installation automatically creates an admin account for you, with the following credentials. So, you should be able to open TRAX LRS in a browser and to log-in with these credentials.

  • Email: admin@traxlrs.com
  • Password: aaaaaaaa

{warning} If you are on a public server, you should immediately change the admin credentials in the Access > App Users > Accounts page of the application.

xAPI endpoint

The database installation automatically creates a client for you, with a specific xAPI endpoint and related Basic HTTP credentials. So, you should be able to send your first statements from any xAPI client from now.

  • Endpoint: http://trax3.test/trax/api/gateway/clients/default/stores/default/xapi
  • Username: traxlrs
  • Password: aaaaaaaa

{warning} If you are on a public server, you should immediately change the client credentials in the Access > API Consumers >Clients page of the application.

Tasks scheduler

In order to use the new tasks management features of TRAX LRS, you need to add a single cron configuration entry to your server that runs the php artisan schedule:run command every minute:

* * * * * cd /path-to-traxlrs && php artisan schedule:run >> /dev/null 2>&1

If you just need to make some tests and don't want to configure a cron job, you can use the following command to run the scheduler every minute:

php artisan schedule:work

Testing

Hereafter are some basic testing instructions. If you are interested in more advanced testing techniques with Docker, you should read the Docker documentation page.

Unit Tests

Make a copy of the .env file and name it .env.testing. Then, change the name of the database, and create the matching database. For example:

DB_DATABASE=trax3_test

{warning} If you already cached the config files with the php artisan config:cache console command, be sure to clear the cache before running the tests with php artisan config:clear. Otherwise, your original database may be completely deleted.

Finally, you can run the unit tests with:

php artisan test

ADL Test Suite

In order to run the ADL LRS conformance test suite, you should first install the last release on your system: https://github.com/adlnet/lrs-conformance-test-suite

Then, you must add the location of the test suite to you .env file. For instance:

TESTSUITE_PATH=/path-to-ald-lrs-testsuite-folder

{warning} The test suite will run on your main database (not the testing one). So if you already have data in your LRS, you should create a specific store with a client. When starting the following command, you will be asked to select a client.

Finally, launch the test suite with:

php artisan testsuite

If you prefer to use the ADL Test Suite directly, without using the artisan command, don't forget to add the -x 1.0.3 option to specify that TRAX LRS conforms with the 1.0.3 version of the xAPI specification. For instance:

node /opt/adl-lrs-testsuite/bin/console_runner.js -e http://trax3.test/trax/api/gateway/clients/default/stores/default/xapi -a -u traxlrs -p aaaaaaaa -x 1.0.3

Production deploy

In the .env file, you should have the following settings:

APP_ENV=production
APP_DEBUG=false

You should cache the application config with:

php artisan config:cache

If you need to remove the config cache:

php artisan config:clear

Known issues

SQLSTATE[42000]: Syntax error or access violation: 1071

If you get this error during the php artisan database:install command, check your version of MySQL.

404 error on the main page

TRAX LRS has a /public/.htaccess file with some Apache directives. When these directives are ignored by Apache, this leads to a 404 error. In this case, check the httpd.conf file of Apache and try to set the following options:

<Directory "path-to-traxlrs/public">
    Require all granted
    Allowoverride All
</Directory>

testing.ERROR: Allowed memory size of 134217728 bytes exhausted

If you get this error during the unit test (php artisan test), check the memory_limit allocated to PHP CLI and try to increase it.