docs: fix mkdocs warnings and add CERN SSO guide (#170)

chrisburr · pre-commit-ci-lite[bot] · web-flow · commit ea8652ba0893 · 2025-08-15T14:04:45.000+02:00
* docs: add CERN SSO configuration guide * docs: fix broken links in documentation - Remove broken k3s and values.yaml links in RUN_PROD.md - Fix installing.md path references in chart-structure.md - Fix configuration.md path in installing.md - Fix deployment template references in run_locally.md - Fix run_demo.md path reference * docs: add proper S3-hosted image link for OTEL collector - Upload otel-collector.png to S3 static hosting - Replace broken local image reference with proper S3 URL * [pre-commit.ci lite] apply automatic fixes * docs: remove otel-collector.png from repo Image is now hosted on S3 static site as per documentation guidelines: https://diracx-docs-static.s3.cern.ch/assets/images/admin/tutorials/otel-collector.png * docs: link deployment templates to GitHub instead of broken local paths - Replace broken local file references with working GitHub links - Users can now directly view the deployment.yaml templates - Links point to main branch for stable references * docs: fix GitHub links to use master branch instead of main - diracx-charts uses master branch, not main - Update deployment template links to correct branch --------- Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com>
diff --git a/demo/otel-collector.png b/demo/otel-collector.png
diff --git a/docs/README.md b/docs/README.md
diff --git a/docs/RUN_PROD.md b/docs/RUN_PROD.md
@@ -4,12 +4,12 @@ The aim of this documentation is to give pointers on how to install the `diracx-
 
 Effectively, this means that you will be using your existing databases (`MySQL`, `OpenSearch`), and just install the new dependencies of `diracx`.
 
-We go here with the assumption that you have a `kubernetes` cluster at hand. If you do no have one, see the [k3s example](../k3s/README.md).
+We go here with the assumption that you have a `kubernetes` cluster at hand.
 
 
 If your central infrastructure already provide the following services, by all mean, use them.
 
-More configuration options are available, please refer to the [values.yaml](../diracx/values.yaml)
+More configuration options are available in the chart's values.yaml file
 
 ## Getting started
 
diff --git a/docs/SSO.md b/docs/SSO.md
@@ -0,0 +1,57 @@
+# CERN SSO Configuration
+
+This document describes how to configure CERN SSO as an Identity Provider (IdP) for DiracX.
+
+## Prerequisites
+
+- Access to CERN Application Portal
+- Administrative rights to register a new application
+
+## Registration Steps
+
+1. Go to the [CERN Application Portal](https://application-portal.web.cern.ch/)
+2. Click "Register a new application"
+3. Fill in the application details:
+   - **Application Name**: DiracX [Your VO/Installation]
+   - **Description**: DiracX authentication for [Your VO]
+   - **SSO Protocol**: OpenID Connect
+
+## Configuration
+
+### Redirect URLs
+
+Configure the following redirect URLs in your CERN SSO application:
+
+```
+https://<youdiracx.invalid>/api/auth/device/complete
+https://<youdiracx.invalid>/api/auth/authorize/complete
+```
+
+Replace `<youdiracx.invalid>` with your actual DiracX hostname.
+
+### Client Configuration
+
+- **Client Type**: Public (no client authentication required)
+- **Required Scopes**: `email`, `openid`, `profile`
+- **Grant Type**: Authorization Code Flow with PKCE
+- **Token Endpoint Authentication**: None (public client)
+
+## Integration with DiracX
+
+Once your CERN SSO application is registered, you'll receive:
+- Client ID
+- Discovery URL (usually `https://auth.cern.ch/auth/realms/cern/.well-known/openid_configuration`)
+
+Configure these in your DiracX values:
+
+```yaml
+diracx:
+  settings:
+    DIRACX_AUTH_OIDC_PROVIDER_NAME: "cern"
+    DIRACX_AUTH_OIDC_CLIENT_ID: "your-client-id"
+    DIRACX_AUTH_OIDC_DISCOVERY_URL: "https://auth.cern.ch/auth/realms/cern/.well-known/openid_configuration"
+```
+
+## User Registration
+
+Note that users still need to be registered in DiracX by configuring the `CsSync` section in the Configuration Service (CS).
diff --git a/docs/admin/explanations/chart-structure.md b/docs/admin/explanations/chart-structure.md
@@ -20,7 +20,7 @@ Detailed documentation with justification for technical decisions can be found [
 The chart includes the following external dependencies, all conditionally enabled:
 
 !!! warning "Production Deployments"
-    The bundled dependencies listed below are primarily intended for development and testing environments. For production deployments, you should use externally managed services. See the [installation guide](../how-to/installing.md) for production deployment recommendations.
+    The bundled dependencies listed below are primarily intended for development and testing environments. For production deployments, you should use externally managed services. See the [installation guide](../how-to/install/installing.md) for production deployment recommendations.
 
 ### Core Infrastructure
 - **MySQL** (`mysql`): Primary database for DiracX data storage
@@ -215,7 +215,7 @@ For production deployments:
 - Configures proper resource limits and requests
 - Sets up monitoring and alerting
 
-To find more about running in production mode see [here](../how-to/installing.md).
+To find more about running in production mode see [here](../how-to/install/installing.md).
 
 ## Bootstrap Sequence
 
diff --git a/docs/admin/how-to/install/installing.md b/docs/admin/how-to/install/installing.md
@@ -212,7 +212,7 @@ GRANT SELECT, INSERT, UPDATE, DELETE, INDEX, CREATE TEMPORARY TABLES, LOCK TABLE
 
 ## DiracX Config URL
 
-This should be the URL of the repository populated by synchronizing the CS. You should already have completed the CS synchronization step. For more details about the configuration, see the [dedicated explanations](../explanations/configuration.md)
+This should be the URL of the repository populated by synchronizing the CS. You should already have completed the CS synchronization step. For more details about the configuration, see the [dedicated explanations](../../explanations/configuration.md)
 
 !!! note "You do not need write permissions"
 
diff --git a/docs/admin/tutorials/run_locally.md b/docs/admin/tutorials/run_locally.md
@@ -10,7 +10,7 @@ To understand this ``chart`` you will need to familiarize yourself with a few k8
 * A ``node`` is one of the machine (VM, physical) which sustains your k8s cluster.
 * Your application runs inside a container which is part of a ``pod``. A ``pod`` is the atomic unit with which kubernetes will work, and in most cases it corresponds to a single container. ``pods`` are deployed on ``nodes``.
 * A ``ReplicaSet`` represents how many ``pods`` of a given type you want to run. For example, you want to run 3 ``pods`` containing the ``diracx`` container for redundancy reasons.
-* A ``Deployment`` is how you describe your workload to k8s. It ensures that any number of replicas of your ``pod`` are running (via ``ReplicaSEt``). This chart contains a ``deployment`` for ``diracx`` (see [here](diracx/templates/diracx/deployment.yaml)), and a ``deployment`` for ``diracx-web`` (see [here](diracx/templates/diracx-web/deployment.yaml)). Kubernetes will always make sure that the ``deployment`` is satisfied.
+* A ``Deployment`` is how you describe your workload to k8s. It ensures that any number of replicas of your ``pod`` are running (via ``ReplicaSEt``). This chart contains a ``deployment`` for ``diracx`` (see [here](https://github.com/DIRACGrid/diracx-charts/blob/master/diracx/templates/diracx/deployment.yaml)), and a ``deployment`` for ``diracx-web`` (see [here](https://github.com/DIRACGrid/diracx-charts/blob/master/diracx/templates/diracx-web/deployment.yaml)). Kubernetes will always make sure that the ``deployment`` is satisfied.
 * A ``Service`` is how you expose your ``Deployment``. If I want to talk to my ``diracx`` application, it is a ``Service`` which will take care of redirecting me within the cluster to one of the ``pod``. Most of the time, the ``Service`` is used for routing inside the cluster
 * An ``Ingress`` exposes your ``Services`` outside of the cluster.
 
@@ -78,7 +78,7 @@ helm diff upgrade diracx-demo  ./diracx --values .demo/values.yaml --set rabbitm
 helm upgrade diracx-demo ./diracx --values .demo/values.yaml
 ```
 
-See [here](../../../dev/explanations/run_demo.md) for more details on what you can do to alter the behavior of the local installation.
+See [here](../../dev/explanations/run_demo.md) for more details on what you can do to alter the behavior of the local installation.
 
 
 ## OpenTelemetry
@@ -96,4 +96,4 @@ To enable it, run ``run_demo.sh`` with ``enable-open-telemetry``
 
 Note that this configuration is trivial and does not follow production recommandations (like using batch processing)
 
-![OTEL collector configuration](../../../demo/otel-collector.png)
+![OTEL collector configuration](https://diracx-docs-static.s3.cern.ch/assets/images/admin/tutorials/otel-collector.png)
