Skip to content

Commit

Permalink
Doc update2
Browse files Browse the repository at this point in the history
  • Loading branch information
@astitva1905
astitva1905 committed Sep 28, 2023
1 parent 50c30c7 commit bdcfdf0
Show file tree
Hide file tree
Showing 15 changed files with 486 additions and 253 deletions.
178 changes: 108 additions & 70 deletions client/LICENSE.md
View file

Large diffs are not rendered by default.

53 changes: 39 additions & 14 deletions client/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,13 @@
# Introduction

Client (frontend) for Digital Twin as a Service (DTaaS) software. This software shall be used for providing a React single page web application for the Digital Twin support platform.
Client (frontend) for Digital Twin as a Service (DTaaS) software.
This software shall be used for providing a React single page web
application for the Digital Twin support platform.

## Setup the Environment and Build

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

### Prerequisites

Expand All @@ -24,7 +27,9 @@ 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 command by passing different flags:
It is also possible to run different types of tests using the yarn
test command by passing different flags:

```bash
yarn test -a #run all tests
yarn test -u #run unit tests
Expand All @@ -35,30 +40,45 @@ yarn test -e #run end-to-end tests

## Authentication

The react client website uses OAuth authentication. The [authentication page](../docs/admin/client/auth.md) provides details on setting up oauth authentication for the client application.
The react client website uses OAuth authentication.
The [authentication page](../docs/admin/client/auth.md)
provides details on setting up oauth authentication for
the client 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 [build instructions](../docs/admin/client/CLIENT.md) for an example.
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 [build instructions](../docs/admin/client/CLIENT.md)
for an example.

### Multiple configurations

If you want to switch between multiple environments, you can use the `yarn configapp` command to copy a configuration file from `client/config/` to the `build` directory.
If you want to switch between multiple environments,
you can use the `yarn configapp` 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.
1. Run the config command to copy the file to the `public` directory
and the `build` directory, if a build is present.

```bash
yarn configapp <config-name>
```

> Which ever env.js file is present in the `public` directory during `yarn build`, will be used in the build.
> 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 the `yarn configapp` command to switch between them.
It is therefore reccommend to keep the configurations in the
`client/config/` directory and use the `yarn configapp` command to
switch between them.

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

Expand All @@ -84,8 +104,9 @@ window.env = {
Here the gitlab URL is `https://gitlab.foo.com/` and the client ID is `934b98f03f1b6f743832b2840bf7cccaed93c3bfe579093dd0942a433691ccc0`.

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

```js
window.env = {
Expand All @@ -107,11 +128,15 @@ window.env = {
REACT_APP_GITLAB_SCOPES: 'openid profile read_user read_repository api',
```

Do remember that the oauth application on gitlab needs to have the redirect (callback) URL is correctly registered.
Do remember that the oauth application on gitlab needs to have the redirect
(callback) URL is correctly registered.

## Caveat

The client website relies on the background services to provide most of the functionality. These services would not be running on the developer computer. The complete application setup exists either on the integration server or as an installation instance. During development, there will be
The client website relies on the background services to provide most of the
functionality. These services would not be running on the developer computer.
The complete application setup exists either on the integration server or as an
installation instance. During development, there will be

```txt
Unexpected Application Error!
Expand Down
80 changes: 57 additions & 23 deletions client/test/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,33 +1,47 @@
# End-to-End (E2E) Tests

The E2E tests require a functional gitlab oauth setup, traefik gateway and a live react client website. The E2E tests do not launch the react client website. So it is important to launch the website using `yarn start`. Keep this server running while performing the E2E tests with `yarn test -e` command.
The E2E tests require a functional gitlab oauth setup, traefik gateway and a
live react client website. The E2E tests do not launch the react client website.
So it is important to launch the website using `yarn start`. Keep this server
running while performing the E2E tests with `yarn test -e` command.

The E2E tests use playwright test runner. You also need to have the software installed. If it is not installed, you can install with the following command.
The E2E tests use playwright test runner. You also need to have the software
installed. If it is not installed, you can install with the following command.

```bash
sudo npx playwright install-deps
```

## OAuth Setup

You can follow the instructions in [authentication page](../../docs/admin/client/auth.md) to setup oauth for the react client website. Remember to add the `http://localhost:4000` as callback URL in the oauth application. The gitlab will still be running on a remote machine. It is not possible to run both the gitlab and react client website on localhost.
You can follow the instructions in
[authentication page](../../docs/admin/client/auth.md) to setup oauth for the
react client website. Remember to add the `http://localhost:4000` as callback URL
in the oauth application. The gitlab will still be running on a remote machine.
It is not possible to run both the gitlab and react client website on localhost.

