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._
Confirm Node and YARN are installed and configured correctly, both the following commands should return the relevant version number.
> node –version > yarn –version
Clone the project from GitHub
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
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 ).
Run the new remote locally to ensure it is running as expected ( localhost:8101 )
duplicate the browser page and append /remoteEntry.js ( localhost:8101/remoteEntry.js )
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
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/
Add the path for the remote in appsresourcessrcconstants.jsx ( MON: ‘/monitoring’, )
Add a new remote file into appsresourcesarcappremotes ( dataMonitoring.tsx ) 6a. Ensure that the REMOTE is the same as 3a. ( above )
Add a route entry into appsresourcessrcappapp.tsx 7a. import DataMonitoring from ‘./remotes/dataMonitoring’; 7b. <Route path={PATH.MON} element={<DataMonitoring />} />
Add an appropriate language entry into libsi18nsrclibtranslationsEN.json 8a. “mon”: “SDP Monitoring”
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.
Create a new branch from
main
branch.Run one of
make bump-major-release
,make bump-minor-release
, ormake bump-patch-release
Update the
charts/ska-portal/values.yaml
file, the image.version should be updated.Make sure the following files have the new version: *
charts/ska-portal/Chart.yaml
*package.json
*.release
Run
make git-create-tag
Run
make git-push-tag
You will then be able to merge that branch back in, and the new release should be created.