Importing the Learning Lab archive

Copying the archive to your host machine

Copy the previously downloaded learning-lab-{{ version }}.tar.bz2 file to your host machine. You can do this via scp to copy it over ssh, or whatever method works best.

Loading and running the Docker image

Load the Learning Lab Docker image with Docker's load command:

docker load < learning-lab-image.tar.bz2

Then, run the image like any other Docker image.

Setting environment variables

There are a few environment variables that need to be set for Learning Lab to run properly. Let's take a moment to gather them all.

Name Description Required
APP_ID The ID of the GitHub App for more info.
WEBHOOK_SECRET The webhook secret of the GitHub App
SESSION_SECRET Can be anything, though we recommend creating a new sha256 string.
COOKIE_SECRET Can be anything, though we recommend creating a new sha256 string.
PRIVATE_KEY The private key of the GitHub App. See Importing the private key for more details.
BOT_NAME The slugified name of the GitHub App
CLIENT_ID The OAuth client ID of the GitHub App
CLIENT_SECRET The OAuth client secret of the GitHub App
APP_URL The URL for the deployment of Learning Lab. This is used to create hyperlinks between Learning Lab and GitHub.
GHE_HOST The host of your GitHub Enterprise appliance. Ex:
REDIS_URL A full Redis connection string. Ex: REDIS_URL=redis://[:password@]host[:port][/db-number][?option=value]
DATABASE_URL A full PostgreSQL connection string. Ex: DATABASE_URL=postgres://{user}:{password}@{hostname}:{port}/{database-name}
DATABASE_NO_SSL Set this to true if your database connection should not require SSL.
PORT The port for Learning Lab to run on. Default is 3000.

Now, create a .env file on your host machine. We will be using this when running the Docker image. In this file, list every environment variable by its key/value pair, for example:


Please note that if any required environment variables have not been set, Learning Lab will be unable to start.

Updating the Docker image

To update the image, you'll need to follow the above steps to retrieve the newer image. Once that's available and on your system and you've run docker load, the next step is to stop and remove the old container:

docker stop learning-lab && docker rm learning-lab

Then follow the same process as before:

docker create...

Importing the private key

The private key .pem file that you create in the GitHub App settings can be included in two ways: either via the PRIVATE_KEY environment variable, or by including the file itself in the container.

When using the PRIVATE_KEY environment variable, note that newlines must be replaced by \n characters including at the end of the value:


If you prefer to include the file itself, you can also use Docker volumes or bind mounts:

docker run -v $(pwd)/learning-lab-private-key.pem:/usr/src/learning-lab/private-key.pem

Note that the file must be named exactly private-key.pem within the container, and should be placed in the /usr/src/learning-lab/ directory within the container:


Previous: ← Register the GitHub App
Next: Run the Docker container →