:warning: This project is nolonger maintained. Please migrate to the new frontend :warning:

You can find the most recent version of this guide here.

Orchestrator Client

This project contains the workflow GUI SURFnet Network Automation.

The client is a ReactJS user interface. This project was bootstrapped with Create React App.

When you need to work on the theming it's good to know that the theme is split into a separate package: located in lib/themes. It has its own README.

Installing

Depending on the OS there are ways to install yarn with a package manager.

Note: If you need more flexibility, like having the ability to test with multiple Node JS versions, we strongly recommend to use NVM. More info here. You would then install yarn also from within your Node env.

Mac

Using Brew:

brew install yarn

or using MacPorts:

sudo port install yarn npm5

and then:

yarn install

Linux

This project currently only works with Node.js 14 (if you also want to be able to run the tests in a deterministic way).

npm install yarn -g
npm install npm-run-all --save-dev -g
./build.sh

Running locally

To run locally:

./bootstrap.sh # only needed the first time if you don't use plugins
yarn start

Browse to the application homepage.

NOTE: After the upgrade to React script 5.0: you get proxy errors when you're on a routable IP. Workaround:

DANGEROUSLY_DISABLE_HOST_CHECK=true yarn start

Running against dev backend

Copy .env.local.example to .env.local

This overrides the REACT_APP_BACKEND_URL variable. You should make local changes to .env.local

Add new dependencies

yarn add 'package-name'

Check dependencies

A quick way to let yarn check the dependencies:

rm node_modules/.yarn-integrity
yarn install --check-files

Docker

Deploys of GUI Workflows are in the form of a Docker image with nginx.

Packages

We are using Prettier as a code formatter. You can run prettier like this:

    # Only check formatting
    yarn prettier
    # Apply prettier rules to project
    yarn prettier-fix

Similarly, you can run other yarn (sub)commands that can be found in the package.json

Running the tests

To run the unit-tests, do: yarn test.

If this fails, you might want to increase your inotify limit. For more information, see https://unix.stackexchange.com/questions/13751/kernel-inotify-watch-limit-reached

Tests consist out of snapshots tests for storybook items and tests for the uniforms based form inputs

WebStorm can run the tests from the IDE by default and is the easiest to start with, especially when you want to easily run separate tests.

The uniforms component are covered by React component tests with Enzyme. It contains a lot of tests and additionally uses snapshots in JSON format to check on the rendering as a whole and to assert more specific stuff like the existence of an expected div with className="x".

Tips

Updating snapshots: when snapshot failed: inspect the output and update your snapshots when you are 100% sure that the changes are indeed expected. After the initial run you can press -u to update the snapshots.

Debug rendered components: You can see what a render of a component delivered with:

console.log(wrapper.html());
console.log(wrapper.render());

Websocket problems while using the dev server Websockets can react a bit quirky to the hot reloading of the webserver. We noticed a re-connect loop that would spawn a new websocket connection every 5 seconds, after the first hot reload (e.g. when you're developing and changed some code with the dev server running). Disabling FAST_REFRESH seems to fix that issue, whilst keeping hot reload intact. So try adding this to you .env.local:

FAST_REFRESH=false

Storybook

To run the storybook, do: yarn storybook. Your browser should open to http://localhost:9009/?path=/story/welcome--to-storybook.

Actions and page views depending on who you are.

The orchestrator client can be configured to allow access to a page or to buttons in the client. The react app consumes a webassembly OPA policy and evaluates if the user has the correct claims to view certain resources. The function that gets called is the allowed() function in src/utils/policy.ts. The implementation of allowed() is done as follows:

{allowed("/orchestrator/arbitrary/resource/name") && (
    <EuiFlexItem>
        ...
    </EuiFlexItem>
)}

Basically it boils down to: when a call to allowed returns true the component will be shown.

When no policy is found, the orchestrator-client will allow access to the resource. Any real access must be enforced by the API. The client only disables features with the allowed function

Pages

These are the pages in the orchestrator client and how the resources can be viewed. In the implementation we only disable menu items, not the actual pages. If a user has a direct url they will still be able to access the resource.

If you would like to add an extra menu item you are free to name it as you wish. It is defined in the allowed function.

Actions

Actions are disabled in the same manner as menu items. The following actions are configurable:

New actions or other actions can be enabled or disabled in the same way as menu items, by adding an arbitrary resource to the project.

Development tips

IDE plugins

Visual Studio Code

• vscode-styled-components for syntax highlighting emotion/css