There are two ways to run an instance of the Education Platform, locally or made available more generally by hosting it.

The recommended way to get started is by using the docker compose configuration provided by the mdenet/educationplatform-docker repository.

• Follow the mdenet/educationplatform-docker readme to get a local instance of the platform running.

This local instance can then be customised for evaluating the platform's functionality.

To allow the platform access to private repositories and to enable learners' to save their progress the token server needs to be configured.

There are four steps to configuring the token server:

1. Create a private test repository

2. Register a GitHub App

3. Create a .env file

4. Check a private repository can be accessed

Further information on the token handler pattern used by the token server.

Create a private test GitHub repository, copy an example activity's files from educationplatform-examples, and push them to the test repository. This repository will be used to test the token server setup.

Registering a GitHub app allows users' selectively give access to their GitHub repositories. It provides a secure GitHub API endpoint that the education platform uses to access repositories that a user has given permission to use. Detailed GitHub app docs describes the options available.

For the education platform access create a new GitHub app from your GitGub account by going to Settings > Developer Settings > GitHub Apps > New GitHub App using the following settings:

• GitHub App name Use an appropriate name and description for your app.
• Homepage URL use http://127.0.0.1:8080
• Callback URL use http://127.0.0.1:8080
• Expire user authorization tokens ensure this is checked.
• Request user authorization (OAuth) during installation - ensure this is checked.
• Webhook active - ensure this is unchecked.
• Repository Permissions under Contents select read and write.

For secure communication with the git API a client secret and private key are required. On successful registration of the GitHub app the GitHub app settings are displayed. This includes the apps unique client id which will be required in the next step when creating the env file.

On this page, click the buttons:

• generate a client secret
• generate a private key

Never disclose these to anyone or store them in text form under version control.

From the Settings > Developer Settings > GitHub Apps > [app name] page's navigation menu select 'Install App' and press the install button.

On the next 'Install and Authorize [app name]' page and ensure that access is given to at least the the private repository created here. Click the Install & Authorize Button to complete and you will be redirected to the education platform starting page.

The permissions the GitHub app gives to education platform can be modified at any time by going to https://github.com/settings/installations and clicking the configure button.

Create a .env file in the /educationplatform-docker/educationplatform/tokenserver/ directory that contains the following text replacing ... with the corresponding client id and client secret from the previous step.

For the TS_ENC_KEY generate a random 256-bit secret key e.g. using openssl rand -hex 32

TS_CLIENT_ID=...
TS_CLIENT_SECRET=...
TS_ENC_KEY=...

Do not make this file available to anyone or store it under version control.

After creating the env file, restart the education platform by stopping the current docker run (press Ctrl-C in the corresponding terminal) and then restarting it, making sure the token-server image is rebuilt (docker compose up --build).

Load the activity by opening the activity via its url:
http://127.0.0.1:8080/?activities=[activity-configuration-file-url]&privaterepo=true

The url of an activity configuration can be found by browsing to the activity config file and viewing it in the repositories GitHub web interface and clicking the 'raw' button. Copy the url without the token parameter. Note you must click the button, not just copy the URL of the button.

On the education platform login page click the 'Sign in with github' button and the activity will be loaded and displayed from the private repository.

The save button can be used to save changes made to the activity's displayed project files that are restored when an activity is resumed.

Deploying the platform to provide an instance for learners to is currently experimental and not thoroughly tested. The following steps indicate how this could be achieved if a hosted instance is required.

• Locally build the mdenet/educationplatform
  • This creates the dist/bundle.js in the dist/ directory
  • Prepare tool static files (see below)
  • Host the contents of the dist/ on a webserver

Tool resource files and configuration files could be hosted as a tool/ subdirectory of the platform with a subdirectory for each tool (to save hosting the tools on separate sites).

• Deploy any used tool functions
• Update urls in tool configuration files in [tool].static/public/[tool-name]_tool.json with their deployed address.
• locally build each of the [tool-name].static/- not yet documented from the root of the repo:
  • npm install --workspaces
  • npm run build --workspaces
  • which will create the dist subdirectory inside each [tool].static/ with all of the static files to put in the tool's subdirectory of the platform static files.

Note - Tool configuration files urls that refer to tool functions need to be updated to use the deployed address. Similarly, activity configuration files urls that refer to tool configurations need to be updated.

Note - Access-Control headers of the tool functions must be configured to allow request from the platform host address to prevent CORS error reported by the browser when accessing them.

Note - If setting up the token server in a location other than the localhost, ensure that SSL is used for connections between the token server and education platform.

Note - The port the tokenserver uses to communicate with the platform can be changed by modifying the TS_PORT environment variable defined in educationplatform-docker/.env and updating the TOKEN_HANDLER_URL in educationplatform-docker/educationplatform/platform/src/playground.js that uses the format ADDRESS:PORT e.g. for a new port of 1234 this would be http://127.0.0.1:1234