Skip to content

Latest commit

 

History

History
255 lines (201 loc) · 9.31 KB

DEVELOPER.md

File metadata and controls

255 lines (201 loc) · 9.31 KB

Introduction

This is the developer documentation for React single page web application.

Setup the Environment and Build

The following steps are required to setup the environment and develop the application.

Prerequisites

cd client
yarn install    #install the nodejs dependencies
yarn format     #format .ts[x] and .js[x] files with prettier.
yarn syntax     #perform linting and static analysis
yarn graph      # generate dependency graphs in the code
yarn build      #build the react app into build/ directory
yarn develop    #start the development server without building. Great for live edits.

#Required: Choose one config for application (mandatory)
yarn config:local
yarn config:dev
yarn config:prod
yarn config:test

yarn start       #start the application
yarn clean       #clean the directory of temporary files

It is also possible to run different types of tests using the yarn test commands:

#Tests require installation of devDependencies
yarn test:unit  #run unit tests
yarn test:int   #run integration tests
yarn test:e2e   #run end-to-end tests
yarn test:all   #run all tests

Authorization

The react client website uses OAuth authorization. The authorization page provides details on setting up oauth authorization for the client application.

It is sufficient to have user-owned oauth application. You can create this application in your gitlab account. Do remember that the oauth application on gitlab needs to have the redirect (callback) URL is correctly registered.

A test OAuth application has been registered on https://gitlab.com. The application is available with client ID: 1be55736756190b3ace4c2c4fb19bde386d1dcc748d20b47ea8cfb5935b8446c. It can be used for development purposes. Please note that you need an account on https://gitlab.com in order to use this OAuth application.

Custom configuration

It is required to have a env.js in the root directory of build during runtime. This file is used to configure the endpoints of the application. See the config page for an explanation of client configuration.

Multiple configurations

If you want to switch between multiple environments, you can use the yarn config sub-command to copy a configuration file from client/config/ to the build directory.

  1. Save the file as client/config/<config-name>.js.
  2. Run the config command to copy the file to the public directory and the build directory, if a build is present.
yarn config:<config-name>

Which ever env.js file is present in the public directory during yarn build, will be used in the build.

It is therefore reccommend to keep the configurations in the client/config/ directory and use one of the yarn config sub-commands to switch between them.

The purpose of different configuration files are given in the table below.

Configuration File Name Usage Scenario
dev.js Check functionality of the client application without using any other parts of the DTaaS software
gitlab.js Used for testing the gitlab code written in src/utils/gitlab.ts. These credentials are not used by the client application
local.js Used by the docker/compose.dev.yml to setup a check the complete DTaaS application on the developer computer
prod.js Used for running the client application on a production server. This file is kept here for reference. The deploy/config/client/env.js is used during installations.
test.js Used by all the tests

Example configuration for developers

The first step is to collect the URL of gitlab acting as oauth provider. Also collect the client application id. With that information, a configuration file can be made.

A suitable configuration file for developers is in config/test.js.:

if (typeof window !== 'undefined') {
  window.env = {
    REACT_APP_ENVIRONMENT: 'test',
    REACT_APP_URL: 'http://localhost:4000/',
    REACT_APP_URL_BASENAME: '',
    REACT_APP_URL_DTLINK: '/lab',
    REACT_APP_URL_LIBLINK: '',
    REACT_APP_WORKBENCHLINK_VNCDESKTOP: '/tools/vnc/?password=vncpassword',
    REACT_APP_WORKBENCHLINK_VSCODE: '/tools/vscode/',
    REACT_APP_WORKBENCHLINK_JUPYTERLAB: '/lab',
    REACT_APP_WORKBENCHLINK_JUPYTERNOTEBOOK: '',
    REACT_APP_WORKBENCHLINK_DT_PREVIEW: '/preview/digitaltwins',

    REACT_APP_CLIENT_ID: '1be55736756190b3ace4c2c4fb19bde386d1dcc748d20b47ea8cfb5935b8446c',
    REACT_APP_AUTH_AUTHORITY: 'https://gitlab.com/',
    REACT_APP_REDIRECT_URI: 'http://localhost:4000/Library',
    REACT_APP_LOGOUT_REDIRECT_URI: 'http://localhost:4000/',
    REACT_APP_GITLAB_SCOPES: 'openid profile read_user read_repository api',
  };
};

