Install Launch LRS on Ubuntu

Simple Instructions to download and install on your own infrastructure, including NGINX, SSL and database configuration.

Our simple instructions have been tried and tested to make it quick and easy to get started with Launch LRS on your own Ubuntu environment. If you don’t have an existing infrastructure we recommend using our CloudFormation template or Launch LRS AMI.


Prerequisites

These instructions assume that you already have Ubuntu 18 or later running, with a public DNS name that is reachable from the internet, and all sources allowed on TCP port 80 and port 443.

For production use we recommend you use an external database to avoid losing data if your system restarts, currently we support MySQL, PostgreSQL, MariaDB, SQL Server and H2. Once created, ensure the database is configured to accept inbound traffic from your Ubuntu server.

For testing purposes a local database is ideal and installation instructions are given below to install MySQL.

Before beginning the installation, ensure that all of your software packages are up to date. Connect to your Ubuntu server and run the following:

[user ~]$ sudo apt-get update

Java Installation

Step 1: Check if you have Java or which version

[user ~]$ java -version

If you already have Java 11 or later installed skip ahead to installing Launch LRS.

Step 2: Install the latest version

Install the default Java OpenJDK package with:

[user ~]$ sudo apt install default-jdk

Installing Launch LRS

Step 1: Download Launch LRS

Create a directory in which to save the Launch LRS application:

[user ~]$ sudo mkdir -p /opt/launch/lrs/

Download the Launch LRS application and save to the directory or download directly and rename by using the wget command below:

[user ~]$ sudo wget https://downloads.launchlearning.io/executable/launch-lrs-latest.jar -O /opt/launch/lrs/launch-lrs.jar

Change the permissions of the file:

[user ~]$ sudo chmod 500 /opt/launch/lrs/launch-lrs.jar

Step 2: Create a user to run Launch LRS

For security reasons, web services should never run as root. Create a dedicated user to run the Launch LRS application and change ownership of the jar file using the following commands:

[user ~]$ sudo useradd launch
[user ~]$ sudo chown launch:launch /opt/launch/lrs/launch-lrs.jar 

Step 3: Configure Launch LRS to run as a service

To enable Launch LRS to run as a service you will need to create a launch-lrs.service file in the /etc/systemd/system directory:

[user ~]$ sudo vi /etc/systemd/system/launch-lrs.service

Press i to insert the following configuration into the launch-lrs.service file:

[Unit]
Description=Launch LRS 
After=network.target remote-fs.target nss-lookup.target 

[Service]
User=launch
ExecStart=/opt/launch/lrs/launch-lrs.jar
SuccessExitStatus=143 

[Install]
WantedBy=multi-user.target

To save and exit press esc then enter :wq

Start the Launch LRS and enable the service:

[user ~]$ sudo systemctl enable launch-lrs.service
[user ~]$ sudo systemctl start launch-lrs.service

To test that the application is up and running correctly you can use the following command to check for some output:

curl -s http://127.0.0.1:8080 | grep "Launch LRS"

Configure NGINX as a reverse proxy

NGINX can be used as a reverse proxy for Tomcat, allowing access to your Launch LRS via HTTP on the default port 80. The Nginx reverse proxy adds additional security for your backend servers, ensuring that the identity of your backend servers remains unknown. NGINX also allows you to setup an encrypted HTTPS connection between the client and the Nginx reverse Proxy with TLS for added data protection.

Step 1: Install NGINX

Install NGINX with the following command:

[user ~]$ sudo apt install nginx

Step 2: Configure the location

Edit the location within the default site configuration file:

[user ~]$ sudo vi /etc/nginx/sites-available/default

Within the Default server configuration section add the following location settings, removing any existing settings:
proxy_pass http://localhost:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;

The location section should look like the following:

