From 62dd4da8a12d8640d9f0153b268c0dbbe3e5fce5 Mon Sep 17 00:00:00 2001
From: mfranzon <43796979+mfranzon@users.noreply.github.com>
Date: Wed, 29 Jan 2025 15:48:55 +0100
Subject: [PATCH 01/16] add dex guide

---
 content/guides/dex.md | 130 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 130 insertions(+)
 create mode 100644 content/guides/dex.md

diff --git a/content/guides/dex.md b/content/guides/dex.md
new file mode 100644
index 00000000000..821fc4c5b65
--- /dev/null
+++ b/content/guides/dex.md
@@ -0,0 +1,130 @@
+---
+title: Mocking OAuth services in testing with Dex
+description: &desc Mocking OAuth services in testing with Dex
+keywords: Dex, container-supported development
+linktitle: Mocking OAuth services with Dex
+summary: *desc
+tags: [app-dev, distributed-systems]
+languages: []
+params:
+  time: 10 minutes
+---
+
+Dex is an open-source OpenID Connect (OIDC) and OAuth 2.0 identity provider that can be configured to authenticate against various backend identity providers, such as LDAP, SAML, and OAuth. Running Dex in a Docker container allows developers to simulate an OAuth 2.0 server for testing and development purposes. This guide will walk you through setting up Dex as an OAuth mock server using Docker containers.
+
+Nowadays OAuth is the preferred choice to authenticate in web services, the highest part of them give the possibility to access using popular OAuth services like Github, Google or Apple. Using OAuth guarantees a higher level of security and simplification since it is not necessary to create new profiles for each service. This means that, by allowing applications to access resources on behalf of users without sharing passwords, OAuth minimizes the risk of credential exposure.
+
+In this guide, you'll learn how to:
+
+- Use Docker to launch up a Dex container.
+- Use mock OAuth in the local development without relying on an external OAuth provider.
+
+## Using Dex with Docker
+
+The official [Docker image for Dex](https://hub.docker.com/r/dexidp/dex/) provides a convenient way to deploy and manage Dex instances. Dex is available for various CPU architectures, including amd64, armv7, and arm64, ensuring compatibility with different devices and platforms. You can learn more about Dex standalone on the [Dex docs site](https://dexidp.io/docs/getting-started/).
+
+### Prerequisites
+
+[Docker Compose](https://docs.docker.com/compose/): Recommended for managing multi-container Docker applications.
+
+### Setting Up Dex with Docker
+
+Begin by creating a directory for your Dex project:
+
+```bash
+mkdir dex-mock-server
+cd dex-mock-server
+```
+Organize your project with the following structure:
+
+```bash
+dex-mock-server/
+├── config.yaml
+└── docker-compose.yaml
+```
+
+Create the Dex Configuration File:
+
+The config.yaml file defines Dex's settings, including connectors, clients, and storage. For a mock server setup, you can use the following minimal configuration:
+
+```yaml
+# config.yaml
+issuer: http://localhost:5556/dex
+storage:
+  type: memory
+web:
+  http: 0.0.0.0:5556
+staticClients:
+  - id: example-app
+    redirectURIs:
+      - 'http://localhost:5555/callback'
+    name: 'Example App'
+    secret: ZXhhbXBsZS1hcHAtc2VjcmV0
+enablePasswordDB: true
+staticPasswords:
+  - email: "admin@example.com"
+    hash: "$2a$10$2b2cU8CPhOTaGrs1HRQuAueS7JTT5ZHsHSzYiFPm1leZck7Mc8T4W"
+    username: "admin"
+    userID: "1234"
+```
+
+Explanation:
+
+- issuer: The public URL for Dex.
+
+- storage: Using in-memory storage for simplicity.
+
+- web: Dex will listen on port 5556.
+
+- staticClients: Defines a client application (example-app) with its redirect URI and secret.
+
+- enablePasswordDB: Enables static password authentication.
+
+- staticPasswords: Defines a static user for authentication. The hash is a bcrypt hash of the password.
+
+> Note: Ensure the hash is a valid bcrypt hash of your desired password. You can generate this using tools like [bcrypt-generator.com](https://bcrypt-generator.com/)
+or use CLI tools like [htpasswd](https://httpd.apache.org/docs/2.4/programs/htpasswd.html) like in this following example:
+```bash
+echo password | htpasswd -BinC 10 admin | cut -d: -f2
+```
+
+Running Dex
+
+With Docker Compose configured, start Dex:
+
+```yaml
+# docker-compose.yaml
+
+services:
+  dex:
+    image: dexidp/dex:latest
+    container_name: dex
+    ports:
+      - "5556:5556"
+    volumes:
+      - ./config.yaml:/etc/dex/config.yaml
+    command: ["dex", "serve", "/etc/dex/config.yaml"]
+```
+
+Now it is possible to run the container using `docker compose` command.
+```bash
+docker compose up -d
+```
+
+This command will download the Dex Docker image (if not already available) and start the container in detached mode.
+
+
+To Verify that Dex is running, check the logs to ensure Dex started successfully:
+
+```bash
+docker-compose logs -f dex
+```
+You should see output indicating that Dex is listening on the specified port.
+
+Testing the OAuth Flow
+Prepare a Test Application:
+
+To test the OAuth flow, you'll need a client application configured to authenticate against Dex. Dex provides an example app that you can use for this purpose.
+
+Clone the Dex Repository:
+

From 576743e44887c85bc351d9db0446616babca58d8 Mon Sep 17 00:00:00 2001
From: mfranzon <43796979+mfranzon@users.noreply.github.com>
Date: Wed, 12 Mar 2025 10:22:07 +0100
Subject: [PATCH 02/16] more work dex guide

---
 content/guides/dex.md | 65 +++++++++++++++++++++++++++++++++----------
 1 file changed, 50 insertions(+), 15 deletions(-)

diff --git a/content/guides/dex.md b/content/guides/dex.md
index 821fc4c5b65..b8ae2eed344 100644
--- a/content/guides/dex.md
+++ b/content/guides/dex.md
@@ -17,7 +17,7 @@ Nowadays OAuth is the preferred choice to authenticate in web services, the high
 In this guide, you'll learn how to:
 
 - Use Docker to launch up a Dex container.
-- Use mock OAuth in the local development without relying on an external OAuth provider.
+- Use mock OAuth in the GHA without relying on an external OAuth provider.
 
 ## Using Dex with Docker
 
@@ -44,7 +44,6 @@ dex-mock-server/
 ```
 
 Create the Dex Configuration File:
-
 The config.yaml file defines Dex's settings, including connectors, clients, and storage. For a mock server setup, you can use the following minimal configuration:
 
 ```yaml
@@ -69,7 +68,6 @@ staticPasswords:
 ```
 
 Explanation:
-
 - issuer: The public URL for Dex.
 
 - storage: Using in-memory storage for simplicity.
@@ -83,15 +81,9 @@ Explanation:
 - staticPasswords: Defines a static user for authentication. The hash is a bcrypt hash of the password.
 
 > Note: Ensure the hash is a valid bcrypt hash of your desired password. You can generate this using tools like [bcrypt-generator.com](https://bcrypt-generator.com/)
-or use CLI tools like [htpasswd](https://httpd.apache.org/docs/2.4/programs/htpasswd.html) like in this following example:
-```bash
-echo password | htpasswd -BinC 10 admin | cut -d: -f2
-```
-
-Running Dex
+or use CLI tools like [htpasswd](https://httpd.apache.org/docs/2.4/programs/htpasswd.html) like in this following example:`echo password | htpasswd -BinC 10 admin | cut -d: -f2`
 
 With Docker Compose configured, start Dex:
-
 ```yaml
 # docker-compose.yaml
 
@@ -115,16 +107,59 @@ This command will download the Dex Docker image (if not already available) and s
 
 
 To Verify that Dex is running, check the logs to ensure Dex started successfully:
-
 ```bash
 docker-compose logs -f dex
 ```
 You should see output indicating that Dex is listening on the specified port.
 
-Testing the OAuth Flow
-Prepare a Test Application:
+#### Using Dex OAuth testing in GHA
+
+To test the OAuth flow, you'll need a client application configured to authenticate against Dex. One of the most typical use cases is to use it inside Github Actions. Since Dex supports mock authentication, you can predefine test users as suggests in the [docs](https://dexidp.io/docs). The `config.yaml` file should looks like:
+
+```yaml
+issuer: http://127.0.0.1:5556/dex
+
+storage:
+  type: memory
 
-To test the OAuth flow, you'll need a client application configured to authenticate against Dex. Dex provides an example app that you can use for this purpose.
+web:
+  http: 0.0.0.0:5556
+
+oauth2:
+  skipApprovalScreen: true
+
+staticClients:
+  - name: TestClient
+    id: client_test_id
+    secret: client_test_secret
+    redirectURIs:
+      - http://{ip-your-app}/path/to/callback/ # example: http://localhost:5555/callback
+
+connectors:
+# mockCallback connector always returns the user 'kilgore@kilgore.trout'.
+- type: mockCallback
+  id: mock
+  name: Mock
+```
+Now you can insert the Dex service inside your `~/.github/workflows/ci.yaml` file:
+
+```yaml
+[...]
+jobs:
+  test-oauth:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install Dex
+        run: |
+          curl -L https://github.com/dexidp/dex/releases/download/v2.37.0/dex_linux_amd64 -o dex
+          chmod +x dex
+
+      - name: Start Dex Server
+        run: |
+          nohup ./dex serve config.yaml > dex.log 2>&1 &
+          sleep 5  # Give Dex time to start
+[...]
+
+```
 
-Clone the Dex Repository:
 

From 2c12ba027d740ed0943f63134604565df4f01420 Mon Sep 17 00:00:00 2001
From: mfranzon <43796979+mfranzon@users.noreply.github.com>
Date: Wed, 12 Mar 2025 10:28:59 +0100
Subject: [PATCH 03/16] add conclusions

---
 content/guides/dex.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/content/guides/dex.md b/content/guides/dex.md
index b8ae2eed344..5c4f68d9231 100644
--- a/content/guides/dex.md
+++ b/content/guides/dex.md
@@ -112,7 +112,7 @@ docker-compose logs -f dex
 ```
 You should see output indicating that Dex is listening on the specified port.
 
-#### Using Dex OAuth testing in GHA
+### Using Dex OAuth testing in GHA
 
 To test the OAuth flow, you'll need a client application configured to authenticate against Dex. One of the most typical use cases is to use it inside Github Actions. Since Dex supports mock authentication, you can predefine test users as suggests in the [docs](https://dexidp.io/docs). The `config.yaml` file should looks like:
 
@@ -159,7 +159,8 @@ jobs:
           nohup ./dex serve config.yaml > dex.log 2>&1 &
           sleep 5  # Give Dex time to start
 [...]
-
 ```
 
 
+### Conclusion
+By following this guide, you've set up Dex as an OAuth mock server using Docker. This setup is invaluable for testing and development, allowing you to simulate OAuth flows without relying on external identity providers. For more advanced configurations and integrations, refer to the [Dex documentation](https://dexidp.io/docs/).

From 47edef86a3571673fa05b8bc572272914e37478e Mon Sep 17 00:00:00 2001
From: Marco Franzon <43796979+mfranzon@users.noreply.github.com>
Date: Wed, 26 Mar 2025 09:56:27 +0100
Subject: [PATCH 04/16] Update content/guides/dex.md

Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com>
---
 content/guides/dex.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/guides/dex.md b/content/guides/dex.md
index 5c4f68d9231..8a5fbdee500 100644
--- a/content/guides/dex.md
+++ b/content/guides/dex.md
@@ -12,7 +12,7 @@ params:
 
 Dex is an open-source OpenID Connect (OIDC) and OAuth 2.0 identity provider that can be configured to authenticate against various backend identity providers, such as LDAP, SAML, and OAuth. Running Dex in a Docker container allows developers to simulate an OAuth 2.0 server for testing and development purposes. This guide will walk you through setting up Dex as an OAuth mock server using Docker containers.
 
-Nowadays OAuth is the preferred choice to authenticate in web services, the highest part of them give the possibility to access using popular OAuth services like Github, Google or Apple. Using OAuth guarantees a higher level of security and simplification since it is not necessary to create new profiles for each service. This means that, by allowing applications to access resources on behalf of users without sharing passwords, OAuth minimizes the risk of credential exposure.
+Nowadays OAuth is the preferred choice to authenticate in web services, the highest part of them give the possibility to access using popular OAuth services like GitHub, Google or Apple. Using OAuth guarantees a higher level of security and simplification since it is not necessary to create new profiles for each service. This means that, by allowing applications to access resources on behalf of users without sharing passwords, OAuth minimizes the risk of credential exposure.
 
 In this guide, you'll learn how to:
 

From 8fdaeff96adfcc3abbd12fd68e69222dcdba5bd1 Mon Sep 17 00:00:00 2001
From: Marco Franzon <43796979+mfranzon@users.noreply.github.com>
Date: Wed, 26 Mar 2025 09:56:36 +0100
Subject: [PATCH 05/16] Update content/guides/dex.md

Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com>
---
 content/guides/dex.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/guides/dex.md b/content/guides/dex.md
index 8a5fbdee500..8e57c838734 100644
--- a/content/guides/dex.md
+++ b/content/guides/dex.md
@@ -17,7 +17,7 @@ Nowadays OAuth is the preferred choice to authenticate in web services, the high
 In this guide, you'll learn how to:
 
 - Use Docker to launch up a Dex container.
-- Use mock OAuth in the GHA without relying on an external OAuth provider.
+- Use mock OAuth in the GitHub Action (GHA) without relying on an external OAuth provider.
 
 ## Using Dex with Docker
 

From 2b53f8e9a5939c04f6b4b39b876416203ad90e9d Mon Sep 17 00:00:00 2001
From: Marco Franzon <43796979+mfranzon@users.noreply.github.com>
Date: Wed, 26 Mar 2025 09:56:47 +0100
Subject: [PATCH 06/16] Update content/guides/dex.md

Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com>
---
 content/guides/dex.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/content/guides/dex.md b/content/guides/dex.md
index 8e57c838734..b585a744b80 100644
--- a/content/guides/dex.md
+++ b/content/guides/dex.md
@@ -80,7 +80,9 @@ Explanation:
 
 - staticPasswords: Defines a static user for authentication. The hash is a bcrypt hash of the password.
 
-> Note: Ensure the hash is a valid bcrypt hash of your desired password. You can generate this using tools like [bcrypt-generator.com](https://bcrypt-generator.com/)
+> [!NOTE]
+>
+> Ensure the hash is a valid bcrypt hash of your desired password. You can generate this using tools like [bcrypt-generator.com](https://bcrypt-generator.com/).
 or use CLI tools like [htpasswd](https://httpd.apache.org/docs/2.4/programs/htpasswd.html) like in this following example:`echo password | htpasswd -BinC 10 admin | cut -d: -f2`
 
 With Docker Compose configured, start Dex:

From 09145addce94dcb3be1ffc3cf3378d0c1752b3e8 Mon Sep 17 00:00:00 2001
From: Marco Franzon <43796979+mfranzon@users.noreply.github.com>
Date: Wed, 26 Mar 2025 09:57:01 +0100
Subject: [PATCH 07/16] Update content/guides/dex.md

Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com>
---
 content/guides/dex.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/guides/dex.md b/content/guides/dex.md
index b585a744b80..e624fe1ebb8 100644
--- a/content/guides/dex.md
+++ b/content/guides/dex.md
@@ -40,7 +40,7 @@ Organize your project with the following structure:
 ```bash
 dex-mock-server/
 ├── config.yaml
-└── docker-compose.yaml
+└── compose.yaml
 ```
 
 Create the Dex Configuration File:

From 9c039f2ae733876b017979fa6ffa8e3f0ceb75e4 Mon Sep 17 00:00:00 2001
From: Marco Franzon <43796979+mfranzon@users.noreply.github.com>
Date: Wed, 26 Mar 2025 09:57:09 +0100
Subject: [PATCH 08/16] Update content/guides/dex.md

Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com>
---
 content/guides/dex.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/guides/dex.md b/content/guides/dex.md
index e624fe1ebb8..ddc230f0a44 100644
--- a/content/guides/dex.md
+++ b/content/guides/dex.md
@@ -110,7 +110,7 @@ This command will download the Dex Docker image (if not already available) and s
 
 To Verify that Dex is running, check the logs to ensure Dex started successfully:
 ```bash
-docker-compose logs -f dex
+docker compose logs -f dex
 ```
 You should see output indicating that Dex is listening on the specified port.
 

From 51bc0e8c52d2beac6b1cac0a0c8b102ce9488fc4 Mon Sep 17 00:00:00 2001
From: Marco Franzon <43796979+mfranzon@users.noreply.github.com>
Date: Wed, 26 Mar 2025 09:57:16 +0100
Subject: [PATCH 09/16] Update content/guides/dex.md

Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com>
---
 content/guides/dex.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/guides/dex.md b/content/guides/dex.md
index ddc230f0a44..b593e70eaa2 100644
--- a/content/guides/dex.md
+++ b/content/guides/dex.md
@@ -108,7 +108,7 @@ docker compose up -d
 This command will download the Dex Docker image (if not already available) and start the container in detached mode.
 
 
-To Verify that Dex is running, check the logs to ensure Dex started successfully:
+To verify that Dex is running, check the logs to ensure Dex started successfully:
 ```bash
 docker compose logs -f dex
 ```

From e4be9d38c3078a4351152ebfa2d98b8e9b727def Mon Sep 17 00:00:00 2001
From: Marco Franzon <43796979+mfranzon@users.noreply.github.com>
Date: Wed, 26 Mar 2025 09:57:49 +0100
Subject: [PATCH 10/16] Update content/guides/dex.md

Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com>
---
 content/guides/dex.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/guides/dex.md b/content/guides/dex.md
index b593e70eaa2..772615e0f31 100644
--- a/content/guides/dex.md
+++ b/content/guides/dex.md
@@ -25,7 +25,7 @@ The official [Docker image for Dex](https://hub.docker.com/r/dexidp/dex/) provid
 
 ### Prerequisites
 
-[Docker Compose](https://docs.docker.com/compose/): Recommended for managing multi-container Docker applications.
+[Docker Compose](/compose/): Recommended for managing multi-container Docker applications.
 
 ### Setting Up Dex with Docker
 

From be4b242e5343a7fdcdb4c53cbc279ffcbeed975e Mon Sep 17 00:00:00 2001
From: Marco Franzon <43796979+mfranzon@users.noreply.github.com>
Date: Wed, 26 Mar 2025 09:58:03 +0100
Subject: [PATCH 11/16] Update content/guides/dex.md

Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com>
---
 content/guides/dex.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/guides/dex.md b/content/guides/dex.md
index 772615e0f31..b78a83ffb59 100644
--- a/content/guides/dex.md
+++ b/content/guides/dex.md
@@ -100,7 +100,7 @@ services:
     command: ["dex", "serve", "/etc/dex/config.yaml"]
 ```
 
-Now it is possible to run the container using `docker compose` command.
+Now it is possible to run the container using the `docker compose` command.
 ```bash
 docker compose up -d
 ```

From 89b489cc15a9baa89b2da6c7d478888983a41806 Mon Sep 17 00:00:00 2001
From: Marco Franzon <43796979+mfranzon@users.noreply.github.com>
Date: Wed, 26 Mar 2025 09:58:14 +0100
Subject: [PATCH 12/16] Update content/guides/dex.md

Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com>
---
 content/guides/dex.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/guides/dex.md b/content/guides/dex.md
index b78a83ffb59..3068e6b4294 100644
--- a/content/guides/dex.md
+++ b/content/guides/dex.md
@@ -116,7 +116,7 @@ You should see output indicating that Dex is listening on the specified port.
 
 ### Using Dex OAuth testing in GHA
 
-To test the OAuth flow, you'll need a client application configured to authenticate against Dex. One of the most typical use cases is to use it inside Github Actions. Since Dex supports mock authentication, you can predefine test users as suggests in the [docs](https://dexidp.io/docs). The `config.yaml` file should looks like:
+To test the OAuth flow, you'll need a client application configured to authenticate against Dex. One of the most typical use cases is to use it inside GitHub Actions. Since Dex supports mock authentication, you can predefine test users as suggested in the [docs](https://dexidp.io/docs). The `config.yaml` file should looks like:
 
 ```yaml
 issuer: http://127.0.0.1:5556/dex

From 1cc50e11ce7a2887dcc5020d2a1e0f20b5c30bef Mon Sep 17 00:00:00 2001
From: Marco Franzon <43796979+mfranzon@users.noreply.github.com>
Date: Wed, 26 Mar 2025 09:58:22 +0100
Subject: [PATCH 13/16] Update content/guides/dex.md

Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com>
---
 content/guides/dex.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/guides/dex.md b/content/guides/dex.md
index 3068e6b4294..32b3b97bfc5 100644
--- a/content/guides/dex.md
+++ b/content/guides/dex.md
@@ -68,7 +68,7 @@ staticPasswords:
 ```
 
 Explanation:
-- issuer: The public URL for Dex.
+- issuer: The public URL of Dex.
 
 - storage: Using in-memory storage for simplicity.
 

From ccb86db85444502d44e2a4d84097a47dfbc38813 Mon Sep 17 00:00:00 2001
From: Marco Franzon <43796979+mfranzon@users.noreply.github.com>
Date: Wed, 26 Mar 2025 09:58:37 +0100
Subject: [PATCH 14/16] Update content/guides/dex.md

Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com>
---
 content/guides/dex.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/content/guides/dex.md b/content/guides/dex.md
index 32b3b97bfc5..605d6bacc17 100644
--- a/content/guides/dex.md
+++ b/content/guides/dex.md
@@ -165,4 +165,5 @@ jobs:
 
 
 ### Conclusion
+
 By following this guide, you've set up Dex as an OAuth mock server using Docker. This setup is invaluable for testing and development, allowing you to simulate OAuth flows without relying on external identity providers. For more advanced configurations and integrations, refer to the [Dex documentation](https://dexidp.io/docs/).

From 6a7a93419d1356e429a871fe9b78a2d50f38f547 Mon Sep 17 00:00:00 2001
From: mfranzon <43796979+mfranzon@users.noreply.github.com>
Date: Wed, 26 Mar 2025 10:01:37 +0100
Subject: [PATCH 15/16] add Dex to vale accept.txt

---
 _vale/config/vocabularies/Docker/accept.txt | 1 +
 1 file changed, 1 insertion(+)

diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt
index 4b328de6474..71d0de4016d 100644
--- a/_vale/config/vocabularies/Docker/accept.txt
+++ b/_vale/config/vocabularies/Docker/accept.txt
@@ -20,6 +20,7 @@ Datadog
 Ddosify
 Debootstrap
 Dev
+Dex
 Dev Environments?
 Django
 Docker Build Cloud

From 1d3e72d1e1129219477f0fb491001aa72178d009 Mon Sep 17 00:00:00 2001
From: mfranzon <43796979+mfranzon@users.noreply.github.com>
Date: Tue, 29 Jul 2025 22:57:53 +0200
Subject: [PATCH 16/16] add otel guide

---
 content/guides/opentelemetry.md | 200 ++++++++++++++++++++++++++++++++
 1 file changed, 200 insertions(+)
 create mode 100644 content/guides/opentelemetry.md

diff --git a/content/guides/opentelemetry.md b/content/guides/opentelemetry.md
new file mode 100644
index 00000000000..9f340de69aa
--- /dev/null
+++ b/content/guides/opentelemetry.md
@@ -0,0 +1,200 @@
+---
+title: Instrumenting a JavaScript App with OpenTelemetry
+description: &desc Learn how to instrument a JavaScript application using OpenTelemetry in a Dockerized environment.
+keywords: OpenTelemetry, observability, tracing
+linktitle: Instrumenting JS Apps with OpenTelemetry
+summary: *desc
+tags: [app-dev, observability]
+languages: [JavaScript]
+params:
+  time: 10 minutes
+---
+
+OpenTelemetry (OTEL) is an open-source observability framework that provides a set of APIs, SDKs, and tools for collecting telemetry data, such as metrics, logs, and traces, from applications. With OpenTelemetry, developers can obtain valuable insights into how their services perform in production or during local development.
+
+A key component of OpenTelemetry is the OpenTelemetry Protocol (OTLP) a general-purpose, vendor-agnostic protocol designed to transmit telemetry data efficiently and reliably. OTLP supports multiple data types (traces, metrics, logs) over HTTP or gRPC, making it the default and recommended protocol for communication between instrumented applications, the OpenTelemetry Collector, and backends such as Jaeger or Prometheus.
+
+This guide walks you through how to instrument a simple Node.js application with OpenTelemetry and run both the app and a collector using Docker. This setup is ideal for local development and testing observability before integrating with external observability platforms like Prometheus, Jaeger, or Grafana.
+
+In this guide, you'll learn how to:
+
+- How to set up OpenTelemetry in a Node.js app.
+- How to run an OpenTelemetry Collector in Docker.
+- How to visualize traces with Jaeger.
+- How to use Docker Compose to manage the full observability stack.
+
+## Using OpenTelemetry with Docker
+
+the official [docker image for opentelemetry](https://hub.docker.com/r/otel/opentelemetry-collector-contrib) provides a convenient way to deploy and manage dex instances. Opentelemetry is available for various cpu architectures, including amd64, armv7, and arm64, ensuring compatibility with different devices and platforms. Same for the [Jaeger docekr image](https://hub.docker.com/r/jaegertracing/jaeger).
+
+## Prerequisites
+
+[Docker Compose](/compose/): Recommended for managing multi-container Docker applications.
+
+Basic knowledge of Node.js and Docker.
+
+## Project Structure
+
+Create the project directory:
+```bash
+mkdir otel-js-app
+cd otel-js-app
+```
+
+```bash
+otel-js-app/
+├── docker-compose.yaml
+├── collector-config.yaml
+├── app/
+│   ├── package.json
+│   ├── app.js
+│   └── tracer.js
+```
+
+## Create a Simple Node.js App
+
+Initialize a basic Node.js app:
+
+```bash
+mkdir app && cd app
+npm init -y
+npm install express @opentelemetry/api @opentelemetry/sdk-node \
+            @opentelemetry/auto-instrumentations-node \
+            @opentelemetry/exporter-trace-otlp-http
+```
+
+Now, add the application logic:
+
+```js
+// app/app.js
+const express = require('express');
+require('./tracer'); // Initialize OpenTelemetry
+
+const app = express();
+
+app.get('/', (req, res) => {
+  res.send('Hello from OpenTelemetry demo app!');
+});
+
+const PORT = 3000;
+app.listen(PORT, () => {
+  console.log(`App listening at http://localhost:${PORT}`);
+});
+```
+
+## Configure OpenTelemetry Tracing
+
+Create the tracer configuration file:
+
+```js
+// app/tracer.js
+const { NodeSDK } = require('@opentelemetry/sdk-node');
+const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
+const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
+
+const sdk = new NodeSDK({
+  traceExporter: new OTLPTraceExporter({
+    url: 'http://collector:4318/v1/traces',
+  }),
+  instrumentations: [getNodeAutoInstrumentations()],
+});
+
+sdk.start();
+```
+
+## Configure the OpenTelemetry Collector
+
+Create a collector-config.yaml file at the root:
+
+```yaml
+# collector-config.yaml
+receivers:
+  otlp:
+    protocols:
+      http:
+
+exporters:
+  logging:
+    loglevel: debug
+  jaeger:
+    endpoint: jaeger:14250
+    tls:
+      insecure: true
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      exporters: [logging, jaeger]
+```
+
+## Add Docker Compose Configuration
+
+Create the `docker-compose.yaml` file:
+
+```yaml
+version: '3.9'
+
+services:
+  app:
+    build: ./app
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=development
+    depends_on:
+      - collector
+
+  collector:
+    image: otel/opentelemetry-collector:latest
+    volumes:
+      - ./collector-config.yaml:/etc/otelcol/config.yaml
+    command: ["--config=/etc/otelcol/config.yaml"]
+    ports:
+      - "4318:4318" # OTLP
+
+  jaeger:
+    image: jaegertracing/all-in-one:latest
+    ports:
+      - "16686:16686" # UI
+      - "14250:14250" # Collector gRPC
+```
+
+Now, add the `Dockerfile` inside the `app/` folder:
+
+```dockerfile
+# app/Dockerfile
+FROM node:18
+
+WORKDIR /usr/src/app
+COPY . .
+RUN npm install
+
+CMD ["node", "app.js"]
+```
+
+## Start the Stack
+
+Start all services with Docker Compose:
+
+```bash
+docker compose up --build
+```
+
+Once the services are running:
+
+Visit your app at [http://localhost:3000](http://localhost:3000)
+
+View traces at [http://localhost:16686](http://localhost:16686) in the Jaeger UI
+
+## Verify Traces in Jaeger
+
+After visiting your app's root endpoint, open Jaeger’s UI, search for the service (default is usually unknown_service unless explicitly named), and check the traces.
+
+You should see spans for the HTTP request, middleware, and auto-instrumented libraries.
+
+## Conclusion
+
+You now have a fully functional OpenTelemetry setup using Docker Compose. You've instrumented a basic JavaScript app to export traces and visualized them using Jaeger. This architecture is extendable for more complex applications and observability pipelines using Prometheus, Grafana, or cloud-native exporters.
+
+For advanced topics such as custom span creation, metrics, and logs, consult the OpenTelemetry JavaScript docs.