Developer Guide
Note
This document complements the guidelines set out in the SKA telescope developer portal
Tooling Pre-requisites
This project requires Node and YARN to install and run. To install please follow the instructions for your operating system at nodejs downloads.
Alternatively, the official Node docker image can be used. Instructions can be found on the official Node docker image site.
After installing Node, Yarn can be installed following this page. This project requires Yarn v1.x; v2 and above is not supported. The recommended version is 1.22.22, which can be set via corepack:
> yarn set version 1.22.22
Or you can directly install YARN via npm.
If you have any questions, the SKA developer portal also has a general guide on how to install JS related packages: Javascript (JS) Guidelines .
Development setup
To run the application directly on your host machine
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 repository and its submodules:
git clone --recurse-submodules https://gitlab.com/ska-telescope/ska-dataproduct-dashboard.git
Scripts for running, testing, and building the application are defined in the scripts section of the package.json file. These are run using YARN.
To run the application locally on your host machine, install all the latest SKAO React components library and other necessary project dependencies with the YARN package manager:
> yarn skao:update
> yarn
If you are setting this up the first time, you may need to run ‘yarn install’ to install any missing dependencies.
Using a .env File (For hosting the application on a developer machine)
Note
This file is excluded from version control via .gitignore to prevent exposing sensitive information.
Create a file named .env at the root of the project. The canonical list of supported variables is defined in
env_scripts/env_config. The table below describes each variable:
Variable |
Type |
Default |
Description |
|---|---|---|---|
|
string |
|
Base URL of the Data Product API. |
|
number |
|
Polling interval in milliseconds for refreshing data from the API. |
|
string |
|
Default number of rows per page in the data grid. |
|
string |
(required only for authentication) |
Microsoft Entra application registration client ID. |
|
string |
(required only for authentication) |
Microsoft Entra tenant ID. |
|
string |
(required only for authentication) |
Redirect URI registered in Microsoft Entra for post-authentication redirect. |
|
string |
(Google Form URL) |
URL of the user feedback form linked from the dashboard header. |
|
boolean |
|
Load mock local data instead of calling the API. For development only — never enable in production. |
Running scripts
You should now be able to run the scripts defined in the package.json within the project directory.
Running the application in development mode
Runs the application in development mode with live reloading. You can access your application at http://localhost:8100. The app will recompile and restart if you make any edits to the source files.
> yarn start
Running the application tests using Cypress
The package Cypress has been set up to provide component and end to end testing. For information on the use of Cypress, see Cypress component-testing.
Code coverage is implemented with Istanbul and NYC for instrumenting the code, and cobertura reporter as it is used for reporting for the Gitlab CI of coverage statistics.
Cypress can be opened in a browser by running the following (this will open an interactive session):
> yarn cypress:open
Or alternatively unit and end to end tests can be run headless by:
> yarn test:cypress:component:ci
> yarn test:cypress:e2e:ci
Code coverage can be viewed by opening the build/coverage/index.html in a browser after running:
> yarn test:coverage:report
Running the production code
The build script builds the app for production to the dist folder. The build is minified and any JSX is transpiled to JavaScript. Your app is ready to be deployed!
> yarn build
Running the application inside a docker container on your host machine
When running the application within a container, the production image of the application is first built in the docker file and a Nginx image is then used to run the application. The following docker commands can be used to build and run it locally:
docker build -t ska-dataproduct-dashboard .
docker run -p 80:80 ska-dataproduct-dashboard
The project will then be accessible at the URL http://localhost/
Steps to run the system locally in Minikube
The following steps will assume that you have the repo checked out, or have the chart locally.
Start Minikube if it is not already running:
minikube start
minikube status
If needed, build the Docker images, tag and load them to Minikube.
docker build -t ska-dataproduct-dashboard .
docker images
docker tag [Image ID] ska-dataproduct-dashboard:[Tag]
minikube image load ska-dataproduct-dashboard:[Tag]
minikube image ls
Change to the chart directory in the repository:
cd charts/ska-dataproduct-dashboard/. Make the needed changes to image versions and enable the deployments as required in the values files. Then update the Helm dependencies.
helm dependency update .
helm dependency build
Create a new namespace (optional):
kubectl create namespace [namespace]Install the helm chart with the following values:
helm install [deploy-name] charts/ska-dataproduct-dashboard -n [namespace] --values values_local_deployment.yaml
On a system with limited resources / slow connection, run with the following additional flags:
helm install [deploy-name] charts/ska-dataproduct-dashboard -n [namespace] --values values_local_deployment.yaml --set diagnosticMode.enabled=true --timeout=60m
Once the above is complete you will have the following running:
The Data Product API
The Data Product Dashboard
To be able to access the API and the dashboard run the following:
kubectl -n [namespace] port-forward service/ska-dataproduct-api 8000:8000
kubectl -n [namespace] port-forward service/ska-dataproduct-dashboard 80:80
You should now be able to access the API and the Dashboard on the following URL’s:
To get data onto the PV:
kubectl get pod -n [namespace]
kubectl cp [host path]/ska-dataproduct-api/tests/test_files/product [ska-dataproduct-api pod]:/usr/data -n [namespace]
Column Header Labels, Descriptions, and Default Visibility
This section documents how column headers with tooltips are rendered in the DataGrid, how default column visibility is controlled and persisted, and how to extend either.
Column header tooltip flow
The frontend resolves column labels and tooltip descriptions from a single i18next
namespace (humanreadable) loaded from GET /en/humanreadable:
GET /en/humanreadable
│
├─ top-level keys → tColumns(item.field) → GridColDef.headerName
└─ "description" → tColumns(`description.${item.field}`) → GridColDef.description
When GridColDef.description is set to a non-empty string, MUI DataGrid renders
a built-in tooltip on column header hover with no additional code required.
If a field has no description in the API response, tColumns(...) returns the raw
key string, which is then coerced to undefined by || undefined in
DataGrid.tsx. MUI shows no tooltip for undefined descriptions.
How DataGrid.tsx injects descriptions
In fetchData, after /muidatagridconfig columns are processed:
setMuiConfigData({
columns: newData.columns.map((item) => ({
...item,
headerName: tColumns(item.field),
description: tColumns(`description.${item.field}`) || undefined,
}))
});
The same tColumns hook and namespace are used for both label and description.
No extra HTTP requests are made.
Default visible columns
Default column visibility is driven entirely by DEFAULT_COLUMNS on the API side,
communicated to the frontend through the col.hide field in /muidatagridconfig.
Priority chain on first load
1. localStorage "defaultColumns" (if field set matches current API — see below)
│
2. col.hide from /muidatagridconfig (API default — stored on first load)
On first load (or after field-set invalidation), visibilityModel is built from
col.hide, stored to localStorage as defaultColumns, and used immediately.
On subsequent loads the stored preferences take priority.