ifdef::env-github[] :tip-caption: :bulb: :note-caption: :information_source: :important-caption: :heavy_exclamation_mark: :caution-caption: :fire: :warning-caption: :warning: endif::[]

:toc: :toc-placement!:

= Tutorial Web App

= Index

:toc: toc::[]

= 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

IMPORTANT: After startup, the webapp automatically opens in your browser (http://localhost:3006). However, you must hard refresh the page before any content is rendered.

.Prerequisites |=== |Requirement |Version

|NodeJS |>= 10 |===

TIP: Use https://github.com/creationix/nvm/blob/master/README.md[nvm] to manage NodeJS versions locally.

[source,shell]

$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.34.0/install.sh | bash $ . ~/.nvm/nvm.sh $ nvm install 10 $ nvm use 10

== Basic setup

:numbered: === Clone the project

First you need to clone the https://github.com/integr8ly/tutorial-web-app-walkthroughs[walkthroughs repository] next to the tutorial web app:

[source,shell]

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

=== Install dependencies Then change to the webapp directory, install its dependencies and run the development server.
[source,shell]

$ cd tutorial-web-app $ rm -rf node_modules $ npm install -g yarn $ yarn install $ yarn start:dev

IMPORTANT: 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.

=== 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:

[source,shell]

$ oc login $ oc patch oauthclient tutorial-web-app -p '{"redirectURIs":["http://localhost:3006"]}'

The Integreatly operator will reset this redirect url so you should stop the operator while testing. If you are developing againtst an openshift 4 cluster you need to use the command below, be sure to update the urls to the ones on your cluster. [source,shell]

OPENSHIFT_OAUTHCLIENT_ID=integreatly-solution-explorer OPENSHIFT_OAUTH_HOST= OPENSHIFT_API= OPENSHIFT_HOST= SSO_ROUTE= OPENSHIFT_VERSION='4' INSTALLED_SERVICES='{ "3scale": { "Host": "<3scale url>", "Version": "2.6" }, "codeready": { "Host": "<codeready url", "Version": "1.2.0.GA" }, "fuse-managed": { "Host": "", "Version": "1.4" }, "user-rhsso": { "Host": "", "Version": "v7.3.2.GA" }}' yarn start:dev

=== 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.

==== Layout of your Walkthroughs directory

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

. └── walkthroughs ├── │   ├── images │   │   └── image.png │   ├── walkthrough.adoc │   └── walkthrough.json ├── 2-walkthrough-two-short-description └── 3-walkthrough-three-short-description

.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 https://asciidoctor.org/docs/what-is-asciidoc/[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:

[source,json]

{ "dependencies": { "repos": [], "serviceInstances": [] } }

===== walkthrough.json: repos

You can specify repositories that will be created for Walkthrough users in the cluster's Gitea instance. The repositories will only be created once a user starts a walkthrough. The format is:

[source,json]

{ "repoName": "", "cloneUrl": "" }

===== 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>.

[source,json]

{ "metadata": { "name": "", "labels": { "": "" } }, "spec": { "clusterServiceClassExternalName": "", "clusterServicePlanExternalName": "default" } }

==== 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:

[source,shell]

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:

[source,shell]

OPENSHIFT_HOST= OPENSHIFT_OAUTH_HOST= 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.

[TIP]

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"

====

=== 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.

[source,shell]

$ cd deployment $ ./create_webapp.sh openshift.example.com:8443 webapp-001 development

NOTE: 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:

[source,shell]

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

NOTE: 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.

==== Deployment to OpenShift (Remote Non-Development Setup)

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

[source,shell]

$ cd deployment $ ./create_webapp.sh openshift.example.com:8443 webapp-001 development

NOTE: 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:

[source,shell]

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

==== Deployment to OpenShift (Non-Development Setup)

[source,shell]

$ 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

:numbered!:

== Running the tests

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

[source,shell]

$ yarn test

== Releasing

=== Version & Tag repos

==== WebApp

[source,shell]

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

[source,shell]

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.