Introduction

• Architecture
• Installation requirements

Architecture

There are three main parts to the Learning Lab application:

• A PostgreSQL database
• A Redis server
• The core Node.js application

The Learning Lab is a Node.js app, which is packaged as a container image for GitHub Enterprise Server deployments.

The GitHub App

Learning Lab is presented as a GitHub App, allowing integration with GitHub features. The credentials for the GitHub App are shared with Learning Lab using a configuration file, which allows it to interact with the GitHub API.

Network port requirements

The Learning Lab container runs on port 3000 by default, and this can be customized using the PORT setting in the configuration file. It will also need access to the PostgreSQL server (default port is 5432) and Redis (default port is 6379). In the example deployment, the container uses host networking for simplified network connectivity.

Installation requirements

Installing GitHub Learning Lab requires:

• Licensing a copy of GitHub Enterprise Server
• Provisioning a new server
• Installing PostgreSQL
• Installing Redis
• Installing Docker
• Downloading the Learning Lab archive

GitHub Enterprise Server

Learning Lab requires a licensed copy of GitHub Enterprise Server version 2.13.0 or greater. Version 2.13.0 introduces GitHub Apps, the primary mechanism Learning Lab uses for its integration with GitHub.

Provisioning a new server

The Learning Lab application runs in a Docker container, so there are no strict requirements for the host system.

➡️ Make note of the server's URL, which you'll need later as APP_URL.

Installing PostgreSQL

The Learning Lab application requires access to a PostgreSQL database, running version 10.10 or higher. You can configure the container to use an existing PostgreSQL instance, or you can create a new installation.

This example demonstrates how to install and configure a PostgreSQL database on an Ubuntu server:

1. Install the PostgreSQL packages.

   $ sudo apt install postgresql postgresql-contrib

2. Configure PostgreSQL to listen locally. This will allow the Learning Lab container to connect to the database.

   $ sudo vi /etc/postgresql/11/main/postgresql.conf

   Locate this line: listen_addresses = 'localhost' and remove the # character preceding it.

3. Restart PostgreSQL to apply the change.

   $ sudo systemctl restart postgresql

4. Create the learninglabdb database.

   $ sudo -u postgres psql -c "create database learninglabdb;"

5. Create a PostgreSQL service account called learninglab, changing <complexPassword> to suit your requirements.

   $ sudo -u postgres psql -c "create role learninglab with login password '<complexPassword>';"

6. Grant access to PostgreSQL for learninglab.

   $ sudo -u postgres psql -c "alter role learninglab superuser;"

7. Test the connection to PostgreSQL, changing <complexPassword> to suit your requirements.

   $ sudo -u postgres psql -d "postgresql://learninglab:<complexPassword>@localhost/learninglabdb" -c "select now()"
              now
   2020-02-17 17:39:57.846033+00
   (1 row)

   This result indicates that PostgreSQL was able to connect to the database, authenticate, and perform a test query.

➡️ Make a note of the database's URL, which you'll need later as DATABASE_URL. From this example, the DATABASE_URL will be postgresql://learninglab:<complexPassword>@localhost/learninglabdb.

Installing Redis

The Learning Lab server requires access to a Redis database. This section demonstrates how to create and configure a Redis database on an Ubuntu server.

1. Install the PostgreSQL packages.

   $ sudo apt install redis-server 

2. Start the redis-server service.

   $ sudo systemctl start redis-server.service

3. Test the connection to Redis.

   $ redis-cli -h 127.0.0.1 -p 6379 ping
   PONG

➡️ Make a note of the Redis URL, which you'll need later as REDIS_URL. From this example, the REDIS_URL will be redis://127.0.0.1:6379.

Installing Docker

The Learning Lab application runs in a Docker container, so your host's operating system must support Docker. For example, to install Docker on an Ubuntu 18.04 server:

$ sudo apt install docker.io

The specific steps for installing Docker will differ depending on the host's operating system. Full instructions can be found on Docker's installation documentation.

Downloading the Learning Lab archive

Download the learning-lab-{{ version }}.tar.bz2 file from the location provided to you by GitHub.