application-ui

The UI service for Application Lifecycle

---

Table of Contents generated with DocToc

• Work in Progress
• Community, discussion, contribution, and support
• License
• Getting Started
• Design
• Setting up Your Dev Environment
  • Prerequiste Tools
  • Building for Development
  • Running locally with an OKD cluster OCM environment
  • Building a local image
• Testing
• NPM Commands
• Links

---

Work in Progress

We are in the process of enabling this repo for community contribution. See wiki here.

Community, discussion, contribution, and support

Check the CONTRIBUTING Doc for how to contribute to the repo.

License

This project is licensed under the Apache License 2.0. A copy of the license can be found in LICENSE.

Included fonts are licensed under the SIL Open Font License 1.1, and copies of this license can be found along side the corresponding fonts in the ./fonts directory.

Getting Started

The Application console runs only on the hub cluster. It defines the user interface used to create and manage application resources deployed on your managed clusters through the use of Application lifecycle subscription operators. This console component, application-ui, depends on the console-api and search-api components to work with the custom Kubernetes resources of the Application lifecycle model. The application-ui and console-api components are packaged as a Helm chart defined in the application-chart repository. The search-api component is packaged as a Helm chart defined in the search-chart repository. This is a guide on how to build and run open-cluster-management application-ui.

Design

This UI Platform is developed as an isomorphic react application. The following major components are used to build this service.

• NodeJS
• Express
• React
• Handlebars
• Redux
• Webpack
• Babel
• Apollo/GraphQL
• Red Hat PatternFly
• Jest

Setting up Your Dev Environment

Prerequiste Tools

• Git
• Node v12+
• Docker (Optional)

Building for Development

git clone https://github.com/open-cluster-management/application-ui.git
cd application-ui
npm install
npm run build

Running locally with an OKD cluster OCM environment

By default the server runs in development mode using insecure HTTP connections. To use HTTPS, you must either:

• set the environment variables serverKey and serverCert with the full path of the key and certificate files
• provide a key and certificate in the ./sslcert/server.key and ./sslcert/server.crt files
• follow the README steps in ./sslcert to generate new certificate files

To run in production mode, set NODE_ENV to production and provide a key and certificate in ./certs/applicationui.key and ./certs/applicationui.crt.

To run your local application-ui code against an existing OCM installation:

1. Make sure you are logged in using oc then source the setup-env.sh script.

   . ./setup-env.sh
   

   This will automatically set up the redirect URL and export all required environment variables, allowing you to skip the next 2 steps. The variables are also printed out as JSON in case you prefer to set them up in a VS Code launch configuration as described below.

   The script works in zsh or bash and requires oc and jq.

   By default, the script sets the hcmUiApiURL variable to use the running OCM. To use local console-api, unset this variable.

   unset hcmUiApiUrl
   

2. Add your application-ui redirect link to your hub's oauthclient multicloudingress if it does not already exist there

   oc edit oauthclient multicloudingress -n open-cluster-management
   
   (Add "- http://localhost:3001/multicloud/applications/auth/callback" to "redirectURIs:" list)
   

3. The following environment variables need to be set.

   export OAUTH2_CLIENT_ID=
   export OAUTH2_CLIENT_SECRET=
   export OAUTH2_REDIRECT_URL=http://localhost:3001/multicloud/applications/auth/callback
   
   \# for local testing, from okd login token
   export API_SERVER_URL=
   export SERVICEACCT_TOKEN=
   export NODE_ENV=development
   
   \# search and console-api
   export searchApiUrl=`/multicloud/applications/search/graphql`
   export hcmUiApiUrl=`/multicloud/applications/graphql`
   

   For VS Code users, these variables can be set in your local VS Code enviroment using the launch.json in the .vscode directory. To create a launch.json file, open your project folder in VS Code (File > Open Folder) and then select the Configure gear icon on the Run view top bar. If you go back to the File Explorer view (Ctrl+Shift+E), you'll see that VS Code has created a .vscode folder and added the launch.json file to your workspace.

   Use a map, env:{} , in launch.json to contain your environment variables.

   {
       "version": "0.2.0",
       "configurations": [
       {
           "type": "node",
           "request": "launch",
           "name": "",
           "program": "${workspaceFolder}/app.js",
           "env": {
           "hcmUiApiUrl": "http://localhost:4000/hcmuiapi",
           "searchApiUrl": "https://localhost:4010/searchapi",
           "NODE_ENV": "",
           "headerUrl": "",
           "OAUTH2_REDIRECT_URL": "http://localhost:3001/multicloud/applications/auth/callback",
           "OAUTH2_CLIENT_ID": "",
           "OAUTH2_CLIENT_SECRET": "",
           "SERVICEACCT_TOKEN": "",
           "API_SERVER_URL": "",
           }
       }
       ]
   }
   

4. If you are working on changes to console-api, run console-api locally following the instructions from https://github.com/open-cluster-management/console-api

5. Start the server for production

   npm run start:production
   

6. Start the server for development, make sure to execute both of the following npm commands

   npm run build:watch
   npm run start
   

7. Open a browser to https://localhost:3001/multicloud/applications or http://localhost:3001/multicloud/applications, depending on whether you are using a certificate for HTTPS or not. If prompted for password, use your OKD credentials.

Building a local image

git clone https://github.com/open-cluster-management/application-ui.git
cd application-ui
export export USE_VENDORIZED_BUILD_HARNESS=false
export COMPONENT_DOCKER_REPO=<docker_repo>
export COMPONENT_NAME=application-ui
export IMAGE_TAG=<image_tag>
make install
make build-prod
make lint
make prune
make build-image

Testing

The following will run all unit tests.

npm run test:unit

To run a particular test.

npm run test:unit -- <test_file>

# for example
npm run test:unit -- ApplicationTopology.test.js

NPM Commands

The full list of npm scripts are described below.

Command	Description
npm start	Starts the application with NODE_ENV='development'
npm run test:unit	Runs jest tests
npm run test:update-snapshot	Updates snapshots for jest tests. This command should only be used if you have made changes to a component that requires an updated snapshot artifact for a test case.
npm run start:production	Starts the application with NODE_ENV='production'
npm run clean	Deletes the generated files from public folder.
npm run build	Does a FULL development build. (caching disabled and dev source maps)
npm run build:production	Does a FULL production build.
npm run build:watch	Does a build of application code (w/o the DLL generation) and remains running in the background watching for changes.
npm run build:dll	Only re-builds the the vendor library component.
npm run lint	Runs linting on the code base.
npm run lint:fix	Attempts to fix any linting errors automatically.
npm run shrinkwrap:clean	Regenerates a clean npm-shrinkwrap.json - THIS COMMAND SHOULD ONLY BE USED IN EXTREME CIRCUMSTANCES.

Note: The build process leverages the Dll and DllReference plugins to extract out vendor plugins for faster build times and improved browser caching. A separate bundle is created for 3rd-party client-side libraries. The generated bundle is sourced (public/dll.vendor.js) along with its manifest (vendor-manifest.json). If new client dependencies are added or existing versions of dependencies are updated this module needs be regenerated and recommitted back into source control via npm run build:dll.

Links

These are a few useful links that will help provide technical reference and best practices when developing for the platform.

• temptifly
• ui-components
• PatternFly
• Webpack
• React Docs
• Thinking in React
• Redux
• Structuring Redux State
• React Best Practices
• Smart and Dumb Components
• Redux Best Practices