## config/test.js file

Before running the E2E tests, you need to update the `config/test.js` file. If you have a live DTaaS client website running, you can copy the `build/env.js` into `config/test.js`.
Before running the E2E tests, you need to update the `config/test.js` file.
If you have a live DTaaS client website running, you can copy the `build/env.js`
into `config/test.js`.

Open `config/test.js` in a text editor and make sure the configuration matches the details of your testing environment. For instance, you need to adjust:
Open `config/test.js` in a text editor and make sure the configuration matches
the details of your testing environment. For instance, you need to adjust:

* `REACT_APP_URL`
* `REACT_APP_AUTH_AUTHORITY`
* `REACT_APP_REDIRECT_URI`
* `REACT_APP_LOGOUT_REDIRECT_URI`

to reflect your test setup. More information on about the environment settings is available in [authentication](../../docs/admin/client/auth.md) and [client deployment](../../docs/admin/client/CLIENT.md) pages.
to reflect your test setup. More information on about the environment settings is
available in [authentication](../../docs/admin/client/auth.md) and
[client deployment](../../docs/admin/client/CLIENT.md) pages.

Here's an example of relevant values for variables. This example is suitable for testing on developer computer.
Here's an example of relevant values for variables. This example is suitable for
testing on developer computer.

```
```js
REACT_APP_URL="http://localhost:4000"
REACT_APP_AUTH_AUTHORITY="http://gitlab.foo.com"
REACT_APP_REDIRECT_URI="http://localhost:4000/Library"
Expand All @@ -36,7 +50,9 @@ REACT_APP_LOGOUT_REDIRECT_URI="http://localhost:4000"

## env file

You need to create a `test/.env` file where you will store the GitLab user credentials. These credentials will be used by playwright to simulate real user interactions during the E2E tests.
You need to create a `test/.env` file where you will store the GitLab user
credentials. These credentials will be used by playwright to simulate real
user interactions during the E2E tests.

A template for `test/.env` is given here:

