Resolve "Move the Web module into a separate project"

stages:

    - build

    - deploy

    - release

#

# Build and test whenever the code is pushed to the the gitlab.

# Build and test whenever the code is pushed to the gitlab.

# Also, generate Javadoc.

# The -Ptest option sets the usage profile of the Web module.

# Use the -DadditionalJOption=-Xdoclint:none option to avoid strict control when generatig Javadoc.

#

build-and-test-job:

  stage: build

  script:

    - mvn clean install javadoc:javadoc javadoc:aggregate $MAVEN_JAVADOC_OPTS $MAVEN_CLI_OPTS -Ptest;

    - mvn clean install javadoc:javadoc javadoc:aggregate $MAVEN_JAVADOC_OPTS $MAVEN_CLI_OPTS;

#    - >

#      mvn clean install $MAVEN_CLI_OPTS -Ptest;

#      if [ "$CI_COMMIT_BRANCH" == "$CI_DEFAULT_BRANCH" ]; then

    expire_in: 1 hour

    when: on_success

#

# Update the staging web server whenever the code is pushed to master, e.g., when merging development branches.

#

staging-job:

  stage: deploy

  image: ubuntu:latest

  before_script:

#    - 'command -v ssh-agent >/dev/null || ( apk add --update openssh )'

    - 'command -v ssh-agent >/dev/null || ( apt-get update -y && apt-get install openssh-client -y )'

    - eval $(ssh-agent -s)

    - echo "$SSH_STAGING_PRIVATE_KEY" | tr -d '\r' | ssh-add -

    - mkdir -p ~/.ssh

    - chmod 700 ~/.ssh

    - ssh-keyscan $STAGING_IPADDRESS >> ~/.ssh/known_hosts

    - chmod 644 ~/.ssh/known_hosts

  script:

    - ssh $SSH_STAGING_USER@$STAGING_IPADDRESS "chmod u+x /opt/fidentis-analyst/analyst2/scripts/staging.sh; /opt/fidentis-analyst/analyst2/scripts/staging.sh $STAGING_POSTGRESQL_DB_NAME $STAGING_POSTGRESQL_USER $STAGING_POSTGRESQL_PASSWORD"

    - eval $(ssh-agent -k)

  tags:

    - shared-fi

  only:

    - master

  environment:

    name: staging

    url: http://172.26.2.223:8081/

#

# Upload the code of a new release of the project onto the project's web server

# (only if commiting to the master branch and the VERSION.txt file has changed)

HELP.md

target/

!.mvn/wrapper/maven-wrapper.jar

!**/src/main/**/target/

!**/src/test/**/target/

### STS ###

.apt_generated

.classpath

.factorypath

.project

.settings

.springBeans

.sts4-cache

### IntelliJ IDEA ###

.idea

*.iws

*.iml

*.ipr

### NetBeans ###

/nbproject/private/

/nbbuild/

/dist/

/nbdist/

/.nb-gradle/

build/

!**/src/main/**/build/

!**/src/test/**/build/

### VS Code ###

.vscode/

distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.8.6/apache-maven-3.8.6-bin.zip

wrapperUrl=https://repo.maven.apache.org/maven2/org/apache/maven/wrapper/maven-wrapper/3.1.0/maven-wrapper-3.1.0.jar

# FIDENTIS Analyst 2 - web application

