Configuring the Learning Lab container

Copying the archive to your host machine
Loading the container image
Creating the environment file
Using the private key
Running the Learning Lab container
Managing the container service
Updating the Docker image

These procedures demonstrate how to install the Learning Lab container in a Linux-based environment. In this example deployment, the container and database services run on a single Ubuntu 18.04 virtual machine with the following configuration:

Memory: 16GB
CPU: 4x Intel Xeon
Docker version: 19.03.6
Redis version: 4.0.9
PostgreSQL version: 10.12

GitHub Enterprise Server (GHES) is running on a separate server.

NOTE: The Learning Lab container does not support SSL certificates. If you require HTTPS encryption for the Learning Lab container, consider using a reverse proxy container on the same Docker host.

Copying the archive to your host machine

Copy the previously downloaded learning-lab-{{ version }}.tar.bz2 file to your host machine. You can use scp to do this from a macOS or Linux-based system. This example demonstrates how to copy the file from your local machine to a remote Docker host named exampleServer.lab. You will need to update these parameters to match your environment:

$ scp learning-lab-0.8.0.tar.bz2 username@exampleServer.lab:/home/user/learning-lab/

learning-lab-0.8.0.tar.bz2 - The name of the container image file. The file name will vary depending on the version you're using.
username@exampleServer.lab: - The username and the hostname to use to connect to the remote host.
/home/user/learning-lab/ - The destination directory on the host computer. This path must already exist.

Loading the container image

Use the Learning Lab file to create a container image named learning-lab. This image will be used later to create and run the container.

Load the container image by running this command on the Docker host, replacing the version number so it matches the Learning Lab version you're using.

$ docker load < learning-lab-0.8.0.tar.bz2

Creating the environment file

The Learning Lab application integrates with GitHub Apps, redis, and PostgreSQL. The settings for each of these services are applied to the container using an environment file:

Note: These environment variables can be viewed with docker inspect, so be sure that you are running the container in a trusted environment.

On the Docker host, create a file named .env:
```
$ cd ~/learning-lab/
$ vi .env
```

Press i to edit the file, then paste the following text into .env:

# The ID of the GitHub App for more info. You can find this in the App's settings page as "App ID":
APP_ID=
# The webhook secret of the GitHub App. Can be any value, though we recommend using a new sha256 string:
WEBHOOK_SECRET=
# Can be any value, though we recommend using a new sha256 string:
SESSION_SECRET=
# Can be any value, though we recommend using a new sha256 string:
COOKIE_SECRET=
# The slugified name of the GitHub App. You can find this in the App's settings page as "GitHub App name":
BOT_NAME=
# The client ID of the GitHub App. You can find this in the App's settings page as "Client ID":
CLIENT_ID=
# The client secret of the GitHub App. You can find this in the App's settings page as "Client secret":
CLIENT_SECRET=
# The URL for the Learning Lab app. You can find this in the App's settings page as "Public link":    
APP_URL=
# The hostname of your GitHub Enterprise appliance. Leave out the https:// for this value. For example: GHE_HOST=github.acme.com 
GHE_HOST= 
# A full Redis connection string. For example: REDIS_URL=redis://[:password@]host[:port][/db-number][?option=value]
REDIS_URL=
# A full PostgreSQL connection string. For example: DATABASE_URL=postgres://{user}:{password}@{hostname}:{port}/{database-name}
DATABASE_URL=
# (Optional) Set this to true if your database connection should not require SSL.    
DATABASE_NO_SSL=
# (Optional) The port for Learning Lab to run on. Default is 3000.
PORT=3000

Complete the required settings in the .env file.
To save your changes and exit vi: press esc, then :, then type wq and press enter.

This example file shows what a completed .env file can look like. Do not use any of these secrets in your own deployment.

