In order to install Learning Locker you will require a machine that has these minimum requirements:
- Git
- GCC toolchain
- Node (v14)
- Yarn
- Connectivity to a Mongo instance (v4+ as of LL v7.0.0)
- Connectivity to a Redis instance (v2.8.18+)
- Web server e.g. Nginx or Apache (optional)
- Process management system e.g. PM2 or Supervisor
A good minimum set of requirements for Git and the GCC toolchain can be installed with the following commands:
yum update
yum -y install curl git python make automake gcc gcc-c++ kernel-devel xorg-x11-server-Xvfb git-core
apt-get update && apt-get upgrade
apt-get -y install curl git python build-essential xvfb apt-transport-https
There are multiple ways to install Node and Yarn (a package management system for Node). We would recommend the excellent NVM (Node Version Manager) which can be installed by following instructions here: https://github.com/creationix/nvm
We are currently targeting builds on Node 14.*
Instructions to install Yarn can be found here: https://yarnpkg.com/en/docs/install but if being used with nvm
install via:
npm install -g yarn
PM2 is an excellent tool that can be used to manage the Node processes. It also handles log management/rotation and can automatically restart failed services. Learning Locker comes pre-packaged with some pm2 configuration scripts.
To install PM2, run the following command:
npm install -g pm2
We also recommend installing the pm2-logrotate
module, which can handle rotating and compressing your logs.
pm2 install pm2-logrotate
pm2 set pm2-logrotate:compress true
It is always preferable that you do not run your Node processes as the root
user. For this reason we would always suggest creating a new system user under which installation, builds and services can be run.
The Learning Locker application is divided into two logically separate codebases, each of which can be configured to talk to the same Mongo and Redis instances.
Each codebase requires that it is downloaded, built and configured before it can be run. This guide will aim to guide you through manually installing and running a full Learning Locker stack.
More distribution specific information can be found inside the install script source code.
Clone the Learning Locker application into a new working directory on your server.
git clone https://github.com/LearningLocker/learninglocker.git
Enter the directory and install the requirements:
npm_config_build_from_source=true yarn install --ignore-engines
You are now ready to build the code. You have different option here depending on how you wish to deploy the services. The codebase has 5 distinct services that can be built:
- UI Server -
yarn build-ui-server
- UI Client -
yarn build-ui-client
- API Server -
yarn build-api-server
- Worker -
yarn build-worker-server
- CLI -
yarn build-cli-server
If you wish to run the UI, API and Worker on the same machine and run CLI commands, you will probably want to build all the services in one simple command:
yarn build-all
Copy the .env.example
into a new .env
file and edit as required.
The database requires some indexes adding and also when upgrading you will find migrations that take care of mutating your data where required.
Once your instance is configured, run required migrations using the below command.
yarn migrate
Clone the xAPI Service into a new working directory on your server.
git clone https://github.com/LearningLocker/xapi-service.git
Enter the directory and install the requirements:
yarn install --ignore-engines
yarn build
Copy the .env.example
into a new .env
file and edit as required.
If PM2 has been installed, you will be able to run the services using the preconfigured pm2 files in each codebase:
To start all 3 services, navigate to the LL working directory and run:
pm2 start pm2/all.json
To start the xAPI service, navigate to the xAPI Service working directory and run:
pm2 start pm2/xapi.json
Note you may wish to copy and modify these pm2 config files based on your setup. Documentation can be found here.
To view the status of your services:
pm2 status
To view logs:
pm2 logs
To restart the services:
pm2 restart all
If you wish to use a different process management tool (e.g. Supervisor) or simply wish to run them manually for testing, you can start the services with these commands.
node ui/dist/server
node api/dist/server
node worker/dist/server
In your xAPI service directory
node dist/server.js
The application is accessed through 3 web interfaces, the UI, API and xAPI. Each of these is configured to run on independent ports but it is recommended you setup a server to sit infront of all traffic and route accordingly. An example nginx config can be seen here: nginx.conf.example