Welcome to ska-portal’s documentation!

This is an React application wrapper for front end applications making up the GUIs for the SKAO.

It includes tools for linting, code formatting, and testing which are easily integrated into various IDEs. It also includes modular federation, accepting remote applications that expose components for external use. ( An example of this is the SKA React Skeleton ).

### Requirements

This skeleton requires Node and YARN to install and run. To install these follow the instructions for your operating system at [https://nodejs.org/en/download/](https://nodejs.org/en/download/).

Alternatively the official Node docker image can be used. Instructions can be found on the [official Node docker image site](https://github.com/nodejs/docker-node/blob/master/README.md#how-to-use-this-image).

### Installation

_All the following notes assume you are at the command prompt for your chosen environment._

  1. Confirm Node and YARN are installed and configured correctly, both the following commands should return the relevant version number.

    > node –version > yarn –version

  2. Clone the project from GitHub

  3. Install the SKAO specific library

> npm config set @ska-telescope:registry https://artefact.skao.int/repository/npm-internal/

> yarn add @ska-telescope/ska-gui-components@latest

  1. Install all the necessary project dependencies by running

> yarn init

## working with remotes

This is done by creating a remote as a separate repo and connecting to it via a given url

To do this you need to ensure the webpack 5 has the following settings:

> experiments: { > > outputModule: true > > } > > … > > plugins: [ > new ModuleFederationPlugin({ > > … > > library: {type: ‘module’} > })

The external remote settings is defined in a external-remotes.config.js file e.g:

> module.exports = { > > “remoteName”: “http://localhost:3300/remoteEntry.js” > > }

You can change that according to the deployment location of external remotes.

Note: if you want to inspect the webpack config generated by the build target, run the command with the extra option –printout. This will result in the webpack config file being dumped as a json file to the /dist directory. If you want to only printout the moduleFederationPlugin data use –printmf.

  • Note: This project uses react 18 which is incompatible with enzyme. To resolve this, the recommendation is to use Cypress for all testing

### Testing a remote to see if it will run within the application suite

If you are using the React Skeleton as a basis of your remote, then that contains all the steps required to progress your application form a sample application, thru to a fully integrated application with it’s own menu option.

This is simplest done by temporarily changing the port of the remote to 8090 ( React ) or 8091 ( Angular ) and seeing if the remote is displayed within the developers menu options. If this is successful then permanently adding this to the application suite can be done. This is outlined by example in the following section.

### Adding a remote to the application suite

Here are the steps that were taken to add the SDP Monitoring Dashboard to the developers menu, which can be used as a guide for adding future remotes. ( Port 8101 has been used as a reference example ).

  1. Run the new remote locally to ensure it is running as expected ( localhost:8101 )

  2. duplicate the browser page and append /remoteEntry.js ( localhost:8101/remoteEntry.js )

  3. Add an entry in libsstate-storagesrcstorageremotes.json as below “sdpMonitoringDashboard”: { “port”: 8101, “module”: “./sdpMonitoringDashboard”, “link”: “/example/path/monitoring/remoteEntry.js” },

3a. sdpMonitoringDashboard - found at the top of localhost:8101/remoteEntry.js 3b. 8101 - port of the URL 3c. ./sdpMonitoringDashboard - found in localhost:8101/remoteEntry.js ( var moduleMap = { “./sdpMonitoringDashboard” ) 3d. ‘monitoring’ needs to be changed as appropriate

  1. Update chartsska-portalvalues.yaml 4a. Open in chartsska-portalvalues.yaml 4b. Locate externalRemotes: in the file 4c. Add the following; Note that name needs to be the same as 3a ( above )

  • name: sdpMonitoringDashboard link: /monitoring/dashboard/

  1. Add the path for the remote in appsresourcessrcconstants.jsx ( MON: ‘/monitoring’, )

  2. Add a new remote file into appsresourcesarcappremotes ( dataMonitoring.tsx ) 6a. Ensure that the REMOTE is the same as 3a. ( above )

  3. Add a route entry into appsresourcessrcappapp.tsx 7a. import DataMonitoring from ‘./remotes/dataMonitoring’; 7b. <Route path={PATH.MON} element={<DataMonitoring />} />

  4. Add an appropriate language entry into libsi18nsrclibtranslationsEN.json 8a. “mon”: “SDP Monitoring”

  5. Add an entry into appsresourcessrcappcomponentsMenumenuItems.tsx 9a. Appropriate icon located ( Normally taken from Material-UI ) 9b. Sample entry below

results.push({ title: ‘res.mon’, path: PATH.MON, icon: () => <LegendToggleOutlinedIcon />, });

### Note for Angular applications

Unlike React, these need to be mounted as opposed to loading. For reference, this has been done in the developers section of the application suite, however it is simple the addition of the ‘mountFirst’ parameter being set to true.

### Creating a new release

Note, this does not currently work in the Windows Shell. Use either Linux, Mac, or Windows WSL.

The following steps and commands is to create a new release for the portal.

  1. Create a new branch from main branch.

  2. Run one of make bump-major-release, make bump-minor-release, or make bump-patch-release

  3. Update the charts/ska-portal/values.yaml file, the image.version should be updated.

  4. Make sure the following files have the new version: * charts/ska-portal/Chart.yaml * package.json * .release

  5. Run make git-create-tag

  6. Run make git-push-tag

  7. You will then be able to merge that branch back in, and the new release should be created.