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.
|
❗
|
After startup, the webapp automatically opens in your browser (http://localhost:3006). However, you must hard refresh the page before any content is rendered. |
| Requirement | Version |
|---|---|
NodeJS |
>= 10 |
|
💡
|
Use nvm to manage NodeJS versions locally. |
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.34.0/install.sh | bash
$ . ~/.nvm/nvm.sh
$ nvm install 10
$ nvm use 10First you need to clone the walkthroughs repository next to the tutorial web app:
$ git clone https://github.com/integr8ly/tutorial-web-app-walkthroughs.git
$ git clone https://github.com/integr8ly/tutorial-web-app.gitThen change to the webapp directory, install its dependencies and run the development server.
$ cd tutorial-web-app
$ rm -rf node_modules
$ npm install -g yarn
$ 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.
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 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.
OPENSHIFT_OAUTHCLIENT_ID=integreatly-solution-explorer OPENSHIFT_OAUTH_HOST=<openshift oauth url> OPENSHIFT_API=<openshift api url> OPENSHIFT_HOST=<openshift console url> SSO_ROUTE=<rhsso url> OPENSHIFT_VERSION='4' INSTALLED_SERVICES='{ "3scale": { "Host": "<3scale url>", "Version": "2.6" }, "codeready": { "Host": "<codeready url", "Version": "1.2.0.GA" }, "fuse-managed": { "Host": "<fuse url>", "Version": "1.4" }, "user-rhsso": { "Host": "<user sso url>", "Version": "v7.3.2.GA" }}' yarn start:devThis 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.
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
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 |
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. |
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": []
}
}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>"
}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"
}
}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:devThis 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> OPENSHIFT_OAUTH_HOST=<openshift oauth url> WALKTHROUGH_LOCATIONS=<path/to/your/walkthrough/folder> yarn start:devAfter 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 By default the master branch of the repository gets cloned. But you can specify a branch or tag by appending WALKTHROUGH_LOCATIONS="https://github.com/user/repo#branch-or-tag" If the walkthroughs are not inside the typical 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" |
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.
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$ 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=developmentTests are implemented using Jest, Enzyme, and Stylelint. Run them with:
$ yarn testcd /tmp/
git clone [email protected]:integr8ly/tutorial-web-app
cd tutorial-web-app/
npm version x.y.z
git push origin master
git push --tagscd /tmp
git clone [email protected]:integr8ly/tutorial-web-app-walkthroughs
cd tutorial-web-app-walkthroughs/
npm version x.y.z
git push origin master
git push --tagsWhen 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 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.