wso2 · Suvink · Jan 28, 2025 · Jan 28, 2025 · Jan 28, 2025 · Jan 28, 2025
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -1,8 +1,8 @@
-name: ci 
+name: ci
 on:
   push:
     branches:
-     - dev
+      - PE
 permissions:
   contents: write
 jobs:
@@ -16,8 +16,8 @@ jobs:
           git config --global user.name "Choreo CI Agent"
       - uses: actions/setup-python@v5
         with:
-          python-version: 3.x
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+          python-version: 3.12
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
       - uses: actions/cache@v4
         with:
           key: mkdocs-material-${{ env.cache_id }}
@@ -44,6 +44,34 @@ jobs:
           pip install mkdocs-glightbox==0.3.4
           pip install mkdocs-include-markdown-plugin==1.0.0
           pip install mkdocs-open-in-new-tab==1.0.3
-      - run: mkdocs gh-deploy --config-file en/mkdocs.yml --force
+      - name: Build site developer
+        run: mkdocs build --config-file en/developer-docs/mkdocs.yml
+      - name: Build site platform-engineer
+        run: mkdocs build --config-file en/pe-docs/mkdocs.yml 
+      - name: Create/fetch gh-pages-v2
+        run: |
+          if git ls-remote --heads origin gh-pages-v2 | grep -q gh-pages-v2; then
+            git fetch origin gh-pages-v2
+            git checkout gh-pages-v2
+          else
+            git switch --orphan gh-pages-v2
+          fi
+      - name: Create gh-pages-v2 branch developer subdirectory
+        run: |
+          rm -rf choreo/docs/developer  # Clear existing directory if needed
+          mkdir -p choreo/docs/developer
+          cp -r en/developer-docs/site/developer/* choreo/docs/developer/ 
+      - name: Create gh-pages-v2 branch platform-engineer subdirectory
+        run: |
+          rm -rf choreo/docs/platform-engineer  # Clear existing directory if needed
+          mkdir -p choreo/docs/platform-engineer
+          cp -r en/pe-docs/site/platform-engineer/* choreo/docs/platform-engineer/
+      - name: Push Changes to gh-pages-v2
+        run: |
+          git add choreo/docs/developer/
+          git commit -m "Update developer directory"
+          git add choreo/docs/platform-engineer/
+          git commit -m "Deploy to platform-engineer directory"
+          git push origin gh-pages-v2 --force
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}                 
diff --git a/README.md b/README.md
@@ -20,127 +20,66 @@ Before you contribute, read the following guidelines to understand how you can s
 
 We look forward to your contributions.
 
-## Run the project locally with Devcontainers
 
-This repository supports the VS Code dev containers feature, which allows you to create a consistent and isolated development environment inside a Docker container. To use this feature, you need to have the following pre requisites:
-
-- VS Code
-- Docker installed on your system
-- [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension for VS Code
-
-Once you have these installed, you can open the repository in VS Code and follow these steps:
-
-- Press F1 and select the Remote-Containers: Open Folder in Container... command.
-- Select the repository folder and wait for the container to build and start.
-- You can now edit, run, debug, and test your code inside the container.
-
-For more information on how to use VS Code dev containers, please refer to the official documentation: https://code.visualstudio.com/docs/remote/containers
-
-### Run MkDocs server locally
-
-To start the server and view the site on your local server, run the following command:
-
-    ```shell
-    $ mkdocs serve
-    ```
-
-    > **NOTE:**
-    >
-    > If you want to make changes and see them on the fly, run the following command to start the server and view the site on your local server:
-    > 1. Navigate to the `mkdocs.yml` file.
-    > 2. Set the following configuration:
-    >     ```
-    >     #Breaks build if there's a warning
-    >     strict: false
-    >     ```
-    > 3. To start the server, make it load the changes, and display the changes faster, run the following command:
-    >
-    >    `mkdocs serve --dirtyreload`
-
-2. To view the Choreo documentation site locally, open the following URL on a new browser window:
+## Run the project locally with MkDocs
 
-    [http://localhost:8000/](http://localhost:8000/)
+### Prerequisites
+- Python 3
+     - Setup guides: [MacOS](https://docs.python.org/3/using/mac.html), [Windows](https://docs.python.org/3/using/windows.html), [Linux](https://wiki.python.org/moin/BeginnersGuide/Download#:~:text=using/mac.html-,Linux,-On%20most%20Linux)
+-  Pip3
+      - Once you install Python, Pip is most likely to be installed by default. If not, follow the [Pip installation guide](https://pip.pypa.io/en/stable/installation/) for instructions.
 
+### Setting up the project
 
-## Run the project locally
-
-### Step 1 - Install Python
-
-#### MacOS
-If you are using macOS, you probably already have a version of Python installed on your machine. Run the following command to verify:
-
+#### Step 1: Clone the project
 ```shell
-$ python --version
-Python 2.7.2
+git clone https://github.com/[git-username]/docs-choreo-dev.git
 ```
 
-If your version of Python is 2.x.x, you need to install Python3. Follow the instructions in [this guide](https://docs.python-guide.org/starting/install3/osx/) to install Python3.
-
-Once you are done, you should see two versions of Python on your machine; python2 and python3.
-
-#### Ubuntu and other versions of Debian Linux
-
-Python 3 is pre-installed in these versions, which you can verify using the `python3 -V` command. Run `sudo apt install -y python3-pip` to install `pip` and verify using `pip3 -V`.
-
-### Step 2 - Install pip
->
-> **INFO**
->
-> If pip is not already installed on your machine, run `get-pip.py` to install pip. Then run the following command to install it:
-> ```shell
-> $ python get-pip.py
-> ```
->
-
-Pip is most likely installed by default. However, you may need to upgrade pip to the latest version:
-
+#### Step 2: Create a Virtual Environment
+- Navigate to the project's root where the `requirements.txt` file is located at.
 ```shell
-$ pip install --upgrade pip
+cd docs-choreo-dev/en
+```
+- Execute the following commands to create a virtual environment and activate it.
+```python
+python3 -m venv dev-env
+source dev-env/bin/activate
 ```
 
-### Step 3 - Install the pip packages
-
-To clone the Choreo documentation GitHub repository and run the site on your local server, follow these steps:
-
-1. Fork `https://github.com/wso2/docs-choreo-dev`.
-2. Navigate to the locatiion where you want to clone the repo and clone the forked repository.
-
-    ```shell
-    $ git clone https://github.com/[git-username]/docs-choreo-dev.git
-    ```
-
-3. Navigate to the directory where you cloned the repo.
-
-    For example:
-
-    ```shell
-    $ cd docs-choreo-dev/<Language-folder>/
-    ```
-
-    ```shell
-    $ cd docs-choreo-dev/en/
-    ```
-
-4. Install the required pip packages.
+#### Step 3: Install dependancies
+Execute the following command from the directory where the `requirements.txt` file is located at.
+```python
+pip3 install -r requirements.txt   
+``` 
 
-    This step installs MkDocs together with the required theme, extensions, and plugins.
+#### Step 4: Navigate to the project directory
+Choreo documentation provides two perspectives: Developer and Platform Engineer. Each perspective is hosted on a separate server. To access the desired perspective, navigate to the corresponding project root.
+- For Developer perspective:
+```shell
+cd en/developer-docs
+```
+- For Platform Engineer perspective:
+```shell
+cd en/pe-docs
+```
 
-    - If you are using Python2, run the following command:
+#### Step 5: Start the development server
+```shell
+mkdocs serve --dirtyreload
+```
+Choreo docs will be available locally on [http://localhost:8000/](http://localhost:8000/)
 
-      ```shell
-      $ pip install -r requirements.txt
-      ```
+### Proof Reading Documentation
 
-    - If you are using Python3, run the following command:
+Prerequisites:
+- [MdSpell](https://github.com/mtuchowski/mdspell)
 
-      ```shell
-      $ pip3 install -r requirements.txt
-      ```
-### Step 4 - Build Project
-1. To build the code navigate to the en folder and run the following command:
 
+#### Steps
+1. Navigate to the `en` directory and run the following command:
     ```shell
-    $ ./serve.sh
+    ./serve.sh
     ```
 This script will check spellings and incorrect links. 
 
@@ -152,40 +91,23 @@ Incorrect spellings will be highlighted in red. You can take one of the followin
 - Proceed with "Add to dictionary - case sensitive" to add the word to the dictionary for all files, but only match the exact case used. For instance, with the word "Microsoft," the word "microsoft" would not be considered correct.
 
 All exclusions will be stored in a .spelling file in the directory from which you run the command.
-
 Choose resolutions consciously.
 
-If there are no errors, proceed to the next step. 
+## Run the project locally with Dev Containers
 
-### Step 5 - Run MkDocs
-1. To start the server and view the site on your local server, run the following command:
+This repository supports the VS Code dev containers feature, which allows you to create a consistent and isolated development environment inside a Docker container. To use this feature, you need to have the following pre requisites:
 
-    ```shell
-    $ mkdocs serve
-    ```
+- VS Code
+- Docker installed on your system
+- [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension for VS Code
+
+Once you have these installed, you can open the repository in VS Code and follow these steps:
+
+- Press F1 and select the Remote-Containers: Open Folder in Container... command.
+- Select the repository folder and wait for the container to build and start.
+- You can now edit, run, debug, and test your code inside the container.
 
-    > **NOTE:**
-    >
-    > If you want to make changes and see them on the fly, run the following command to start the server and view the site on your local server:
-    > 1. Navigate to the `mkdocs.yml` file.
-    > 2. Set the following configuration:
-    >     ```
-    >     #Breaks build if there's a warning
-    >     strict: false
-    >     ```
-    > 3. To start the server, make it load the changes, and display the changes faster, run the following command:
-    >
-    >    `mkdocs serve --dirtyreload`
-
-2. To view the Choreo documentation site locally, open the following URL on a new browser window:
-
-    [http://localhost:8000/](http://localhost:8000/)
-
-> **NOTE:**
->
-> If you are using the `mkdocs serve --dirtyreload` command to run the MkDocs server, be sure to change the configuration in the `mkdocs.yml` file as follows before sending a pull request:
->
-> `strict: true`
+For more information on how to use VS Code dev containers, please refer to the official documentation: https://code.visualstudio.com/docs/remote/containers
 
 ## License
 

diff --git a/en/.spelling b/en/.spelling
@@ -108,6 +108,7 @@ WebApps
 cron
 deployment.toml
 subpath
+helloworld
 codebase
 libs
 work-with-the-micro-integrator-runtime-in-choreo

diff --git a/...-a-custom-domain-for-your-organization.md → ...-a-custom-domain-for-your-organization.md b/...-a-custom-domain-for-your-organization.md → ...-a-custom-domain-for-your-organization.md
@@ -70,6 +70,48 @@ To add a custom domain for your organization, follow the steps given below:
           - Certificate chain file guidelines:
              - The chain file, which is essential for some clients to verify the authenticity of a server's SSL/TLS certificate, should contain your domain's SSL/TLS certificate (optional, as this can be provided via the certificate itself) and one or more intermediate certificates in the correct order, leading back to a root certificate. 
              - All certificates in the chain should be X509 certificates in PEM format.
+               <details><summary>For step-by-step instructions on constructing a certificate chain with a root certificate, click here</summary>
+               To construct a certificate chain with a root certificate, you must organize and combine the certificates in the correct sequence. A typical certificate chain consists of the following:
+                 - **Root certificate**: The trusted self-signed certificate issued by the certificate authority (CA).
+                 - **Intermediate certificates** (if any): Certificates issued by the root CA to subordinate CAs.
+                 - **Leaf certificate**: Your end-entity certificate issued by the CA. This is an optional certificate that may be included within the chain or provided separately.<br><br>
+                Follow these steps to construct the certificate chain:
+                    1. Obtain and organize your certificates in the correct order:
+                        - **Leaf certificate**: The public certificate issued by the CA. This is optional and may be included within the chain or provided separately.
+                        - **Intermediate certificates**: Obtain these from the CA, if applicable.
+                        - **Root certificate**: Obtain this from the CA.  If it is self-signed, it serves as the trust anchor.
+                    2. Combine the certificates into a single file in the following order:
+                        - Leaf certificate: This is your public certificate issued by the CA.
+                        - Intermediate certificates if applicable: Include these in the correct hierarchical order.
+                        - Root certificate: Include this at the end of the file.<br><br>
+                        Use a text editor or a command-line tool to concatenate the certificates into one file, ensuring each certificate begins and ends with the proper markers. Also make sure the `BEGIN CERTIFICATE` and `END CERTIFICATE` markers appear on a new line:
+                    ```
+                     -----BEGIN CERTIFICATE-----
+                     <Leaf Certificate Content>
+                     -----END CERTIFICATE-----
+                     -----BEGIN CERTIFICATE-----
+                     <Intermediate Certificate Content>
+                     -----END CERTIFICATE-----
+                     -----BEGIN CERTIFICATE-----
+                     <Root Certificate Content>
+                     -----END CERTIFICATE-----
+                    ```
+                    3. Save the concatenated file. You can save it with a name such as `certificate_chain.pem`.
+                    4. Use the following command to verify that your certificate chain is constructed correctly:
+                    ```
+                    openssl verify -CAfile <root_or_bundle_cert>.pem certificate_chain.pem
+                    ```
+                    Replace `<root_or_bundle_cert>.pem` with the path to your root certificate or a bundle containing both the root and intermediate certificates.
+                    5. Once the certificate chain is verified, upload it via the Choreo Console:
+                        ![Upload certificate chain](../assets/img/administer/configure-domain/upload-certificate-chain.png)
+                        - If the constructed chain includes the leaf certificate, follow these steps:
+                            - Upload the constructed certificate chain in the **TLS Certificate** field.
+                            - Upload the private key file in the **TLS Key File** field.
+                            - Do not upload a certificate chain file, as it is already included in the TLS certificate.
+                        - If the constructed chain does not include the leaf certificate, follow these steps:
+                            - Upload the leaf certificate in the **TLS Certificate** field.
+                            - Upload the private key file in the **TLS Key File** field.
+                            - Upload the constructed certificate chain in the **Certificate Chain File** field.
 
      To proceed with this step in this guide, click **Let's Encrypt**.
 

diff --git a/...nfigure-a-user-store-with-built-in-idp.md → ...nfigure-a-user-store-with-built-in-idp.md b/...nfigure-a-user-store-with-built-in-idp.md → ...nfigure-a-user-store-with-built-in-idp.md
diff --git a/.../configure-asgardeo-as-an-external-idp.md → .../configure-asgardeo-as-an-external-idp.md b/.../configure-asgardeo-as-an-external-idp.md → .../configure-asgardeo-as-an-external-idp.md
diff --git a/.../configure-azure-ad-as-an-external-idp.md → .../configure-azure-ad-as-an-external-idp.md b/.../configure-azure-ad-as-an-external-idp.md → .../configure-azure-ad-as-an-external-idp.md
@@ -24,7 +24,7 @@ Follow the steps below to add Azure AD as an IdP in Choreo:
     !!! info
         - In azure, there are two versions of access tokens available. By default, the IDP applications you create use the v1 access token. Therefore, if you intend to use the v1 access token, when providing the `Well-Known URL`, omit the v2.0 path segment from the URL. [Learn more](https://learn.microsoft.com/en-us/azure/active-directory/develop/access-tokens#token-formats)
         For example, convert `https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration`-> `https://login.microsoftonline.com/<tenant-id>/.well-known/openid-configuration`
-        - If you intend to work with v2.0, then the IDP application's manifest should be changed as explained in the [access tokendocumentation](https://learn.microsoft.com/en-us/azure/active-directory/develop/access-tokens#token-formats). 
+        - If you intend to work with v2.0, then the IDP application's manifest should be changed as explained in the [access token documentation](https://learn.microsoft.com/en-us/azure/active-directory/develop/access-tokens#token-formats). 
 
 8. Leave the **Apply to all environments** checkbox selected. However, if you want to restrict the use of the external IdP to a certain environment, you can select them from the **Environments** list.
 9. Review the endpoints and click **Next**.