Skip to content
This web application provides the front door into the Integreatly initiative. It houses the various walkthroughs, as well as a dashboard of installed products/services.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci
.github
.openshiftio
.vscode
deployment
public
scripts
src
.dockerignore
.env.development
.env.production
.env.test
.eslintrc.js
.gitignore
.prettierignore
.prettierrc
.stylelintignore
.stylelintrc
Dockerfile
LICENSE
README.adoc
git_client.js
gitea_client.js
package.json
server.js
server_middleware.js
yarn.lock

README.adoc

Tutorial Web App

Index

Overview

This web application provides the front door into the Inetgreatly initiative. It houses the various Tutorials (aka Steel Threads) as well as a dashboard of installed products/services.

Contributing with Tutorial Web App

Local Development

Table 1. Prerequisites
Requirement Version

NodeJS

>= 8

💡
Use nvm to manage NodeJS versions locally.

Basic setup

.1. Clone the project

First you need to clone the walkthroughs repository next to the tutorial web app:

$ git clone https://github.com/integr8ly/tutorial-web-app-walkthroughs.git

.2. Install dependencies

Then change to the webapp directory, install its dependencies and run the development server.

$ cd tutorial-web-app
$ yarn install
$ yarn start:dev
❗️
The webapp will automatically open (http://localhost:3006) in your browser and watch for file changes. When running locally, the available services list is mocked, and service urls set via env vars.

The webapp will also automatically load the walkthroughs from ../tutorial-web-app-walkthroughs/walkthroughs.

.3. Cluster configuration

If you are running tutorial-web-app against your cluster, then you will need to configure your cluster to allow callback to your localhost:

$ oc login <my-cluster>
$ oc edit oauthclient tutorial-web-app

This will open the file in vim for editing. The line 'http://localhost:3006' should be added to the bottom of the oauthclient tutorial-web-app and the file saved

redirectURIs:
- ...
- http://localhost:3006

.4. Setup Local Development of Walkthroughs

This section describes how to set up the Webapp for Walkthrough authors. It is recommended to put your Walkthroughs in a separate directory that you later publish on Github or another git hosting provider.

.4.1. Layout of your Walkthroughs directory

The recommended layout for a Walkthroughs directory consists of a subfolder named walkthroughs and two files:

.
└── walkthroughs
    ├── <Walkthrough ID>
    │   ├── images
    │   │   └── image.png
    │   ├── walkthrough.adoc
    │   └── walkthrough.json
    ├── 2-walkthrough-two-short-description
    └── 3-walkthrough-three-short-description
Table 2. Struture Definition

Dir

Description

Walkthrough ID

The Walkthrough ID will be used in the URL of the Tutorial Web App. It must be unique and should match ^[a-zA-Z0-9_].$

walkthrough.adoc

The main content of the Walkthrough in Asciidoc format. It is recommended to have all content in a single file. Please refer to the documentation of Asciidoctor to learn more about Asciidoc

walkthrough.json

The Walkthrough manifest file. Currently contains information about Walkthrough extra dependencies.

walkthrough.json format

The walkthrough.json file is used to describe extra dependencies of your walkthrough. At the moment this means either additional service instances or git repositories that your Walkthrough depends on. The basic file structure is:

{
  "dependencies": {
    "repos": [],
    "serviceInstances": []
  }
}
walkthrough.json: repos

You can specify repositories that will be created for Walkthrough users in the cluster’s [Gitea](https://gitea.io/en-us/) instance. The repositories will only be created once a user starts a walkthrough. The format is:

{
  "repoName": "<Repo Name in Gitea>",
  "cloneUrl": "<Optional: clone from external repo>"
}
walkthrough.json: serviceInstances

You can also specify additional service dependencies that will allow the users of your Walkthrough to use those services. Please note that the Services have to be present on the cluster already. Adding a service dependency creates a service instance that links that service to the user’s Walkthrough project.

Services can expose routes and they will be made available to the Walkthrough as an attribute in the form of route-<route name>-host. The value of this attribute will be <protocol>://<route>.

{
  "metadata": {
    "name": "<Service Name>",
    "labels": { "<Example Label Name>": "<Example Label Value>" }
  },
  "spec": {
    "clusterServiceClassExternalName": "<External Name of the ClusterServiceClass>",
    "clusterServicePlanExternalName": "default"
  }
}

.4.2. Importing your external Walkthroughs into the Webapp

Once you have the file structure in place you can import your Walkthrough into the Webapp for testing purposes. Inside the webapp root directory run:

WALKTHROUGH_LOCATIONS=<path/to/your/walkthrough/folder> yarn start:dev

This will start the Webapp in development mode and import your Walkthroughs. You can also locally test against a remote Openshift instance:

OPENSHIFT_HOST=<openshift master url> WALKTHROUGH_LOCATIONS=<path/to/your/walkthrough/folder> yarn start:dev

After you’ve made changes to your walkthrough you can restart the webapp server by typing rs into the terminal where the Webapp process is running and hitting return. Refresh your browser and your changes should be reflected.

💡

You can also specify a git reference in the form of a URL in WALKTHROUGH_LOCATIONS. By default the repository will be cloned inside the temporary directory /tmp but you can override this using TMP_DIR. Every time the webapp starts it will create a fresh clone of the walkthrough repositories.

By default the master branch of the repository gets cloned. But you can specify a branch or tag by appending #<branch or tag name> to the URL, for example:

WALKTHROUGH_LOCATIONS="https://github.com/user/repo#branch-or-tag"

If the walkthroughs are not inside the typical walkthroughs/ folder in your repository you can specify the directory via a querystring param like so:

WALKTHROUGH_LOCATIONS="https://github.com/user/repo?walkthroughsFolder=/custom/location#branch-or-tag"

You can specify multiple walkthrough folders in same repo if you want:

WALKTHROUGH_LOCATIONS="https://github.com/user/repo?walkthroughsFolder=/custom/location?walkthroughsFolder=/another/custom/location#branch-or-tag"

.5. Developing Walkthroughs on Openshift

If you’re a walkthrough developer and you are working against an the Webapp on an Openshift instance, you can point that instance to your custom Walkthroughs repository.

Open the webapp project on the cluster and within that project, open the tutorial-web-app deployment. Click Edit and switch to the Environment tab.

You should see an env var named WALKTHROUGH_LOCATIONS. Add your repository (the separator is ,), for example:

https://github.com/integr8ly/tutorial-web-app-walkthroughs.git,https://github.com/integr8ly/example-customisations.git

You can refer to specific branches, for example, #my-feature.

A git reference can be deployed to a remote OpenShift cluster.

$ cd deployment
$ ./create_webapp.sh openshift.example.com:8443 webapp-001 development
ℹ️
The cluster must be setup for cors manually. This requires adding the webapp route to the corsAllowedOrigins block in master-config.yml.

To rebuild & redeploy:

$ oc start-build -n webapp-001 tutorial-web-app
ℹ️
When changes are made to your repository you can send a POST request to the /sync-walkthroughs endpoint. This will re-clone the repositories, the new walkthroughs will then be visible in the web app.

Following some local setup options.

.5.1. Deployment to OpenShift (Remote Non-Development Setup)

A git reference can be deployed to a remote OpenShift cluster.

$ cd deployment
$ ./create_webapp.sh openshift.example.com:8443 webapp-001 development
ℹ️
The cluster must be setup for CORS manually. This requires adding the webapp route to the corsAllowedOrigins block in master-config.yml.

To rebuild & redeploy:

$ oc start-build -n webapp-001 tutorial-web-app

.5.2. Deployment to OpenShift (Non-Development Setup)

$ oc new-project tutorial-web-app
$ find . | grep openshiftio | grep application | xargs -n 1 oc apply -f
$ oc new-app --template react-demo-app -p SOURCE_REPOSITORY_URL=https://github.com/priley86/integr8ly-prototype -p SOURCE_REPOSITORY_REF=development

Running the tests

Tests are implemented using Jest, Enzyme, and Stylelint. Run them with:

$ yarn test

Releasing

Version & Tag repos

WebApp

cd /tmp/
git clone git@github.com:integr8ly/tutorial-web-app
cd tutorial-web-app/

npm version x.y.z
git push origin master
git push --tags

Walkthroughs

cd /tmp
git clone git@github.com:integr8ly/tutorial-web-app-walkthroughs
cd tutorial-web-app-walkthroughs/

npm version x.y.z
git push origin master
git push --tags

Build Images

When the changes are pushed this will trigger a new release build. If the build is successful, a new image will be pushed to https://quay.io/repository/integreatly/tutorial-web-app. The new image will be tagged as latest and the version number x.y.z.

Update the WebApp Operator

Update the version of the webapp image (DeploymentConfig) and walkthroughs tag (WALKTHROUGH_LOCATIONS param) in https://github.com/integr8ly/tutorial-web-app-operator/blob/master/deploy/template/tutorial-web-app.yml & create PR back to master. Once merged to master, these changes will be picked up in the next Integreatly (installation repo) release.

You can’t perform that action at this time.