diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 0000000000000000000000000000000000000000..5284a8710685e440cb72b09118aa3e411490a6ee --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,56 @@ +# Development + +## Installing dependencies + +This project includes a private dependency on a library called [ce-ui-common](https://artifactory.esss.lu.se/ui/repos/tree/General/ics-npm/@ess-ics/ce-ui-common/-) in the Artifactory, for which additional configuration is required. + +1. Create an `.npmrc` file based on the example provided in this registry, substituting your email and base64 credentials, and place it in HOME. +2. Install dependencies with + ```shell + npm ci + ``` + +Note, we lock dependency versions with [package-lock.json](package-lock.json); please install dependencies with `npm ci` (not npm install) to avoid overwriting the package-lock. + +## Updating the API files + +This project uses `@rtk-query/codegen-openapi` to auto-generate the deploy api from its OpenAPI spec. To generate the spec: + +1. To update the api file, run + ``` + npm run generate-api + ``` + See `openapi-config.json` for path information. +2. Commit the changed file. + +Note: default path to api spec is localhost. To generate a new spec BE must run locally. It is possible to change path to any other swagger environment, but it is preferred to use locally running backend. + +## Proxying backends + +For being able to run the backend, and frontend application on the same machine (locally) a proxy has been set in the project. + +If you <ins>don't want to run</ins> the backend server and frontend on the same machine, or have different settings, please adjust the [vite.config.ts](vite.config.ts) at the following line: +`target: "http://localhost:8080"` + +## Tools + +### Frameworks + +- React +- Redux Toolkit + +### Building + +- Vite +- NVM (Optional) + +### Linting and formatting + +- ESLint +- Prettier +- Pre-commit + +### Testing + +- Cypress +- Storybook diff --git a/README.md b/README.md index a8b8b14be82203cf3271ff4399b69ebafcc40a87..9992f543cd5168cabef657afa6ca3fec178b09aa 100644 --- a/README.md +++ b/README.md @@ -1,170 +1,38 @@ # CE deploy & monitor web UI -This project is meant to be the web User Interface for the CE deploy & monitor tool. The project is written in ReactJS. +This project provides a web interface for the [CE deploy & monitor back-end](https://gitlab.esss.lu.se/ccce/dev/ce-deploy-backend), written in React. -## Developing environment +## Quickstart -- NodeJS and npm -- Docker (if want to run backend locally for test purposes) -- IDE for JavaScript developement (e.g. Visual Studio Code) -- Credentials from ESS Artifactory, with permission to the ics-npm registry - -(For developing purposes it is suggested to use _Node Version Manager_ [NVM] which makes easy to change between different Node versions). - -- Windows: https://github.com/coreybutler/nvm-windows -- Mac/Linux: https://github.com/nvm-sh/nvm - -### Required versions - -- Node: v20+ -- npm: v6.10+ - -## Local development setup - -### Installing Dependencies - -This project includes private dependencies from Artifactory, so additional configuration is required. - -1. Create an `.npmrc` file based on the example provided in this registry, substituting your email and base64 credentials. -1. Install dependencies with `npm ci`. - -Note, we lock dependency versions with _package-lock.json_; please install dependencies with `npm ci` (not npm install) to avoid overwriting the package-lock. - -## Updating the API Files - -This project uses `@rtk-query/codegen-openapi` to auto-generate the deploy api from its OpenAPI spec. To generate the spec: - -1. Run `npm run generate-api` to update the api file; see `openapi-config.json` for path information. -1. Commit the changed file. +```shell +npm ci +npm start +``` -Note: default path to api spec is localhost. To generate a new spec BE must run locally. It is possible to change path to any other swagger environment, but it is preferred to use locally running backend. +## Requirements -### Proxying to Existing Backends +- NodeJS and npm +- Credentials from ESS' Artifactory, with permissions to the ics-npm registry -For being able to run the backend, and frontend application on the same machine (locally) a proxy has been set in the project! -If you <ins>don't want to run</ins> the backend server, and frontend on the same machine, or have different settings, please adjust the `vite.config.ts` at the following line: -`target: "http://localhost:8080"` +## Configuration -## External configuration +All necessary configuration is stored in a config file in the `public` folder, called [config.js](public/config.js). The config file has to be included in the [index.html](index.html) file. -All necessary configuration is stored in a config file in the `public` folder, called `config.js`. The config file has to be included in the _index.html_ file! The following values can be set in the file: | Environment variable | Description | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| SERVER_ADDRESS | The backend server base URL _(host:port)_ (if backend server is running natively on the same host as the UI then the value has to be empty, and proxy has to be set!) | -| API_BASE_ENDPOINT | The context path of the application's REST API _(e.g. /api/spec)_ | -| SUPPORT_URL | The URL for where to ask for more support (i.e. service desk) | -| TOKEN_RENEW_INTERVAL | Time interval to renew JWT auth token _(in milliseconds)_ | -| NAMING_ADDRESS | Naming service base URL (used for IOC name Naming reference feature) | -| NETBOX_ADDRESS | Netbox service base URL (used for IOC name Naming reference feature) | -| ENVIRONMENT_TITLE | Adds a (sub)text to the HTLM title, and also for the appBar header. Supposed to show information to the user which environment they are using. The default value is empty. _Optional field!_ | - -Refering to a value in the JS source code is: _window.field-name_ (e.g. window.SERVER_ADDRESS). - -### Setting Environment Variables - -Environment variables are stored in `.env` files. -Precedency of environment variable files are (files on the left have more priority than files on the right): - -- npm start: `.env.development.local`, `.env.local`, `.env.development`, `.env` -- npm run ci:build: `.env.production.local`, `.env.local`, `.env.production`, `.env` - -All environment variables start with `REACT_APP_` prefix. - -## Useful links to start developing in ReactJS - -This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app). - -## Available Scripts - -In the project directory, you can run: - -```bash -npm start -``` - -Runs the app in the development mode.\ -Open [http://localhost:3000](http://localhost:3000) to view it in the browser. - -The page will reload if you make edits.\ -You will also see any lint errors in the console. - -## [ESLint](https://eslint.org) & [Prettier](https://prettier.io) - -Linting can be checked, and to some extent auto fixed by running following scripts: - -```bash -npm run lint -``` - -will run `npx eslint src` which will run eslint on all files in the src directory and write out the results of the check in your console. - -```bash -npm run lint:fix -``` - -will run `npm run lint -- --fix` which will run eslint on all files in the src directory and fix what can be auto fixed and write out the rest of the results of the check, of what could not be auto fixed, in your console. - -```bash -npm run prettier -``` - -will run `npx prettier src --check` which will run prettier on all files in the src directory and write out which files would be changed in your console. - -```bash -npm run prettier:fix -``` - -will run `npm run prettier -- --write` which will run prettier on all files in the src directory and write out which files have be changed in your console. - -## [Pre-Commit](https://pre-commit.com/) - -### Installation - -You will need to install pre-commit first locally on you machine, the install it in you project, instructions on how to do this you can find here: https://pre-commit.com/#install - -By running `pre-commit run --all-files` pre-commit will run both eslint and prettier on all files in src, much like the scripts from the package.json - -## End-to-end testing with Cypress - -For end-to-end testing we user Cypress, tests are written in gherkin syntax. -To run Cypress tests, <ins>you have to</ins> - -- run the backend server -- run the frontend code - -Details: -https://github.com/TheBrainFamily/cypress-cucumber-preprocessor - -Then to open Cypress dialog window enter: - -```bash -npx cypress open -``` - -To run Cypress tests from command line (without the test-dialog), enter - -```bash -npx cypress run -``` - -## Building - -```bash -npm run ci:build -``` - -Builds the app for production to the `build` folder.\ -It correctly bundles React in production mode and optimizes the build for the best performance. - -The build is minified and the filenames include the hashes.\ -Your app is ready to be deployed! - -See the section about [deployment](https://vite.dev/guide/static-deploy.html) for more information. +| `SERVER_ADDRESS` | The backend server base URL _(host:port)_ (if backend server is running natively on the same host as the UI then the value has to be empty, and proxy has to be set!) | +| `API_BASE_ENDPOINT` | The context path of the application's REST API _(e.g. /api/spec)_ | +| `SUPPORT_URL` | The URL for where to ask for more support (i.e. service desk) | +| `TOKEN_RENEW_INTERVAL` | Time interval to renew JWT auth token _(in milliseconds)_ | +| `NAMING_ADDRESS` | Naming service base URL (used for IOC name references feature) | +| `NETBOX_ADDRESS` | NetBox base URL (used for IOC host references) | +| `ENVIRONMENT_TITLE` | Adds a (sub)text to the HTLM title, and also for the appBar header. Supposed to show information to the user which environment they are using. The default value is empty. _Optional field!_ | +| `FRONTEND_VERSION` | Version of application to display on help page | -## Learn More +Refering to a value in the JS source code is: _window.field-name_ (e.g. `window.SERVER_ADDRESS`). -You can learn more in the [vite documentation](https://vite.dev/guide/). +## Development -To learn React, check out the [React documentation](https://reactjs.org/). +See [DEVELOPMENT.md](DEVELOPMENT.md).