|
| 1 | +# BIL Validator Tool |
| 2 | + |
| 3 | +The BIL Validator Tool is a web based validation tool for eCMR documents notarized by the BIL eCMR platform. |
| 4 | +Furthermore, the tool can be built as native App using the Electron framework. |
| 5 | + |
| 6 | + |
| 7 | + |
| 8 | +## Requirements |
| 9 | + |
| 10 | +``` |
| 11 | +git ^2.24.0 |
| 12 | +node ^12.16.1 |
| 13 | +npm ^6.13.4 - included with node version 12.16.1 |
| 14 | +yarn ^1.22.4 |
| 15 | +bash ^5.0.11 or similar shell engine to call scripts |
| 16 | +``` |
| 17 | + |
| 18 | +## Project setup |
| 19 | + |
| 20 | +```shell script |
| 21 | +// clone repository: |
| 22 | +git clone <this-repo> |
| 23 | + |
| 24 | +// move into project folder |
| 25 | +cd ./validator-tool |
| 26 | + |
| 27 | +// install dependencies |
| 28 | +yarn |
| 29 | +``` |
| 30 | + |
| 31 | +## Structure |
| 32 | + |
| 33 | +The project is divided into the following three packages: |
| 34 | + |
| 35 | +- backend |
| 36 | +- frontend |
| 37 | +- native |
| 38 | + |
| 39 | +The `backend` handles fetching of the eCMR data, resolving the CMR Nr. and Pin-Code and checking the validity of the given document. |
| 40 | + |
| 41 | +The `frontend` sends the given PDF document or the CMR No. and Pin-Code to the backend and then displays the result of the validation and the data inside the CMR document. |
| 42 | + |
| 43 | +The `native` package contains the required electron files. Each package contains its own README, which should be carefully read before using the application. |
| 44 | + |
| 45 | + |
| 46 | +### Folder structure |
| 47 | + |
| 48 | +- to easily manage the monorepo-structure, the project is setup with yarn workspaces and lerna and the setup follows best-practices from the lerna and yarn documentation pages. If you don't know about lerna and yarn workspaces you can start with an introduction and a comparison to other approaches [here](https://doppelmutzi.github.io/monorepo-lerna-yarn-workspaces). |
| 49 | +- the mentioned tooling divides our project in a root-project and 3 sub-packages in the packages folder |
| 50 | +- these sub projects are divided in: |
| 51 | + - api: contains a nodeJS application using the NestJS framework for serving a REST-backend. This package is responsible for proxying eCMR-REST APIs and providing additional functionalities for the frontend. Additionally this module can be deployed as single backend using docker. |
| 52 | + - web: contains a SPA (S ingle P age A pplication) written in React. This part represent the main-view of our application and can be deployed with a webserver like nginx (docker) or as single html/js/css-package. |
| 53 | + native: contains a wrapper application with electron that bundles the api package and web package into a full native desktop application for Windows, Linux and macOS. |
| 54 | +- additional information regarding single packages can be taken from the README in the respective package-folder |
| 55 | +- one additional folder in the root package is e2e: this contains testing logic for e2e tests of backend/api/native packages |
| 56 | + |
| 57 | +## Usage |
| 58 | + |
| 59 | +- there is a root `package.json` containing useful scripts utilizing lerna for e.g. linting, building or testing of the whole project - just have a look at the defined scripts in root `package.json`. |
| 60 | +- every package contains its own `package.json` file with its own naming scheme and can be deployed |
| 61 | +and run individually. Further information on running and building subpackages can be taken from the respective README or `package.json`. |
| 62 | +- to run a command in a subpackage, simply `cd` into a package and run the specific commands. |
| 63 | +- in the root `package.json` file also Docker scripts are configured to run and deploy docker containers providing the backend and web package. To use these scripts, docker and docker-compose must be installed. |
| 64 | +- Docker-images have to be built from the root directory as the whole monorepo is copied from `cwd` into the Docker build context and access to parent folders is denied when starting a build from a specific subfolder. |
| 65 | + |
| 66 | +### Development commands |
| 67 | + |
| 68 | +The project's `package.json` contains predefined commands for running and deploying the project for development. These commands |
| 69 | +need to be executed from the root folder of the project. The subpackages located in the `packages` folder contain additional commands |
| 70 | +for the individual packages. |
| 71 | +The api package can be started using the following command: |
| 72 | + |
| 73 | +```shell script |
| 74 | +yarn dev:api |
| 75 | +``` |
| 76 | + |
| 77 | +For running the frontend the following command should be used: |
| 78 | + |
| 79 | +```shell script |
| 80 | +yarn dev:web |
| 81 | +``` |
| 82 | + |
| 83 | +Furthermore, starting the desktop application can be done via the following command: |
| 84 | + |
| 85 | +```shell script |
| 86 | +yarn dev:native |
| 87 | +``` |
| 88 | + |
| 89 | +### Docker Deployment |
| 90 | + |
| 91 | +#### Frontend |
| 92 | + |
| 93 | +```shell script |
| 94 | +docker create \ |
| 95 | + --name=frontend \ |
| 96 | + -e BASEPATH=/ \ |
| 97 | + -e BACKEND_URL=<URL_OF_BACKEND> \ |
| 98 | + -p 8082:8082 \ |
| 99 | + ss20aseqse01/web:latest |
| 100 | +``` |
| 101 | + |
| 102 | +##### Environment-Variables |
| 103 | + |
| 104 | +| Parameter | Function | |
| 105 | +|-----------|----------| |
| 106 | +|BASEPATH|Used to set the URL of the frontend. Should start with '/' and should not end with '/'.| |
| 107 | +|BACKEND_URL|Used to give the container the URL or IP of the backend system| |
| 108 | + |
| 109 | +#### Backend |
| 110 | + |
| 111 | +```shell script |
| 112 | +docker create \ |
| 113 | + --name=backend \ |
| 114 | + -v <PATH_TO_LOGS>:/tmp/validator/logs/ |
| 115 | + -e LOGDIR_PATH=/tmp/validator/logs/ \ |
| 116 | + -e SWAGGER_PATH=/swagger \ |
| 117 | + -p 8083:8083 \ |
| 118 | + --restart unless-stopped \ |
| 119 | + ss20aseqse01/api:latest |
| 120 | +``` |
| 121 | + |
| 122 | +##### Environment-Variables |
| 123 | + |
| 124 | +| Parameter | Function | |
| 125 | +|-----------|----------| |
| 126 | +|LOGDIR_PATH|Used to set the location for log files inside the container| |
| 127 | +|SWAGGER_PATH|Used to set the URL for the swagger backend| |
| 128 | + |
| 129 | +#### Docker-compose |
| 130 | + |
| 131 | +In order to run the application in a dockerized manner, please use the given `docker-compose.yml` file. The file contains further |
| 132 | +docker-specific comments for the deployment. |
| 133 | +Using Docker Compose the application with default values can be started using: |
| 134 | + |
| 135 | +```shell script |
| 136 | +docker-compose up |
| 137 | +``` |
| 138 | + |
| 139 | +If you want to supply a custom configuration for REST-Endpoints, add the following line to the `api` container in the `docker-compose.yml`: |
| 140 | + |
| 141 | +```dockerfile |
| 142 | +volumes: |
| 143 | +- <PATH TO YOUR REST CONFIG JSON FILE>:/app/restConfiguration.json |
| 144 | +``` |
| 145 | + |
| 146 | +After executing `docker-compose up` again the new config should be injected and overrides the initial configuration file. |
| 147 | + |
| 148 | +#### Tips and Tricks |
| 149 | + |
| 150 | +- use an IDE like IntelliJ/Webstorm/VSCode and install plugins for development like prettier, eslint, npm-scripts, browser-debugging etc. |
| 151 | +- use tooling like IntelliSense and language support for TypeScript, React, JS and config files like babel, eslint, editorconfig etc. |
| 152 | +- disable IDE-indexing of node_modules as every change cases a reindex on the whole node_modules folder |
| 153 | +- web-apps can be debugged by attaching a debugger to the dev-server started by most of the packages in background |
| 154 | +- disable save-writes and switch to manual-saves in the IDE as the dev-servers watch file changes and build changed parts instantly - a write from IDE on every letter may cause the dev-server to build uninterrupted (activate also asterx to don't forget unsaved files) |
| 155 | +- turn on eslint auto-detection as all eslint-config files are present in the project and the eslint is contained in the project, so there is no need to specify an extra instance with own linting-rules |
| 156 | +- if some linting-rules are not useful, make a suggestion in a merge-request, maybe the current eslint-rules are too messy and should be sorted out |
| 157 | + |
| 158 | +#### Resources |
| 159 | + |
| 160 | +##### Debugging |
| 161 | + |
| 162 | +- [Client side debugging with JetBrains IDEs like IntelliJ](https://www.jetbrains.com/help/idea/running-and-debugging-typescript.html) |
| 163 | +- Disable safe writes: [here](http://thehunk.blogspot.com/2015/07/disable-auto-save-in-jetbrains-ide.html) or [here](https://parceljs.org/hmr.html#safe-write) |
| 164 | + |
| 165 | +##### Lerna and Yarn Workspaces |
| 166 | + |
| 167 | +- [Configuration of typescript with lerna](https://medium.com/@NiGhTTraX/how-to-set-up-a-typescript-monorepo-with-lerna-c6acda7d4559) |
| 168 | +- [Lerna Typescript structure - also describing module resolution with Typescript (ts references)](https://github.com/Quramy/lerna-yarn-workspaces-example) |
| 169 | +- [Lerna managed multi-sdk project](https://medium.com/mitterio/multirepo-to-lerna-js-monorepo-80f6657cb443) |
| 170 | +- [Another Lerna managing a frontend/backend app](https://medium.com/the-andela-way/using-lerna-to-manage-js-monorepos-b7b8611f2ff3) |
| 171 | + |
| 172 | +##### React |
| 173 | + |
| 174 | +- [React Bootstrap UI](https://react-bootstrap.netlify.com) |
| 175 | +- [Electron React Boilerplate](https://github.com/electron-react-boilerplate/electron-react-boilerplate) |
| 176 | + |
| 177 | +##### Electron |
| 178 | + |
| 179 | +- [Electron](https://www.electronjs.org/) |
| 180 | +- [Electron builder](https://www.electron.build/) |
| 181 | + |
| 182 | +##### Bundler |
| 183 | + |
| 184 | +- [Webpack](https://webpack.js.org/concepts/) |
| 185 | +- [How to Set Up a React TypeScript Project from Scratch with Babel and Webpack](https://medium.com/@dahvinchee/how-to-set-up-a-react-typescript-project-from-scratch-with-babel-and-webpack-6b069881229d): also describes how babel can be used to transform typescript. |
| 186 | +- [Bundler decision/Parcel vs Webpack](https://blog.jakoblind.no/parcel-webpack) |
| 187 | + |
| 188 | +##### NestJS |
| 189 | + |
| 190 | +- [NestJS docs](https://docs.nestjs.com/) |
| 191 | +- [NestJS examples](https://github.com/nestjs/nest/tree/master/sample) |
| 192 | + |
| 193 | +##### Codequality |
| 194 | + |
| 195 | +- [ESLint and Prettier in Typescript project](https://dev.to/robertcoopercode/using-eslint-and-prettier-in-a-typescript-project-53jb) |
| 196 | +- [Migrating from TSLint to ESLint](https://medium.com/@cosmvs/painless-migration-from-tslint-to-eslint-for-react-with-typescript-4befb4918ba8) |
| 197 | +- [Enable Prettier](https://prettier.io/docs/en/webstorm.html#running-prettier-on-save-using-file-watcher) |
| 198 | +- [Preferred style guidelines (contains links to airbnb)](https://blog.geographer.fr/eslint-guide) |
| 199 | +- [TypeScript types vs interfaces](https://pawelgrzybek.com/typescript-interface-vs-type/) |
| 200 | +- [TypeScript cheat sheet](https://github.com/typescript-cheatsheets/react-typescript-cheatsheet) |
| 201 | + |
| 202 | +##### Documentation |
| 203 | + |
| 204 | +- [Markdown Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) |
| 205 | +- [Gitlab Markdown](https://reset.inso.tuwien.ac.at/repo/help/user/markdown) |
| 206 | +- [jsdoc](https://jsdoc.app/) |
| 207 | +- [NestJS code-documentation](https://docs.nestjs.com/recipes/documentation) |
| 208 | + |
| 209 | +##### Testing |
| 210 | + |
| 211 | +- [Testing Typescript applications](https://journal.artfuldev.com/unit-testing-node-applications-with-typescript-using-mocha-and-chai-384ef05f32b2) |
| 212 | +- [4 ways of structure tests in your application](https://stackoverflow.com/questions/20548723/how-do-you-structure-your-tests-for-your-server-applications-in-node-js) |
| 213 | +- [Debugging/Testing NodeJS app](https://scalified.com/2017/11/01/nodejs-typescript-intellij-debug/) |
| 214 | +- [NestJS](https://docs.nestjs.com/fundamentals/testing) |
| 215 | +- [NestJS unit tests article](https://medium.com/@jackallcock97/unit-testing-with-nestjs-and-jest-a-comprehensive-tutorial-464910f6c6ba) |
0 commit comments