Skip to content

Developer Guide

Jump to bottom
Matteo Guarnaccia edited this page Oct 30, 2025 · 20 revisions

Workflow

  1. Select a issue from the IMS issues.
  2. Pull the latest version of the develop branch
  3. Create a branch from there called #{insert label (e.g feature or bug)}/{insert general name of story}-#{story number}
  4. Put the issue into In Progress
  5. Repeatedly during development:
    1. Develop code/write tests
    2. Ensure all tests pass
    3. Run linter and fix issues
    4. Commit - ideally, each commit message should have the issue number included, so that we can track the code related to resolving the issue
    5. (optionally) push to origin
  6. Merge origin/develop into your feature branch.
  7. Run unit tests
  8. Check impact on coverage
  9. Run e2e tests
  10. Push to origin
  11. Make a pull request - the PR description should also point to the relevant issue
  12. Put the issue into In Review
  13. Get the pull request reviewed, if more work needs to be done go back to step 4.
  14. Wait for the automated build (if it exists, otherwise the reviewer should do these steps)
  15. Once a pull request is approved then it can be merged back into origin/develop
  16. Wait for the automated build for the merge in to develop to pass.
  17. Move the issue to Done and close the issue.

Branching Strategy

When working on a new feature the branch should follow the naming convention feature/{insert general name of story}-#{story number}. This indicates it is new functionality as well as linking it to the story (for potential future requirement tracing)

If working on a bug from a previous story then the branch should follow the pattern bugfix/{general name of bug}-#{story/bug number}.

Required Tools

