|
| 1 | +<!-- |
| 2 | +SPDX-FileCopyrightText: 2021 Alliander N.V. |
| 3 | +
|
| 4 | +SPDX-License-Identifier: Apache-2.0 |
| 5 | +--> |
| 6 | + |
| 7 | +# Development for CoMPAS OpenSCD |
| 8 | + |
| 9 | +## Building |
| 10 | + |
| 11 | +If you want to build CoMPAS OpenSCD yourself in order to make some changes to your local installation or to contribute |
| 12 | +to the project, you may first want to install [Node.js](https://nodejs.org/) in order to be able to use our local |
| 13 | +development setup. |
| 14 | + |
| 15 | +Once Node.js is installed on your system, you may get started by entering the following lines in your command prompt: |
| 16 | + |
| 17 | +``` |
| 18 | +git clone https://github.com/com-pas/compas-open-scd |
| 19 | +cd compas-open-scd |
| 20 | +npm install |
| 21 | +npm start |
| 22 | +``` |
| 23 | + |
| 24 | +This will start a local development server and open a browser window which will automatically be reloaded as soon as you |
| 25 | +save any changes to your local source code files. |
| 26 | + |
| 27 | +## Linting & Formatting |
| 28 | + |
| 29 | +If you use VSCode to develop, we recommend you install and use |
| 30 | +the [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) |
| 31 | +and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) extensions in order to |
| 32 | +automatically lint and format your code as you edit it. There are similar plugins available for |
| 33 | +using [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/) from within other IDEs and text editors. |
| 34 | + |
| 35 | +## Scripts |
| 36 | + |
| 37 | +We provide the following `npm` scripts for your convenience: |
| 38 | + |
| 39 | +- `npm start` runs `CoMPAS OpenSCD` for development, reloading on file changes |
| 40 | +- `npm test` runs the test suite with Karma |
| 41 | +- `npm run lint` runs the linter (fixes problems in your code) |
| 42 | +- `npm run format` runs the formatter (formats your code in a unified way) |
| 43 | +- `npm run doc` builds HTML documentation into the `doc` directory |
| 44 | +- `npm run build` builds a deployable version of the project into the `dist` directory |
| 45 | + |
| 46 | +## Docker |
| 47 | + |
| 48 | +It's also possible to run CoMPAS OpenSCD as a docker. Of every release a docker image is created and pushed to Docker |
| 49 | +Hub. To run the docker container use the following command. |
| 50 | + |
| 51 | +``` |
| 52 | +docker run -it --rm -d -p 8080:80 --name compas-open-scd lfenergy/compas-open-scd:latest |
| 53 | +``` |
| 54 | + |
| 55 | +Now open a browser and go to "http://localhost:8080". CoMPAS OpenSCD is shown. |
| 56 | + |
| 57 | +## CoMPAS Service |
| 58 | + |
| 59 | +During development, it is sometimes handy to use running backend services, like CIM Mapping or SCL Data Service. |
| 60 | +The problem is that these services need an Authorization Header to work. Normally these are injected by a reverse proxy |
| 61 | +or something like that. |
| 62 | + |
| 63 | +There is a work-around and that is using the ModHeader Extension of the Browser (Chrome, Firefox, ...). |
| 64 | +With this extension the header 'Authorization' can be added with a value 'Bearer <access token>'. |
| 65 | + |
| 66 | + |
| 67 | + |
| 68 | +URL Filters is used to only send this Request Header to the configured URLs. |
| 69 | + |
| 70 | +To retrieve an Access Token from a running KeyCloak instance there is a Postman collection, see below. |
| 71 | + |
| 72 | +### CoMPAS Services depends on a running KeyCloak instance |
| 73 | + |
| 74 | +A KeyCloak instance needs to be running on port 8089 by default in dev mode. If a custom KeyCloak instance is used see |
| 75 | +[Security](README.md#security) for more details. |
| 76 | + |
| 77 | +There is a preconfigured Demo KeyCloak instance available for CoMPAS in the |
| 78 | +[CoMPAS Deployment Repository](https://github.com/com-pas/compas-deployment). This repository can be cloned and |
| 79 | +used to execute the following commands to create a local Docker Image with the CoMPAS Demo configuration. |
| 80 | + |
| 81 | +```shell |
| 82 | +cd <CoMPAS Deployment Repository Directory>/compas/keycloak |
| 83 | +docker build -t compas_keycloak . |
| 84 | +``` |
| 85 | + |
| 86 | +A Docker Image `compas_keycloak` is created that can be started using the following command |
| 87 | + |
| 88 | +```shell |
| 89 | +docker run --rm --name compas_keycloak \ |
| 90 | + -p 8089:8080 |
| 91 | + -d compas_keycloak:latest |
| 92 | +``` |
| 93 | + |
| 94 | +There are now 3 users available to be used, `scl-data-editor`, `scl-data-reader`, `scd-reader`. See |
| 95 | +[CoMPAS Deployment Repository](https://github.com/com-pas/compas-deployment) for more information about the users. |
| 96 | + |
| 97 | +### Postman |
| 98 | + |
| 99 | +To make a call to the CoMPAS Backend Service work in CoMPAS OpenSCD we need to import an environment and authorisation |
| 100 | +collection. These files can be found in [CoMPAS Deployment Repository](https://github.com/com-pas/compas-deployment) |
| 101 | +in the directory `postman` (`auth.collection.json` and `local.environment.json`). |
| 102 | + |
| 103 | +In the authorisation collection there are called for the 3 users known within the Demo KeyCloak instance. |
| 104 | +If one of these calls are executed you can switch to the tab `Visualize`. There is a button to copy the bearer to the |
| 105 | +clipboard. This will also be done automatically when switching to the tab (label becomes `Copied!`). |
| 106 | +The value of the clipboard can be copied in ModHeader Extension as Authorization Header. |
| 107 | + |
| 108 | +Hint: `Bearer` is included in the value of the clipboard, so the complete value in ModHeader can be replaced. |
0 commit comments