Here the gitlab URL is https://gitlab.com/ and the client ID is 1be55736756190b3ace4c2c4fb19bde386d1dcc748d20b47ea8cfb5935b8446c.

If a basename is needed for the client application, then the configuration file needs to be updated with the basename. For example, with a basename of au, the build/env.js file is given below.

if (typeof window !== 'undefined') {
  window.env = {
    REACT_APP_ENVIRONMENT: 'test',
    REACT_APP_URL: 'http://localhost:4000/',
    REACT_APP_URL_BASENAME: 'au',
    REACT_APP_URL_DTLINK: '/lab',
    REACT_APP_URL_LIBLINK: '',
    REACT_APP_WORKBENCHLINK_VNCDESKTOP: '/tools/vnc/?password=vncpassword',
    REACT_APP_WORKBENCHLINK_VSCODE: '/tools/vscode/',
    REACT_APP_WORKBENCHLINK_JUPYTERLAB: '/lab',
    REACT_APP_WORKBENCHLINK_JUPYTERNOTEBOOK: '',
    REACT_APP_WORKBENCHLINK_DT_PREVIEW: '/preview/digitaltwins',

    REACT_APP_CLIENT_ID: '1be55736756190b3ace4c2c4fb19bde386d1dcc748d20b47ea8cfb5935b8446c',
    REACT_APP_AUTH_AUTHORITY: 'https://gitlab.com/',
    REACT_APP_REDIRECT_URI: 'http://localhost:4000/au/Library',
    REACT_APP_LOGOUT_REDIRECT_URI: 'http://localhost:4000/au',
    REACT_APP_GITLAB_SCOPES: 'openid profile read_user read_repository api',
  };
};

Missing Workspace

The development environment does not have user workspaces and traefik gateway running in the background. As a consequence, the iframe links pointing to user workspace will not work correctly. Instead, you will see the following error.

Unexpected Application Error!
404 Not Found

This error can be seen on the Library and Digital Twins pages. This error is expected.

Quality Check

A docker compose-based development environment is available to test the DTaaS application on your local machine.

Please note that it is currently not easy to test for different port and basename options in the docker-based development environment.

Publish Docker Images

Each new release of client web application is published as a docker container image. Please see publishing page for more information publishing docker images.

Gitlab Integration

The client codebase has been using Gitlab for OAuth2 only. There is an ongoing effort to integrate Gitlab CI/CD capabilities to automate the execution of Digital Twins. This code is in alpha stage and is available in src/util/gitlab*.ts.

The gitlab code requires gitlab personal access token for a gitlab account. Remember to select all scopes for access token. Specifically, select the following scopes.

api, read_api, read_user, create_runner, k8s_proxy, read_repository, write_repository, ai_features

The token information needs to be updated in config/gitlab.json.

In addition to the personal access token, you also need to create a pipeline trigger token. This token is required to trigger pipelines by using the API. You can create this token in your GitLab project's CI/CD settings under the Pipeline trigger tokens section.

Once the token configuration is in place, the gitlab code can be developed and tested using the following yarn commands.

yarn gitlab:compile
yarn gitlab:run

These two commands run src/util/gitlabDriver.ts code to check the correct functioning of the gitlab code placed in src/util directory.

A piece of code in src/util/gitlabDriver.ts checks for correct execution of a DT in gitlab runner. The token owner must have a hosted runner in order for this piece of code to be executed successfully. Otherwise, the following error appears.

....
Execution Result: false
Execution Status: error
Execution Logs: [
  {
    status: 'error',
    error: Error: GitbeakerRequestError: Not Found
        at DigitalTwin.<anonymous> (file:///C:/Users/au598657/git/DTaaS/client/dist/gitlabDigitalTwin.js:32:73)
        at Generator.throw (<anonymous>)
        at rejected (file:///C:/Users/au598657/git/DTaaS/client/dist/gitlabDigitalTwin.js:5:65)
        at process.processTicksAndRejections (node:internal/process/task_queues:95:5),
    DTName: 'hello-world',
    runnerTag: 'dtaas'
  }
]

Digital Twins page preview

In the Workbench section, there is a link to preview the Digital Twins page. The GitLab account used as OAuth provider must have a DTaaS group, a project under your username, and a digital_twins folder which contains the Digital Twins. From this interface, you can start or stop execution of Digital Twins, and once the execution is complete, view the complete logs.