From 75b6548322b87732579490fdd75d783a6042a8d1 Mon Sep 17 00:00:00 2001 From: jhartmann Date: Tue, 23 Jul 2024 15:16:33 +0200 Subject: [PATCH] chore(docs):[#511] cleanup and unify installation instructions in INSTALL.md --- INSTALL.md | 36 +++++++++-- README.md | 12 ++-- frontend/INSTALL.md | 145 ------------------------------------------ tx-backend/INSTALL.md | 93 --------------------------- 4 files changed, 34 insertions(+), 252 deletions(-) delete mode 100644 frontend/INSTALL.md delete mode 100644 tx-backend/INSTALL.md diff --git a/INSTALL.md b/INSTALL.md index 09c77c4ea4..36f2fb29b7 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,12 +1,38 @@ # 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/ +``` + +``` +# 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) +To run the frontend locally with a already existing backend, use the run configs in [frontend/package.json](frontend/package.json). -## Installation Instructions Backend +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". -- [Installation Instructions Backend](tx-backend/INSTALL.md) +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 @@ -56,8 +82,6 @@ helm install umbrella charts/umbrella/ -n umbrella --create-namespace -f charts/ ### Local Frontend with Umbrella Trace-X backend -To use the frontend locally, follow the [installation instructions](frontend/INSTALL.md). - 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: @@ -71,4 +95,4 @@ Afterward, use one of the following users to log into the CX-Operator realm: ### Out of scope - Sending notifications is currently not supported -- IRS Asset Sync requires a new release of IRS which provides a fix for callback url validation +- 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..03a57e5b7c 100644 --- a/README.md +++ b/README.md @@ -78,6 +78,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). @@ -111,10 +115,6 @@ Because it uses SVGs, we knew it will perform great. And we are able to have pin * [Angular CLI](https://angular.io/cli) * [YARN](https://yarnpkg.com/) -### Frontend Installation - -* see [Installation guide](frontend/INSTALL.md) - ### Getting started Clone the source locally: @@ -158,10 +158,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/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`