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:
19.03.6
4.0.9
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.
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.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
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.
.env
:$ cd ~/learning-lab/
$ vi .env
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
.env
file. 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.
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.
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.
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
This section explains how to update the Learning Lab image, if required.
learning-lab-0.8.0.tar.bz2
$ docker load < learning-lab-0.8.0.tar.bz2
$ docker stop learning-lab
$ docker rm learning-lab
docker run
command. This will rebuild the container with the new image and re-apply your configuration.