Web application of FIDENTIS Analyst 2 desktop software which is re-implementation of [FIDENTIS Analyst](https://github.com/Fidentis/Analyst).

---

## Requirements

Backend dependencies:

* [Oracle JDK 17](https://www.oracle.com/java/technologies/downloads/#java17) (with all %JAVA_PATH% set up)

* [Maven](https://www.mkyong.com/maven/how-to-install-maven-in-windows/) (even there is folder `.mvn` and files `mvnw` and `mvnw.cmd` that should help run it without it but it's better to have installed)

* [PostgreSQL 15](https://www.postgresql.org/download/) - for database (setup is described in development guide)

Frontend dependencies:

* [Node](https://nodejs.org/en/) - version: `16.13.1` (the best way to install direct versions of node is via [nvm](https://github.com/nvm-sh/nvm))

* [npm](https://www.npmjs.com/package/npm) - version `8.1.2`

---

## Installation and running

To build whole module run `mvn clean install`. This command also copy frontend part of the application to output `.jar`. <br>

To run application from command line, you have to set your database (see developer\`s guide how to run it locally) and run command `mvn spring-boot:run {profile}`.

Application supports 2 profiles:

* production: `-Pprod`

* development: `-Pdev`

---

## Developer\`s guide

Application is divided into the frontend application via [React](https://reactjs.org/) library, [THREE.js](https://threejs.org/) and other supplement packages. 

Backend is written in [Spring Boot](https://spring.io/projects/spring-boot) (version 2.7.5).

### Frontend application

Can be found inside `frontend` folder in `Web` module. Proxy servers for development are set in: `vite.config.ts`. For tooling is used [Vite](https://vitejs.dev/).

Main language is [Typescript](https://www.typescriptlang.org/) so everything has to be correctly typed (no usage of `any`). And UI component library is [MUI](https://mui.com/). 

For styling purposes the packages installed are [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/). Configuration are taken from public packages by [Haaxor1689](https://github.com/Haaxor1689).

#### Folder system:

* `assets` - folder to place any extra `.scss` files and any image/icon that is used inside application

* `components` - folder for all custom components (may change in future if there will be too many)

* `hooks` - folder for all custom hooks

* `pages` - folder any separate view that will be used for routing

* `providers` - folder for all contexts

* `services` - folder for all files that handles backend calls (using [Axios](https://axios-http.com/)). Each file should contain only on `URL` variable that copy backend endpoints mapping

* `types` - folder for all general typings

* `utils`

#### Running frontend for development

First start with command: `npm install` inside folder `./Web/frontend`. This command will install all needed packages that are mentioned inside `package.json`.

<br>

For development run command: `npm run dev` inside folder `./Web/frontend`. This command starts development server with hot reload. This server runs on URL `http://127.0.0.1:5173`

and after every change and save content is reloaded.

### Backend application

Firstly, we have to set up `application.yml` more precisely development properties that will match our local setup. Go inside folder: `./src/main/resources`. Here open file: `application-dev.yml`.

This file should contain only your local values (aka postgres database name, username and password). So after creating local database fill these attributes correctly and **!DO NOT PUSH THIS FILE TO ORIGIN!**.

After this setup we can run command: `mvn clean install` if we didn't before for whole project. This will create runnable `.jar` file with frontend application bundled in.

<br>

To start server run command: `mvn spring-boot:run` (`-Pdev` profile is default profile set in `pom.xml` it will start it in development profile, so it will pick development properties).

#### Manipulating database

To create, update, delete tables/columns there is installed [liquibase](https://docs.liquibase.com/tools-integrations/springboot/springboot.html). This provides for developers easy way of writing simple scripts (changelogs)

that will run at the start of application (only changelogs that didn't already run - there are records in database which changelogs already run). Scripts are written in `xml` and files can be found

inside folder: `./src/main/resources/db/changelog`. Naming convention is: `changelog-{id}` where id is integer incrementing by 1 (it has to be unique) and this file is after included into main

file `master-changelog.xml`. Each changelog can contain multiple `<changeSet>` tags where each have to have unique id starting with id of file.

#### Running tests

To run tests, the developer has to have installed [Docker](https://www.docker.com/). No registration or running special images are needed only start docker. Tests will create `@Testcontainer` with PostgreSQL database to have

the same environment as in production. `AbstractIntegratrionTest` contains all setup and `@MockBean` necessary. This implementation has one limitation that is impossibility running all tests at once because

the container is not shared across classes. Developer has to start each test class manually.

#### Mail service

To test mail service in development, install NPM package [maildev](https://www.npmjs.com/package/maildev) which provide simple GUI and mail server. All properties for Spring Boot application are already

implemented in `application-dev.yml` file. If you want to run mail server on different ports you have to change these settings also.

#### Folder system:

* `config` - all configuration files (Spring security, Jwt tokens etc.)

* `controllers` - all REST API controllers

* `dto` - special data classes used for mapping objects for transport between FE and BE

* `exceptions` - all custom exceptions and main `@ControllerAdvice` are defined here

* `mail` - classes for mail service

* `models` - application models (database follows these object as tables)

* `repostory` - folder for files to handle operations with models (deletion, update etc)

* `security` - all classes for Spring Security - filters, permission evaluators

* `services` - folder for business logic of every endpoint

* `utils`

 No newline at end of file