To develop the Inventory management system you will need the following tools:

  • Node.js (https://nodejs.org/en/) - (LTS version at the time of writing is 20.17.0)
  • NPM (comes with the node.js installation)
  • An IDE for developing with JavaScript (VS Code is a good cross-platform suggestion)
  • Yarn
  • Docker
  • Docker Compose

Installation instructions are available on the sites for each tool and depend on your operating system, e.g. node can be installed as an msi on a windows machine

Note: if installing Node.js on Linux machines please read https://nodejs.org/en/download/package-manager/ as these detail how to ensure you are able to get the most recent version of Node.js on your machine, rather than an old version in the default package.

Helpful tools

E2E interactive Testing

Initial Configuration

PuTTYgen

  • Generate a public/private key pair with default parameters (RSA, 2048 bits), saving both public and private keys.
  • Copy the public key to your VM, under .ssh/authorized_keys in the format ssh-rsa PUBLIC_KEY rsa-key-YYYYMMDD filling in the rsa-key-date from the Comment in the key file.

PuTTY

  • Under the category: Session, under host name enter your-fed-id@VM-IP-ADDRESS
  • Under the category: Connection -> SSH -> X11, make sure that Enable X11 forwarding is enabled.
  • Under the category: Connection -> SSH -> Auth -> Credentials, add your private key (from the PuttyGen step).
  • Return to category: Session, under Saved Sessions enter a name to save your VM settings as (i.e Dev VM) and press Save.

IMPORTANT: Make sure to always select the saved session settings and press load whenever starting up Putty.

Usage

XLaunch

  • Open XLaunch, and select Multiple Windows and continue.
  • Select Start no client and continue.
  • Select Disable Server Access Control and continue. image
  • Select Finish

PuTTY

  • Load Saved session settings and select open.

IDE

  • Return to your IDE, connect to your VM, and open the terminal.
  • enter export DISPLAY=localhost:10.0, or any other unused localhost
  • run xeyes to make sure everything is working (should open a new window).

You can now run interactive tests with yarn:e2e:interactive and yarn:e2e:interactive:api

New developer tutorials

Here's a list of useful tutorials to help new developers learn the technologies required:

Starting the Inventory Management System for development

First of all, you will need to clone the repository and navigate to the project directory:

git clone [email protected]:ral-facilities/inventory-management-system.git
cd inventory-management-system

Create a inventory-management-system-settings.json file

cp public/inventory-management-system-settings.example.json public/inventory-management-system-settings.json

Run install all the dependancies

yarn install

When switching branches you may need to run yarn install if the branch you are on has installed extra dependencies

If you get errors about dependencies not being met, especially after switching branches, then this may be due to yarn having mismatching versions and getting stuck and unable to upgrade. This can usually be fixed by deleting the node_modules folder and running yarn install freshly

Starting Dev serve with Mock data (MSW)

Local

Start the website

yarn dev

Docker

Build and start the Docker containers:

docker-compose up

The website should now be running at http://localhost:3000.

Starting the Dev serve with IMS API

Start IMS API (using docker-compose.yml)

IMS API should be running http://localhost:8000. To check if it is running correctly you access the open api docs.

Edit the apiUrl in the inventory-management-system-settings.json to be

  • 'http://localhost:8000'

Local

Start the website

yarn dev

Docker

Build and start the Docker containers:

docker-compose up

The website should now be running at http://localhost:3000.

Starting IMS with Scigateway with authentication

Start IMS API (using docker-compose.yml)

IMS API should be running http://localhost:8000.

Edit the apiUrl in the inventory-management-system-settings.json to be

  • 'http://localhost:8000'

Start ldap-jwt-auth (using docker-compose.yml)

ldap-jwt-auth should be running http://localhost:8001.

Start Scigateway(on react-18 branch react-18-#1205)

{
   "plugins": [
     {
      "name": "inventory-management-system",
      "src": "http://localhost:5001/main.js",
      "enable": true,
      "location": "main"
     }
   ],
   "auth-provider": "jwt",
   "authUrl":"http://localhost:8001"
}

Starting IMS

Start the website

yarn preview:build

This should build the main.js on http://localhost:5001.

Without authentication

  • Skip these step Start ldap-jwt-auth (using docker-compose.yml)

  • Make sure that AUTHENTICATION__ENABLED set to false in the .env in IMS API

  • The scigateway setting.json should look like this

{
   "plugins": [
     {
      "name": "inventory-managment-system",
      "src": "http://localhost:5001/main.js",
      "enable": true,
      "location": "main"
     }
   ],
   "auth-provider": null,
   "authUrl":""
}

Using Authorisation with the Inventory Management System

IMS utilises authorisation to enable extra functionality for privileged (currently just admin) users. A banner is shown to users if they are currently a privileged role.

The extra functionality of an admin includes

  • Creating and deleting units and usage statuses
  • Ability to bypass rules when creating, editing, deleting or moving items.

During development, you can enable admin functionality using several different methods. The available options are outlined below.

Via the toggle in development mode

A Privileged user toggle is available in development mode (positioned in the top right of the screen), which switches between an admin and default user.

Using ldap-jwt-auth

By following the instructions in ldap-jwt-auth here, you can create an admin user, and then generate an access token which contains a privileged role. Following this you can then either

a) Follow the Scigateway setup instructions above and login with the admin credentials specified.

b) Follow the IMS API setup instructions above and use the generated access token.

This will grant you privileged functionality in the Inventory Management System.

Common commands

Here is a list of common commands used in development and a short description of what they do

  • yarn dev - start the development server that does hot reloading
  • yarn build - build the final bundled javascript
  • yarn test - run the tests and calculate the coverage
  • yarn lint - lint (and fix as much as possible) the typescript/javascript code
  • yarn e2e - run the end-to-end tests in a headless mode with mock data (useful for CI systems)
  • yarn e2e:interactive - run the end-to-end tests interactively with mock data (useful for debugging e2e tests)
  • yarn e2e:api - run the end-to-end tests in a headless mode using the api (useful for CI systems)
  • yarn e2e:interactive:api - run the end-to-end tests interactively using the api (useful for debugging e2e tests)

More commands can be found in package.json - specifically in the scripts section

Clone this wiki locally