diff --git a/CHANGELOG.md b/CHANGELOG.md index 74c8cb0b71..a0a189d0b1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,9 @@ _**For better traceability add the corresponding GitHub issue number in each cha - #1244 upgraded registry from 0.4.1 to 0.5.0 - #XXX update e2e-tests-xray_frontend.yml to support association int environment +### Added +- #511 Added installation guide for local frontend with umbrella chart + ## [13.0.0 - 19.07.2024] ### Added diff --git a/INSTALL.md b/INSTALL.md index ffdc4138a5..d391f5229a 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,9 +1,124 @@ # Installation Instructions +## Installation Instructions Helm + +### Install Helm chart from the Helm chart repository + +``` +# 1. Add the helm chart repository: +helm repo add tractusx-dev https://eclipse-tractusx.github.io/charts/dev +``` + +``` +# 2. Install traceability-foss chart into your cluster: +helm install traceability-foss tractusx-dev/traceability-foss +``` +### Use Helm chart as dependency on your own Helm chart + +``` + dependencies: + - name: traceability-foss + repository: https://eclipse-tractusx.github.io/traceability-foss + version: 1.x.x +``` + +### Configure product-example Helm chart on your needs + +Please have a look into our [Helm chart documentation](charts/traceability-foss/README.md) for more information about the configuration options. + ## Installation Instructions Frontend -- [Installation Instructions Frontend](frontend/INSTALL.md) +### Prerequisites + +* [Node.js 18](https://nodejs.org/en) +* [Angular CLI](https://angular.io/cli) +* [YARN](https://yarnpkg.com/) + +### Getting started + +Clone the source locally: + +```bash +$ git clone git@github.com:eclipse-tractusx/traceability-foss.git +$ cd traceability-foss/frontend +``` + +#### Install prerequisites: + +install [node.js](https://nodejs.org/en/download/package-manager) +```bash +$ npm install --global yarn +$ npm install -g @angular/cli +$ yarn install +``` + +Start application with ``yarn start`` and navigate to ``http://localhost:4200``. + +To run the frontend locally with an already existing backend, use the run configs in [frontend/package.json](frontend/package.json). + +Add a run config by creating a new entry in [package.json](frontend/package.json) similar to `"start:auth": "ng serve --configuration=dev,auth"` and adding a entry in [angular.json](frontend/angular.json) at "projects.trace-x.architect.build.configuratns" and "projects.trace-x.architect.serve.configurations". + +Add an environment by creating new file in [frontend/src/environments](frontend/src/environments) and reference it in the [package.json](frontend/package.json) build configuration. + +## Installation Instructions Local Umbrella + +### Install Umbrella + +Using the [eclipse-tractusx/tractus-x-umbrella](https://github.com/eclipse-tractusx/tractus-x-umbrella) helm chart, all traceability-foss dependencies can be installed locally. + +For detailed instructions on how to set up the umbrella chart, see the chapters "Cluster setup" and "Network setup" in the umbrella [README.md](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/main/charts/umbrella/README.md). + +Clone the [Umbrella repo](https://github.com/eclipse-tractusx/tractus-x-umbrella) (only required once): + +``` +git clone https://github.com/eclipse-tractusx/tractus-x-umbrella.git +``` + +Check out the [Trace-X umbrella integration branch](https://github.com/eclipse-tractusx/tractus-x-umbrella/tree/chore/trace-x-integration): + +``` +cd tractus-x-umbrella/ +git fetch origin +git checkout -b chore/trace-x-integration origin/chore/trace-x-integration +``` + +Build the required images for Idp and IATP mock. + +#### Powershell +```powershell +& minikube -p minikube docker-env --shell powershell | Invoke-Expression +docker build init-container/ -t init-container:testing +docker build iatp-mock/ -t tractusx/iatp-mock:testing --platform linux/amd64 +``` + +#### Bash +```bash +eval $(minikube docker-env) +docker build init-container/ -t init-container:testing +docker build iatp-mock/ -t tractusx/iatp-mock:testing --platform linux/amd64 +``` + +Install the umbrella chart using the [values-adopter-trace-x.yaml](https://github.com/eclipse-tractusx/tractus-x-umbrella/blob/chore/trace-x-integration/charts/umbrella/values-adopter-trace-x.yaml) + +``` +helm dependency update charts/tx-data-provider/ +helm dependency update charts/umbrella/ +helm install umbrella charts/umbrella/ -n umbrella --create-namespace -f charts/umbrella/values-adopter-trace-x.yaml +``` + +### Local Frontend with Umbrella Trace-X backend + +To integrate with the umbrella services, run the frontend with `start:auth:localUmbrella` + +Afterward, use one of the following users to log into the CX-Operator realm: + +| Role | Username | Password | +|------------|---------------------------|-------------------------------| +| Supervisor | tracex-supervisor@tx.test | tractusx-umbr3lla!-supervisor | +| Admin | tracex-admin@tx.test | tractusx-umbr3lla!-admin | +| User | tracex-user@tx.test | tractusx-umbr3lla!-user | -## Installation Instructions Backend +### Out of scope -- [Installation Instructions Backend](tx-backend/INSTALL.md) +- Sending/receiving of quality notifications is not supported, since it would require another tracex instance. +- IRS Asset Sync does not yet work with IRS 5.4.0. It requires a new release of IRS which provides a fix for callback url validation. diff --git a/README.md b/README.md index d8a3eda1ac..29cb407e79 100644 --- a/README.md +++ b/README.md @@ -20,24 +20,19 @@ A high level of transparency across the supplier network enables faster interven - [Introduction](#introduction) - [Vision and Mission Statement](#vision-and-mission-statement) - [Trace-X Feature list](#trace-x-feature-list) + - [Installation](#installation) - [How to contribute](#how-to-contribute) - [Releasing](#releasing) - - [Environments](#environments) - [Frontend Application](#frontend-application) - [Challenges and solutions](#challenges-and-solutions) - - [Prerequisites](#frontend-prerequisites) - - [Installation](#frontend-installation) - - [Getting started](#getting-started) - [Application authentication](#application-authentication) - [Application architecture & patterns](#application-architecture--patterns) - [User guide](#user-guide) - [Frontend Testing strategy](#frontend-testing-strategy) - - [The backend application](#the-backend-application) + - [The backend application](#backend-application) - [Prerequisites](#backend-prerequisites) - - [Installation](#backend-installation) - [Backend Testing strategy](#backend-testing-strategy) - [API documentation](#api-documentation) - - [Container Image](#container-image) - [Licenses](#licenses) - [Notice for Docker image](#notice-for-docker-image) - [Contact](#contact) @@ -78,6 +73,10 @@ Trace-X as the Open-Source solution for Parts Traceability offers the following * Quality Investigations (Company to Supplier) * Quality Alerts (Company to Customers) +## Installation + +* see [Installation guide](INSTALL.md) + ## How to contribute A detailed guide on how to contribute can be found [here](CONTRIBUTING.md). @@ -105,36 +104,6 @@ Our first approach was to use HTML canvas. But it turned out it is hard to perfo D3.js is a JavaScript library for manipulating documents based on data. D3 helps you bring data to life using HTML, SVG, and CSS. Because it uses SVGs, we knew it will perform great. And we are able to have pinpoint accuracy when it comes to user actions. -### Frontend Prerequisites - -* [Node.js 18](https://nodejs.org/en) -* [Angular CLI](https://angular.io/cli) -* [YARN](https://yarnpkg.com/) - -### Frontend Installation - -* see [Installation guide](frontend/INSTALL.md) - -### Getting started - -Clone the source locally: - -```bash -$ git clone git@github.com:eclipse-tractusx/traceability-foss.git -$ cd traceability-foss/frontend -``` - -#### Install prerequisites: - -install [node.js](https://nodejs.org/en/download/package-manager) -```bash -$ npm install --global yarn -$ npm install -g @angular/cli -$ yarn install -``` - -Start application with ``yarn start`` and navigate to ``http://localhost:4200``. - ### Application Authentication Please find [here](frontend/AUTHENTICATION.md) some important information about the app authentication. @@ -146,7 +115,7 @@ so that you end up with a well-structured app. ### User Guide -A detailed [explanation](docs/user/user-manual.adoc) of how to use the application. +A detailed [explanation](docs/src/docs/user/user-manual.adoc) of how to use the application. ### Frontend Testing Strategy See [Testing](frontend/TESTING.md). @@ -158,10 +127,6 @@ See [Testing](frontend/TESTING.md). * JDK 21 * [Docker Engine](https://docs.docker.com/engine/) -### Backend Installation - -* see [Installation guide](tx-backend/INSTALL.md) - ### Backend Testing Strategy See [Testing](tx-backend/TESTING.md). diff --git a/frontend/INSTALL.md b/frontend/INSTALL.md deleted file mode 100644 index 67c8cdc50e..0000000000 --- a/frontend/INSTALL.md +++ /dev/null @@ -1,145 +0,0 @@ -# Environment variables - -Support environment variables are: - -```javascript -const ENV_VARS_MAPPING = { - CATENAX_PORTAL_KEYCLOAK_URL: 'keycloakUrl', - CATENAX_PORTAL_CLIENT_ID: 'clientId', - CATENAX_PORTAL_REALM: 'realm', - CATENAX_PORTAL_API_URL: 'apiUrl', - CATENAX_PORTAL_BASE_URL: 'baseUrl', - CATENAX_PORTAL_BACKEND_DOMAIN, - CATENAX_PORTAL_URL: 'portalUrl', - BPN: 'bpn' -}; -``` - -`CATENAX_PORTAL_KEYCLOAK_URL` -This variable is used to set up and use keycloak - -`CATENAX_PORTAL_CLIENT_ID` -This variable is used to identify the client on keycloak - -`CATENAX_PORTAL_REALM` -This variable is used to define the realm for keycloak. Default realm for the portal is "CX-Central". - -`CATENAX_PORTAL_API_URL` -This variable points to the desired api - -`CATENAX_PORTAL_BASE_URL` -This variable is used to set the base path of the application. (Should be set if application runs as a subtopic) - -`CATENAX_PORTAL_BACKEND_DOMAIN` -This variable is needed for security, to be more explicit, for the security headers of a request. -The domain of the corresponding backend should be used here. -An example value could be: `catena-x.net` - -`CATENAX_PORTAL_URL` -This variable is optional and points to the CX Portal instance - -`BPN` -This variable is the bpn of the application owner - -# Helm deployment - -## Configuration of values.yaml - -To run a helm chart you first need to specify a values file with instructions on how to run your helm file. -Here is an example how you could structure this file for this frontend helm chart. - -`your-values.yaml` - -```yaml -image: - tag: $APP_REVISION - ENVIRONMENT_VAR_1: 'VALUE' - ENVIRONMENT_VAR_2: 'VALUE' - ... - -ingress: - enabled: true - className: "nginx" - annotations: - cert-manager.io/cluster-issuer: letsencrypt-prod - hosts: - - host: "${FE_HOST_URL}" - paths: - - path: / - pathType: Prefix - tls: - - hosts: - - "${FE_HOST_URL}" - secretName: "${FE_HOST_URL}-tls" - -``` - -## Helm installation - -Add the Trace-X frontend Helm repository: - -```sh -$ helm repo add traceability-foss-frontend https://github.com/eclipse-tractusx/traceability-foss -``` - -Then install the Helm chart into your cluster: - -```sh -$ helm install -f your-values.yaml traceability-foss-frontend traceability-foss-frontend/traceability-foss-frontend -``` - -### Deployment using ArgoCD - -Create a new Helm chart and use Trace-X as a dependency. - -```yaml -dependencies: - - name: traceability-foss-frontend - alias: frontend - version: x.x.x - repository: 'https://github.com/eclipse-tractusx/traceability-foss/' -``` - -Then provide your configuration as the values.yaml of that chart. - -Create a new application in ArgoCD and point it to your repository / Helm chart folder. - -# Docker deployment - -## How to build the application - -The angular app is built into Docker containers and exposed through NGINX - -It is important to specify the type of configuration profile, previously defined in the angular JSON file, so it can -build the application correctly. - -## How to run the docker image - -When running the build docker image you are able to pass through multiple environment variables to configure the FE. - -### Example command: - -```shell -$ docker run -d -p 4200:8080 -e CATENAX_PORTAL_BASE_URL=/example -e CATENAX_PORTAL_BACKEND_DOMAIN=catena-x.net ${dockerImage} -``` - -#### `Docker run` - -With the `docker run [OPTIONS]` an operator can add to or override the image defaults set by a developer. And, additionally, operators can override nearly all the defaults set by the Docker runtime itself. The operator’s ability to override image and Docker runtime defaults is why run has more options than any other `docker` command. - -#### `-d` - -To start a container in detached mode, you use `-d=true` or just `-d` option. By design, containers started in detached mode exit when the root process used to run the container exits - -#### `-p 4200:8080` - -To expose a container’s internal port, an operator can start the container with the `-P` or `-p` flag. The exposed port is accessible on the host and the ports are available to any client that can reach the host. - -#### `-e ENV_VAR=VAR_VALUE` - -The operator can set any environment variable in the container by using one or more `-e` flags, even overriding already defined flags by the developer with a Dockerfile `ENV`. - -#### `${dockerImage}` - -While not strictly a means of identifying a container, you can specify a version of an image you’d like to run the container with by adding `image[:tag]` to the command. For example, `docker run 002b3c518f5852f7fd5e9e46c0ea1ab4d76b697d33d5022af1a69e1a909645ea`. -Images can be pulled [here](https://github.com/eclipse-tractusx/traceability-foss-frontend/pkgs/container/traceability-foss-frontend). diff --git a/frontend/angular.json b/frontend/angular.json index 503c95471c..90269ebbda 100644 --- a/frontend/angular.json +++ b/frontend/angular.json @@ -137,6 +137,14 @@ } ] }, + "localUmbrella": { + "fileReplacements": [ + { + "replace": "src/environments/environment.ts", + "with": "src/environments/environment.localUmbrella.ts" + } + ] + }, "production": { "fileReplacements": [ { @@ -212,6 +220,9 @@ }, "debugProd": { "browserTarget": "trace-x:build:dev,debugProd" + }, + "localUmbrella": { + "browserTarget": "trace-x:build:dev,localUmbrella" } } }, diff --git a/frontend/package.json b/frontend/package.json index aad6f8d64a..134f71837d 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -22,6 +22,7 @@ "start:auth:mock": "ng serve --configuration=authMock", "start:auth:local": "ng serve --configuration=authLocal", "start:auth:localBe": "ng serve --configuration=localBackend", + "start:auth:localUmbrella": "ng serve --configuration=localUmbrella", "start:noAuth:localBe": "ng serve --configuration=localBackendNoAuth", "env:mock": "docker-compose up", "test": "ng test", diff --git a/tx-backend/INSTALL.md b/tx-backend/INSTALL.md deleted file mode 100644 index d7ed01d171..0000000000 --- a/tx-backend/INSTALL.md +++ /dev/null @@ -1,93 +0,0 @@ -![Trace-X](../docs/trace-x-logo.svg) -# Product Traceability FOSS Backend Installation guide - -## Clone the source locally: - -```sh -$ git clone https://github.com/eclipse-tractusx/traceability-foss.git -$ cd traceability-foss -``` -Please note: Local deployment of the app is not supported. - -For deployment please find our helm chart github actions here: [helm-upgrade.yaml](../.github/workflows/helm-upgrade.yaml) and [helm-test-backwards-compatability.yaml](../.github/workflows/helm-test-backwards-compatability.yaml). Within this actions the full application is configured to start up. - -## OAuth2 configuration -Product Traceability FOSS Backend relies on properly configured OAuth2 instance. In order to work, it must be configured with proper realm, clients and roles. -Users should have one of the following roles assigned: -* User -* Admin -* Supervisor - -## Helm secrets configuration -Product Traceability FOSS Backend ships with helm charts and utilize [helm dependency](https://helm.sh/docs/helm/helm_dependency/) functionality for 3rd party components. - -### OAuth2 Properties -In order to deploy the service following secrets needs to be provided for specific environment [project helm environment specific files](../charts/traceability-foss/charts/backend/values.yaml): - -* `oauth2.clientId` - OAuth2 client registration id credentials -* `oauth2.clientSecret` - OAuth2 client registration secret credentials - -### Database -To start a database for local development, go to the docker directory and run. - -```sh -docker compose up -d -``` - -Add the database configuration to your [application-local.yml](https://github.com/eclipse-tractusx/traceability-foss/blob/main/backend/src/main/ressouces/application-local.yml) - -```yaml -spring: - datasource: - url: jdbc:postgresql://localhost:5432/trace - username: postgres - password: docker - flyway: - clean-on-validation-error: false -``` -Database scripts are executed with Flyway. Put the scripts at [migration](src/main/resources/db/migration) - -* `postgresql.secret.initUserDbSql` - database initialization script, contains username and password for databases used by the service. -Please note that the final script should be encoded using Base64 encoding and then added to a secret. Sample command: -```sh -echo -n 'CREATE ROLE trace WITH LOGIN PASSWORD 'yourPassword';\nCREATE DATABASE trace;\nGRANT ALL PRIVILEGES ON DATABASE trace TO trace;' | base64 -``` - -* `postgresql.auth.postgresPassword` - PostgreSQL master password -* `datasource.password` - `trace` database password configured in `initUserDbSql` script -* `pgAdmin4.env.password` - pgAdmin4 master password - - -## Helm installation -Add the Trace-X Backend Helm repository: - -```sh -$ helm repo add traceability-foss-backend https://eclipse-tractusx.github.io/traceability-foss-backend -``` -Then install the Helm chart into your cluster: - -```sh -$ helm install -f your-values.yaml traceability-foss backend/traceability-foss-backend -``` - -## Deployment using ArgoCD - -Create a new Helm chart and use Trace-X as a dependency. - -```yaml -dependencies: -- name: traceability-foss-backend - alias: backend - version: x.x.x - repository: "https://eclipse-tractusx.github.io/traceability-foss-backend/" -``` - -Then provide your configuration as the values.yaml of that chart. - -Create a new application in ArgoCD and point it to your repository / Helm chart folder. - -## API sample endpoints -* Swagger UI: `http://localhost:8080/api/swagger-ui/index.html` -* API docs: `http://localhost:8080/api/v3/api-docs` -* Application health liveness endpoint: `http://localhost:8081/actuator/health/liveness` -* Application health readiness endpoint: `http://localhost:8081/actuator/health/readiness`