# The ID of the GitHub App for more info. You can find this in the App's settings page as "App ID":
APP_ID=1
# The webhook secret of the GitHub App. Can be any value, though we recommend using a new sha256 string:
WEBHOOK_SECRET=t2T4AGyh5nyHPBEzTKhsaASp8IYEM24obRKaSQUTGtYs9
# Can be any value, though we recommend using a new sha256 string:
SESSION_SECRET=t2T4AGyh5nyHPBEzTKhsaASp8IYEM24obRKaSQUTGtYs9
# Can be any value, though we recommend using a new sha256 string:
COOKIE_SECRET=t2T4AGyh5nyHPBEzTKhsaASp8IYEM24obRKaSQUTGtYs9
# The slugified name of the GitHub App. You can find this in the App's settings page as "GitHub App name":
BOT_NAME=learning-lab-app
# The client ID of the GitHub App. You can find this in the App's settings page as "Client ID":
CLIENT_ID=Iv1.1e9cbf2632432566
# The client secret of the GitHub App. You can find this in the App's settings page as "Client secret":
CLIENT_SECRET=6bc5289207c6ea1aesdg42a66259d1d885bb
# The URL for the Learning Lab app. You can find this in the App's settings page as "Public link":    
APP_URL=https://your-GHES-server.lab/github-apps/learning-lab-app
# The hostname of your GitHub Enterprise appliance. Leave out the https:// for this value. For example: GHE_HOST=github.acme.com 
GHE_HOST=your-GHES-server.lab
# A full Redis connection string. For example: REDIS_URL=redis://[:password@]host[:port][/db-number][?option=value]
REDIS_URL=redis://127.0.0.1:6379
# A full PostgreSQL connection string. For example: DATABASE_URL=postgres://{user}:{password}@{hostname}:{port}/{database-name}
DATABASE_URL=postgresql://learninglab:AGyhsds5nyAGbvh8IYEM2@localhost/learninglabdb
# (Optional) Set this to true if your database connection should not require SSL.    
DATABASE_NO_SSL=
# (Optional) The port for Learning Lab to run on. Default is 3000.
PORT=3000

In a later section, the container is configured to reference this file and apply the settings when it starts.

Using the private key

The Learning Lab container uses the GitHub App's private key, and expects to find it within the container's local file system as /usr/src/learning-lab/private-key.pem. To configure this, the .pem file that you previously created in the GitHub App settings is presented to the container using a bind mount.

This example demonstrates how to copy the file from your local machine to a remote Docker host named exampleServer.lab. You will need to update these parameters to match your environment:

$ scp learning-lab-app.2020-03-12.private-key.pem username@exampleServer.lab:/home/user/learning-lab/

learning-lab-app.2020-03-12.private-key.pem - The name of the private key file.
username@exampleServer.lab: - A combination of your username and the hostname of the host computer.
/home/user/learning-lab/ - The destination directory on the host computer. This path must already exist.

The private key remains stored on the Docker host, for example as /home/user/learning-lab/learning-lab-app.2020-03-12.private-key.pem. A bind mount is then used during docker run to present this file to the container as /usr/src/learning-lab/private-key.pem.

The bind mount parameters are demonstrated in the following section.

Running the Learning Lab container

To run the Learning Lab container, the docker run command uses your private key and the .env file:

$ cd ~/learning-lab/
$ docker run --name learning-lab --mount type=bind,source=/home/ubuntu/learning-lab/learning-lab-app.2020-03-12.private-key.pem,target=/usr/src/learning-lab/private-key.pem --env-file .env --network=host learning-lab

docker run -- Creates and starts a new container.
--name learning-lab - Defines the name of the container. This allows you to start and stop the container using its name.
--mount type=bind,source=/home/user/learning-lab/learning-lab-app.2020-03-12.private-key.pem,target=/usr/src/learning-lab/private-key.pem - Uses a bind mount to present the .pem file on your Docker host to the container.
--env-file .env - Tells Docker to apply the .env file configuration to the container.
--network=host - Tells Docker to use host networking. This will allow the container to connect to the Postgres service running on the host. It also lets you access the Learning Lab service using a port on the Docker host.
learning-lab - The name of the image to use.

Once the container has launched, it will perform the initial configuration tasks, and then indicate that it is available on the configured network port:

==> Starting the app in production mode...

> learning-lab@0.8.0 serve /usr/src/learning-lab
> node ./lib/index.js

15:08:59.541Z  INFO probot: Listening on http://localhost:3000

You can now access the Learning Lab using a web browser. For example: http://exampleServer.lab:3000. This path will vary depending on the DNS name of your Docker host, and the listening port you've chosen.

Managing the container service

You can stop and start the Learning Lab container, if needed. The Learning Lab will no longer be available when the container is stopped.

You can use docker tools to monitor the container’s activity:
```
$ docker logs -f learning-lab
```
To stop the container:
```
$ docker container stop learning-lab
```
To start the container:
```
docker container start learning-lab
```

Updating the Docker image

This section explains how to update the Learning Lab image, if required.

Download the new image file, and copy it to the Docker host.
Load the new image file. This example uses a file named learning-lab-0.8.0.tar.bz2
```
$ docker load < learning-lab-0.8.0.tar.bz2
```

Stop the existing container, and remove it:

$ docker stop learning-lab
$ docker rm learning-lab

Run your existing docker run command. This will rebuild the container with the new image and re-apply your configuration.

Previous: ← Creating and authorizing the GitHub App

Next: Upload your license →