Expand All @@ -46,11 +62,14 @@ REACT_APP_TEST_PASSWORD=your_password
REACT_APP_URL='https://foo.com'
```

Replace _your_username_ and _your_password_ with the actual username and password of your GitLab account or the testing account that you intend to use. Finally replace _foo.com_ with the URL of your application, as you did in `env.js`.
Replace _your_username_ and _your_password_ with the actual username and password
of your GitLab account or the testing account that you intend to use. Finally
replace _foo.com_ with the URL of your application, as you did in `env.js`.

Here's an example for test setup on the developer machine and on the integration server:
Here's an example for test setup on the developer machine and on the
integration server:

```
```env
REACT_APP_TEST_USERNAME=TestUsername
REACT_APP_TEST_PASSWORD=TestPassword123
REACT_APP_URL='http://localhost:4000'
Expand All @@ -63,12 +82,16 @@ There are two possible testing setups you can create.
1. Host website on the developer computer and test from developer computer
1. Host website on the integration server and test from the integration server

If you use `localhost` in the `REACT_APP_URL` the above the two mentioned setups are essentially the same.
In order to run the tests on the integration server, you need to disable the HTTP authentication (if setup in the first place) on the Traefik server and let the website be accessible without any authenticaiton.
If you use `localhost` in the `REACT_APP_URL` the above the two mentioned setups
are essentially the same.
In order to run the tests on the integration server, you need to disable the
HTTP authentication (if setup in the first place) on the Traefik server and
let the website be accessible without any authenticaiton.

### The configuration files for the test on localhost

The `config/test.js` file is given below. The `build/env.js` also holds the same content.
The `config/test.js` file is given below. The `build/env.js` also holds the
same content.

```js
window.env = {
Expand All @@ -91,21 +114,26 @@ window.env = {
};
```

**test/.env**
## test/.env

```ini
REACT_APP_TEST_USERNAME=TestUsername
REACT_APP_TEST_PASSWORD=TestPassword123
REACT_APP_URL='http://localhost:4000'
```

Please note that the username and password are the user credentials on `gitlab.foo.com`.
Please note that the username and password are the user
credentials on `gitlab.foo.com`.

## Testing on the integration server

In this test setup, the DTaaS application is running at `https://foo.com` and the gitlab instance is running at `https://gitlab.foo.com`. The E2E test shall be run from the developer computer. The codebase commit should be the same on both the developer computer and integration server.
In this test setup, the DTaaS application is running at `https://foo.com` and
the gitlab instance is running at `https://gitlab.foo.com`. The E2E test shall
be run from the developer computer. The codebase commit should be the same on
both the developer computer and integration server.

The `config/test.js` file on the developer computer is given below. The `build/env.js` of the integration server also holds the same content.
The `config/test.js` file on the developer computer is given below. The
`build/env.js` of the integration server also holds the same content.

```js
window.env = {
Expand All @@ -128,7 +156,7 @@ window.env = {
};
```

**test/.env**
## test/.env

```ini
REACT_APP_TEST_USERNAME=TestUsername
Expand All @@ -138,13 +166,19 @@ REACT_APP_URL='https://foo.com'

Please note that the username and password are the user credentials on `gitlab.foo.com`.

**NOTE:** The tests from developer computer to the integration server only work with null basename. The test fails if a basename (say `au`) is specified. This might be due to a complex interaction of developer computer, traefik gateway and the client website hosted behind traefik.
**NOTE:** The tests from developer computer to the integration server only
work with null basename. The test fails if a basename (say `au`) is specified.
This might be due to a complex interaction of developer computer, traefik
gateway and the client website hosted behind traefik.

## Running the Tests

Once you've properly set up your .env file, you can now run the end-to-end tests.

```
```bash
yarn test -e
```
This command launches the test runner and executes all end-to-end tests. Make sure you have an active internet connection while running these tests, as they simulate real user interactions with your GitLab account.
This command launches the test runner and executes all end-to-end tests.
Make sure you have an active internet connection while running these tests,
as they simulate real user interactions with your GitLab account.

10 changes: 7 additions & 3 deletions deploy/vagrant/make_boxes/dtaas/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
# DTaaS Boxes

This is a box that has the following items:

* docker
* nodejs and yarn
* jupyter
Expand Down Expand Up @@ -28,21 +31,21 @@ vagrant ssh

# install the oh-my-zsh
sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
# install plugins: history, autosuggestions,
# install plugins: history, autosuggestions,
git clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

# inside ~/.zshrc, modify the following line
plugins=(git zsh-autosuggestions history cp tmux)

# remove the vagrant default public key - first line of
# remove the vagrant default public key - first line of
# /home/vagrant/.ssh/authorized_keys

# exit vagrant guest machine and then
# copy own private key to vagrant private key location
cp vagrant .vagrant/machines/default/virtualbox/private_key

# check
vagrant ssh #should work
vagrant ssh #should work

vagrant halt

Expand All @@ -57,5 +60,6 @@ vagrant box add --name dtaas ./dtaas.vagrant
```

## TODO

1. Write a script for automating the above steps
1. Generate the ssh keys from ssl/certificates.bash
10 changes: 7 additions & 3 deletions deploy/vagrant/single-machine/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,25 @@ This directory contains code for running DTaaS application inside one
vagrant VM. The setup requires a machine which can spare 16GB RAM,
8 vCPUs and 50GB Hard Disk space to the vagrant box.

A dummy **foo.com** URL has been used for illustration. Please change this to your unique website URL.
A dummy **foo.com** URL has been used for illustration.
Please change this to your unique website URL.

Please follow these steps to make this work in your local environment.

1. Create [**dtaas** Vagrant box](../make_boxes/dtaas/README.md).
You would have created an SSH key pair - _vagrant_ and
_vagrant.pub_ for the vagrant box.
The _vagrant_ is the private SSH key and is needed for the next steps.
Copy _vagrant_ SSH private key into the current directory (`deploy/vagrant/single-machine`).
Copy _vagrant_ SSH private key into the current
directory (`deploy/vagrant/single-machine`).
This shall be useful for logging into the vagrant machine
created for single-machine deployment.

1. Update the **Vagrantfile**. Fields to update are:
1. Hostname (`node.vm.hostname = "foo.com"`)
1. MAC address (`:mac => "xxxxxxxx"`). This change is required if you have a DHCP server assigning domain names based on MAC address. Otherwise, you can leave this field unchanged.
1. MAC address (`:mac => "xxxxxxxx"`). This change is required
if you have a DHCP server assigning domain names based on MAC
address. Otherwise, you can leave this field unchanged.
1. Other adjustments are optional.
1. Execute the following commands from terminal

Expand Down
Loading

0 comments on commit bdcfdf0

Please sign in to comment.