location  /  {
    proxy_pass http://localhost:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

Step 3: Enable and start NGINX

[user ~]$ sudo systemctl enable nginx.service
[user ~]$ sudo systemctl restart nginx.service

Connect to your Launch LRS

Launch LRS should now be available at your Public DNS. Enter the address in your browser to see the following page:

After confirming access to your Launch LRS you can sign in and test it immediately. Select manage and sign in with the following credentials:
username: admin 
password
: password
You will be required to change your password on first sign in.

Production use configuration

For the security and integrity of your data, before using Launch LRS in a production environment, we recommend the following:

  • Setting a domain name for easier access and also to allow the SSL setup
  • Configuring a SSL certificate to ensure a secure connection to your Launch LRS
  • Configuring Launch LRS to use a database to persist your data into

If you wish to use Launch LRS in a production environment please follow the steps below.


Setting up a domain name

To host your Launch LRS on a public website you must own or control the domain you plan to use. If you don’t already have one you need to register a domain name for your web server. You can register a domain with one of the numerous third-party domain registration and DNS hosting services, including Amazon Route 53.

You will also need a static IP address for your Launch LRS server.

Once you have a registered domain, refer to your providers own documentation to create a domain name record that points to the static IP of your Launch LRS server. Customers with an active licence can contact us for additional help.


Configuring a SSL certificate

Let’s Encrypt, a certificate authority, provides an easy way to obtain and install free TLS/SSL certificates. Let’s Encrypt requires the Certbot package which is available from the snap repository.

Prerequisite

A domain name you own or control, configured to to point to the IP address of your Launch LRS server as described in the section above.

Step 1: Install snap

Ensure that your version of snapd is up to date:

[user ~]$ sudo snap install core; sudo snap refresh core

Step 2: Install Certbot

If you have any Certbot packages installed using the apt package manager you should remove them before installing the Certbot snap:

[user ~]$ sudo apt-get remove certbot
[user ~]$ sudo snap install --classic certbot

Step 3: Update the NGINX config file with your domain

Access the NGINX configuration file:

[user ~]$ sudo vi /etc/nginx/sites-available/default

Find the following server_name line in the file:

server_name _;

Replace the _ underscore with your domain name to allow Certbot to automatically configure SSL for NGINX. For example:

server_name lrs.example.com;

Save the file and quit your editor. Then reload Nginx to load the new configuration:

[user ~]$ sudo systemctl reload nginx

Step 4: Get and install your certificate

Execute the following instruction on the command line on the machine to ensure that the certbot command can be run:

[user ~]$ sudo ln -s /snap/bin/certbot /usr/bin/certbot

Run Certbot with the –nginx plugin:

[user ~]$ sudo certbot --nginx

You will be prompted to enter an email address and agree to the terms of service. You will also be asked which domain names you would like a certificate for.

Certbot will then communicate with the Let’s Encrypt server and run a challenge to verify that you control the domain you’re requesting a certificate for.

Certbot will automatically renew your certificates before they expire. You can test automatic renewal for your certificates by running this command:

[user ~]$ sudo certbot renew --dry-run

Step 5: Verify your Launch LRS is secure

Once Certbot confirms that the verification is successful, data sent to and from your Launch LRS will be secured. You can confirm that your site is secure by viewing your Launch LRS in your browser, your browser should indicate that your site is properly secured.


Configuring Launch LRS to use a database

If a database is not specified, the Launch LRS application will use an in-memory database which will be wiped every time you restart the Launch LRS application.

For a production environment we recommend configuring the Launch LRS database on a different host to the Launch LRS application.

Step 1: Install a database

If you don’t already have a remote database we recommend using AWS RDS to install a database. Launch LRS currently supports MySQL, MariaDB, PostgreSQL, SQL Server and H2.

For testing purposes, instructions are provided below for setting up and configuring a local database using MariaDB.

Step 2: Configure your database

Create and open an application.properties file in the same directory as the Launch LRS application:

[user ~]$ sudo vi /opt/launch/lrs/application.properties

Insert the configuration below into the application.properties file, substituting the following:

dbms: mysql, sqlserver or postgresql 
endpoint: URL of your database server. For internal database installations use localhost
dbname: name of the database you intend to use for Launch LRS
user: a username with full permissions to the specified database
changeMe: password for the user

spring.datasource.url=jdbc:dbms://endpoint:3306/dbname?zeroDateTimeBehavior=convertToNull
spring.datasource.username=user
spring.datasource.password=changeMe

Save and quit.

The full list of configuration properties can be found within the Launch LRS documentation

Step 3: Restart Launch LRS

[user ~]$ sudo systemctl restart launch-lrs

If you now access Launch LRS in your browser you should notice the in-memory warning message at the bottom of the screen has gone.

If you receive 502 Bad Gateway, ensure you’re credentials, endpoint and port are correct in the configuration file.

If you changed your password during the initial setup, it will have been set back to the default when the database was specified. Select manage and sign in with the following credentials:
username: admin 
password
: password
You will be required to change your password on first sign in after specifying a database.

Local database setup for non-production use

The instructions below are to install MySQL on Ubuntu 20 or later. Other databases supported by Launch LRS can be installed instead.

Step 1: Install MySQL

To install MySQL from the APT repository, run the following command:

[user ~]$ sudo apt-get install mysql-server

After the installation, the MySQL server should start automatically.

Step 2: Secure the database server

Run the mysql_secure_installation command to set a root password and remove the insecure features from your installation:

[user ~]$ $ sudo mysql_secure_installation
  1. Type Y to setup VALIDATE PASSWORD COMPONENT and choose a level.
  2. Set a password for the root user when prompted.
  3. Type Y to remove the anonymous user accounts.
  4. Type Y to disable the remote root login.
  5. Type Y to remove the test database.
  6. Type Y to reload the privilege tables and save your changes.

Step 3: Connect to your database server

[user ~]$ sudo mysql

Step 4: Create a database

[mysql]> CREATE DATABASE lrs;

Step 5: Create a user for the database

Create a user substituting changeMe for a new secure password:

[mysql]> CREATE USER 'launch'@'localhost' IDENTIFIED BY 'changeMe';
[mysql]> GRANT ALL PRIVILEGES ON lrs.* TO 'launch'@'localhost';

Exit MySQL:

[mysql]> \q

Refer to the database configuration instructions within the Launch LRS documentation to connect the Launch LRS application to your database.