docs: align portal iam doc structure with trg 1 (#207)

#187

.github/pull_request_template.md

@@ -14,7 +14,7 @@ Link to Github issue.
 
 Please delete options that are not relevant.
 
-- [ ] I have followed the [contributing guidelines](https://github.com/eclipse-tractusx/portal-iam/blob/main/docs/technical%20documentation/14.%20How%20to%20contribute.md)
+- [ ] I have followed the [contributing guidelines](https://github.com/eclipse-tractusx/portal-iam/blob/main/docs/admin/dev-process/How%20to%20contribute.md)
 - [ ] I have added copyright and license headers, footers (for .md files) or files (for images) 
 - [ ] I have performed a self-review of my changes
 - [ ] I have successfully tested my changes

.sonarcloud.properties

@@ -1 +1,2 @@
-sonar.cpd.exclusions = import/keycloak-themes/**/*.*
+sonar.cpd.exclusions = import/keycloak-themes/**/*.*
+sonar.exclusions = docs/**/*.yaml

CHANGELOG.md

@@ -87,7 +87,7 @@ New features, fixed bugs, known defects and other noteworthy changes to each rel
 The following issues were discovered:
 
 * 403 error when accessing the Partner Network in the Portal Frontend [#132](https://github.com/eclipse-tractusx/portal-iam/pull/132)
-* Refresh token rotation causes page reload in frontend apps when using multiple tabs, see [User Token Lifespan](docs/consultation/workshop-20231005.md#user-token-lifespan)
+* Refresh token rotation causes page reload in frontend apps when using multiple tabs, see [User Token Lifespan](docs/consultation/workshops/workshop-20231005.md#user-token-lifespan)
 * Custom login themes break when inserting HTML/CSS/JavaScript code in the IdP display name
 
 ## 3.0.0
@@ -478,7 +478,7 @@ sharedidp:
 
 The following issues were recently discovered:
 
-* Refresh token rotation causes page reload in frontend apps when using multiple tabs, see [User Token Lifespan](docs/consultation/workshop-20231005.md#user-token-lifespan)
+* Refresh token rotation causes page reload in frontend apps when using multiple tabs, see [User Token Lifespan](docs/consultation/workshops/workshop-20231005.md#user-token-lifespan)
 * Custom login themes break when inserting HTML/CSS/JavaScript code in the IdP display name
 
 ## 1.2.0

CONTRIBUTING.md

@@ -77,7 +77,7 @@ https://www.eclipse.org/projects/handbook/#resources-commit
 
 ## How To Contribute
 
-For more practical information, please refer to [Contribution details](/docs/technical%20documentation/14.%20How%20to%20contribute.md).
+For more practical information, please refer to [Contribution details](/docs/admin/dev-process/How%20to%20contribute.md).
 
 ## Contact
 

README.md

@@ -25,7 +25,7 @@ For further information please refer to the chart specific README files, availab
 
 ## Known Issues and Limitations
 
-See [Known Knowns](/docs/technical%20documentation/16.%20Known-Knowns.md).
+See [Known Knowns](/docs/admin/known-knowns/Known-Knowns.md).
 
 ## Notice for Docker images
 

charts/centralidp/README.md

@@ -4,7 +4,7 @@
 
 This helm chart installs the Helm chart for Central Keycloak Instance.
 
-For further information please refer to the [technical documentation](../../docs/technical%20documentation).
+For further information please refer to the [technical documentation](/docs/admin/technical-documentation/).
 
 The referenced container images are for demonstration purposes only.
 
@@ -144,14 +144,14 @@ No specific upgrade notes.
 
 This major changes from the Keycloak version from 16.1.1 to version 22.0.3.
 
-Please have a look at the [CHANGELOG](../../CHANGELOG.md#200) for a more detailed description.
+Please have a look at the [CHANGELOG](/CHANGELOG.md#200) for a more detailed description.
 
 We also recommend checking out the [Keycloak Upgrading Guide](https://www.keycloak.org/docs/latest/upgrading/index.html).
 
 To be explicitly mentioned: this major adds the production mode with default value false and the reverse proxy mode with default value passthrough.
 Please check the description of those parameters and decide if they're suitable for you.
 
-Please also refer to [Upgrade Details](../../docs/technical%20documentation/12.%20Upgrade%20Details.md#v200).
+Please also refer to [Upgrade Details](/docs/admin/technical-documentation/12.%20Upgrade%20Details.md#v200).
 
 #### Upgrade approach
 

charts/centralidp/README.md.gotmpl

@@ -4,7 +4,7 @@
 
 This helm chart installs the {{ template "chart.description" . }}.
 
-For further information please refer to the [technical documentation](../../docs/technical%20documentation).
+For further information please refer to the [technical documentation](/docs/admin/technical-documentation).
 
 The referenced container images are for demonstration purposes only.
 
@@ -85,7 +85,7 @@ We also recommend checking out the [Keycloak Upgrading Guide](https://www.keyclo
 To be explicitly mentioned: this major adds the production mode with default value false and the reverse proxy mode with default value passthrough.
 Please check the description of those parameters and decide if they're suitable for you.
 
-Please also refer to [Upgrade Details](../../docs/technical%20documentation/12.%20Upgrade%20Details.md#v200).
+Please also refer to [Upgrade Details](/docs/admin/technical-documentation/12.%20Upgrade%20Details.md#v200).
 
 #### Upgrade approach
 

charts/sharedidp/README.md

@@ -4,7 +4,7 @@
 
 This helm chart installs the Helm chart for Shared Keycloak Instance.
 
-For further information please refer to the [technical documentation](../../docs/technical%20documentation).
+For further information please refer to the [technical documentation](/docs/admin/technical-documentation/).
 
 The referenced container images are for demonstration purposes only.
 

charts/sharedidp/README.md.gotmpl

@@ -4,7 +4,7 @@
 
 This helm chart installs the {{ template "chart.description" . }}.
 
-For further information please refer to the [technical documentation](../../docs/technical%20documentation).
+For further information please refer to the [technical documentation](/docs/admin/technical-documentation).
 
 The referenced container images are for demonstration purposes only.
 

docs/README.md

@@ -0,0 +1,78 @@
+# Portal IAM Documentation
+
+This documentation provides a comprehensive overview of the **Portal IAM** system, covering various aspects such as architecture, user management, security, and deployment instructions.
+
+## 1. Introduction
+
+This repository contains the documentation for the **Portal IAM** platform, an Identity and Access Management (IAM) solution. The documentation is organized into the following sections to help users, administrators, and developers understand and work with the system effectively.
+
+## 2. Documentation Structure
+
+### [Admin Documentation](./admin/)
+
+The `admin` folder includes documentation for system administrators:
+
+### 1. [Technical Documentation](./admin/technical-documentation/)
+
+The `technical-documentation` folder includes the following guides and manuals:
+
+- [External Identity Provider](./admin/technical-documentation/00.%20External%20Identity%20Provider.md): Guide on integrating external identity providers.
+- [Introduction](./admin/technical-documentation/01.%20Introduction.md): Overview of Portal IAM.
+- [Generic Setup](./admin/technical-documentation/02.%20Generic%20Setup.md): Instructions on the basic setup.
+- [User Management](./admin/technical-documentation/04.%20User%20Management.md): How to manage users within the Portal IAM.
+- [Roles & Rights Concept](./admin/technical-documentation/06.%20Roles%20&%20Rights%20Concept.md): Overview of role-based access control.
+- [Password Policy](./admin/technical-documentation/07.%20Password%20Policy.md): Password requirements and guidelines.
+- [Email Configuration](./admin/technical-documentation/08.%20Email%20Configuration.md): Email server and notification configuration.
+- [Event Logging](./admin/technical-documentation/09.%20Event%20Logging.md): How events and logs are managed.
+- [Generic Security](./admin/technical-documentation/10.%20Generic%20Security.md): General security guidelines.
+- [FAQ](./admin/technical-documentation/11.%20FAQ.md): Frequently asked questions.
+- [Upgrade Details](./admin/technical-documentation/12.%20Upgrade%20Details.md): Information on system upgrades.
+- [Operational Notes](./admin/technical-documentation/13.%20Operational%20Notes.md): Additional operational considerations.
+
+### 2. [Developer Process](./admin/dev-process/)
+
+- [Dev Flow](./admin/dev-process/Dev%20Flow.md): This document outlines the development flow, using a git-based diagram to show the process of feature development, bug fixes, and release candidates. 
+- [How to Contribute](./admin/dev-process/How%20to%20contribute.md): Steps for contributing to the project.
+
+### 3. [Release Process](./admin/release-process/)
+
+- [Release Process](./admin/release-process/Release%20Process.md) :  This document explains the release process, detailing steps from creating a release branch, updating versions, and generating changelogs to merging release candidates into the main branch. It follows semantic versioning practices and provides links to automated workflows used in the release cycle.
+
+### 4. [Known-Knowns](./admin/known-knowns/)
+
+The `known-knowns` folder highlights known limitations, issues, or considerations regarding the Portal IAM:
+
+- [Known-Knowns](./admin/known-knowns/Known-Knowns.md): A list of known issues and solutions.
+
+### [Consultation Documentation](./consultation/)
+
+### 1. [charts](./consultation/charts/) and [environments](./consultation/environments/)
+
+The `charts` and `environments` folder contain an **example** helm chart and configuration for a potential deployment improvement discussed during workshops.
+
+- [Portal IAM Helm Chart](./consultation/portal-iam-helm-chart.md): instructions on using this **example** helm chart.
+
+### 2. [Workshops](./consultation/workshops/)
+
+The `workshops` folder includes minutes and topics for two workshops:
+
+- [Workshop 20230927](./consultation/workshops/workshop-20230927.md): topics covered during the session of September 27, 2023 workshop.
+- [Workshop 20231005](./consultation/workshops/workshop-20231005.md): topics covered during the session of October 5, 2023 workshop.
+
+
+### 3. [Consultation Document](./consultation/consultation.md)
+
+- Consultation notes and decisions.
+
+
+### [Assets](./static/)
+
+The `static` folder contains assets used in the documentation.
+
+## NOTICE
+
+This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).
+
+- SPDX-License-Identifier: Apache-2.0
+- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
+- Source URL: https://github.com/eclipse-tractusx/portal-iam

docs/technical documentation/14. How to contribute.md → docs/admin/dev-process/How to contribute.md

@@ -98,7 +98,7 @@ What was changed, why was it changed (e.g. which issue was fixed or which requir
 
 ### Additional information
 
-Please refer to the [Development Flow](./17.%20Dev%20Flow.md).
+Please refer to the [Development Flow](./Dev%20Flow.md).
 
 ## NOTICE
 

docs/technical documentation/16. Known-Knowns.md → docs/admin/known-knowns/Known-Knowns.md

@@ -1,6 +1,6 @@
 # Known Issues and Limitations
 
-- Refresh token rotation causes page reload in frontend apps when using multiple tabs, see [User Token Lifespan](../consultation/workshop-20231005.md#user-token-lifespan)
+- Refresh token rotation causes page reload in frontend apps when using multiple tabs, see [User Token Lifespan](/docs/consultation/workshops/workshop-20231005.md#user-token-lifespan)
 - Custom login themes break when inserting HTML/CSS/JavaScript code in the IdP display name
 
 ## NOTICE

docs/technical documentation/18. Release Process.md → docs/admin/release-process/Release Process.md

@@ -11,7 +11,7 @@ The release process for a new version can roughly be divided into the following
   - [RC: provide successive rc branch and change base of open PRs](#rc-provide-successive-rc-branch-and-change-base-of-open-prs)
   - [NOTICE](#notice)
 
-The process builds on the [Development Flow](./17.%20Dev%20Flow.md) which, usually, takes place within forks and leads to merged pull requests in the repositories of the eclipse-tractusx organization.
+The process builds on the [Development Flow](../dev-process/Dev%20Flow.md) which, usually, takes place within forks and leads to merged pull requests in the repositories of the eclipse-tractusx organization.
 
 For assigning and incrementing **version** numbers [Semantic Versioning](https://semver.org) is followed.
 
@@ -24,15 +24,15 @@ On the release branch the following steps are executed:
 
 Bump the chart and app version in the `Chart.yaml` files.
 
-- [centralidp/Chart.yaml](../../charts/centralidp/Chart.yaml)
-- [sharedidp/Chart.yaml](../../charts/sharedidp/Chart.yaml)
+- [centralidp/Chart.yaml](/charts/centralidp/Chart.yaml)
+- [sharedidp/Chart.yaml](/charts/sharedidp/Chart.yaml)
 
 And bump the version of the images for the init container and realm seeding job in the `values.yaml` files:
 
-- [centralidp/values.yaml](../../charts/centralidp/values.yaml)
-- [sharedidp/values.yaml](../../charts/sharedidp/values.yaml)
+- [centralidp/values.yaml](/charts/centralidp/values.yaml)
+- [sharedidp/values.yaml](/charts/sharedidp/values.yaml)
 
-_environment relevant: Update the version of the targetRevision tag in the [argocd-app-templates](../../environments/argocd-app-templates/), used for hosted environments._
+_environment relevant: Update the version of the targetRevision tag in the [argocd-app-templates](/environments/argocd-app-templates/), used for hosted environments._
 
 Example for commit message:
 
@@ -53,7 +53,7 @@ _build: update readme for vx.x.x_
 ## Update CHANGELOG.md
 
 The changelog file tracks all notable changes since the last released version.
-Once a new version is ready to be released, the changelog can get updated via an automatically created pull request using the [release-please workflow](../../.github/workflows/release-please.yml) which can be triggered manually or by pushing a _changelog/v*.*.*_ branch.
+Once a new version is ready to be released, the changelog can get updated via an automatically created pull request using the [release-please workflow](/.github/workflows/release-please.yml) which can be triggered manually or by pushing a _changelog/v*.*.*_ branch.
 
 Please see:
 
@@ -70,11 +70,11 @@ Example for PR titles:
 
 _build(1.2.0): merge release into main_
 
-> Be aware that the merge into main triggers the workflow with the [helm chart releaser action](../../.github/workflows/release.yaml).
+> Be aware that the merge into main triggers the workflow with the [helm chart releaser action](/.github/workflows/release.yaml).
 >
 > The workflow creates a 'centralidp-x.x.x' and 'sharedidp-x.x.x' tags and according releases. The release contains the new chart.
 >
-> This workflow also pushes the version tag that triggers the [release workflow](../../.github/workflows/release.yaml) which creates the versioned docker image/s.
+> This workflow also pushes the version tag that triggers the [release workflow](/.github/workflows/release.yaml) which creates the versioned docker image/s.
 
 _environment relevant: The 'vx.x.x' tag is used to install (with the convenience of the argocd-app-templates) or upgrade the version via AgroCD on the hosted K8s clusters._
 

docs/technical documentation/11. FAQ.md → docs/admin/technical-documentation/11. FAQ.md

@@ -79,11 +79,11 @@ To transform the created "role" to an actual role, since currently its a single
 
 3. Update keycloak base image
 
-The [CX-Central realm file](../../import/realm-config/generic/catenax-central/CX-Central-realm.json) needs to be updated with role changes (export from Keycloak) to provide the configuration in the init container for the realm import and seeding.
+The [CX-Central realm file](/import/realm-config/generic/catenax-central/CX-Central-realm.json) needs to be updated with role changes (export from Keycloak) to provide the configuration in the init container for the realm import and seeding.
 
 4. Update documentation
 
-- [Roles&Rights Matrix](/docs/technical%20documentation/06.%20Roles%20&%20Rights%20Concept.md#253-portal-application)
+- [Roles&Rights Matrix](/docs/admin/technical-documentation/06.%20Roles%20&%20Rights%20Concept.md#253-portal-application)
 
 ### App Role(s)
 
@@ -130,13 +130,14 @@ For the scenario of sql, the relevant sql can get found below:
 
 3. Update Keycloak base image
 
-The [CX-Central realm file](../../import/realm-config/generic/catenax-central/CX-Central-realm.json) needs to be updated with role changes (export from Keycloak) to provide the configuration in the init container for the realm import and seeding.
+The [CX-Central realm file](/import/realm-config/generic/catenax-central/CX-Central-realm.json) needs to be updated with role changes (export from Keycloak) to provide the configuration in the init container for the realm import and seeding.
 
 4. Update documentation
 
-- [Roles&Rights Matrix](/docs/technical%20documentation/06.%20Roles%20&%20Rights%20Concept.md#253b-technical-user-accounts)
+- [Roles&Rights Matrix](/docs/admin/technical-documentation/06.%20Roles%20&%20Rights%20Concept.md#253b-technical-user-accounts)
 
-- [Technical User Creation - End User documentation]([/docs/technical%20documentation/04%20User%20Management.md](https://github.com/eclipse-tractusx/portal-assets/blob/main/docs/03.%20User%20Management/03.%20Technical%20User/02.%20Create%20Technical%20User.md#available-technical-user-roles))
+- [Technical User Creation - End User documentation](https://github.com/eclipse-tractusx/portal-assets/blob/main/docs/user/03.%20User%20Management/03.%20Technical%20User/02.%20Create%20Technical%20User.md#available-technical-user-roles)
+- [User Management](/docs/admin/technical-documentation/04.%20User%20Management.md)
 
 ## What is the difference between roles & permission
 

docs/consultation/portal-iam-helm-chart.md

@@ -31,7 +31,7 @@ there is a [hook](./charts/portal-iam/templates/hooks/check-variable.yaml) creat
 
 The Helm Chart can be extended to add more detailed objects, but it was not part of this Proof of Concept.
 
-The chart is implemented [here](../consultation/charts/).
+The chart is implemented [here](./charts/).
 
 ### How to use - Example of usage
 

docs/consultation/workshops/README.md

@@ -0,0 +1,23 @@
+# Workshop Documentation
+
+This repository contains resources and materials related to the workshops conducted.
+
+## Workshops Overview
+
+This folder includes documentation and files for the following workshops:
+
+1. **IAM Helm Chart Workshop**
+   - Date: September 27, 2023
+   - **Documentation Link**: [IAM Helm Chart Workshop Documentation](workshop-20230927.md)
+
+2. **User Token Lifespan Workshop**
+   - Date: October 5, 2023
+   - **Documentation Link**: [User Token Lifespan Workshop Documentation](workshop-20231005.md)
+
+## NOTICE
+
+This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).
+
+- SPDX-License-Identifier: Apache-2.0
+- SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation
+- Source URL: https://github.com/eclipse-tractusx/portal-iam

docs/consultation/workshop-20231005.md → docs/consultation/workshops/workshop-20231005.md

@@ -1,4 +1,4 @@
-# Portal IAM - Workshop 5th Octuber, 2023
+# Portal IAM - Workshop 5th October, 2023
 
 ## User Token Lifespan
 
@@ -61,7 +61,7 @@ Again, there are no-recommended values (only default ones). The final values wil
 
 ## One IAM Helm chart: POC
 
-This topic is described in [this file](portal-iam-helm-chart.md).
+This topic is described in [this file](../portal-iam-helm-chart.md).
 
 ## Hands on Blue/Green Deployment from v16.1.1 to v22.0.3 with prepared instances