PR for SRVLOGIC-537: Add "Configuring custom Maven mirrors" section in the OpenShift Serverless Logic docs

_topic_maps/_topic_map.yml

@@ -401,6 +401,8 @@ Topics:
   File: serverless-logic-managing-persistence
 - Name: Workflow eventing system
   File: serverless-logic-workflow-eventing-system
+- Name: Configuring custom Maven mirrors
+  File: serverless-logic-configuring-custom-maven-mirrors
 - Name: Managing upgrades
   Dir: serverless-logic-managing-upgrades
   Topics:

modules/serverless-logic-adding-maven-mirror-building-workflows.adoc

@@ -0,0 +1,69 @@
+// Module included in the following assemblies:
+// * serverless-logic/serverless-logic-configuring-custom-maven-mirrors.adoc
+
+
+:_mod-docs-content-type: PROCEDURE
+[id="serverless-logic-adding-maven-mirror-building-workflows_{context}"]
+= Adding a Maven mirror when building workflows
+
+You can configure a Maven mirror by setting the `MAVEN_MIRROR_URL` environment variable in the `SonataFlowBuild` or `SonataFlowPlatform` custom resources (CR). 
+
+[NOTE]
+====
+The recommended approach is to update the `SonataFlowPlatform` CR. This ensures the mirror configuration is propagated automatically to all workflow builds within the platform scope.  
+====
+
+.Prerequisites 
+
+* You have {ServerlessLogicOperatorName} installed on your cluster.
+* You have created your {ServerlessLogicProductName} project. 
+* You have access to a {ServerlessLogicProductName} project with the appropriate roles and permissions to create applications and other workloads in {ocp-product-title}.
+* You have access to a custom Maven mirror or internal repository.
+
+.Procedure
+
+. Edit the `SonataFlowPlatform` CR to configure a Maven mirror for all workflow builds in a namespace, as shown in the following example:
++
+.Example of Maven mirror configuration in a `SonataFlowPlatform` CR
+[source,yaml]
+----
+apiVersion: sonataflow.org/v1alpha08
+kind: SonataFlowPlatform
+metadata:
+  name: my-platform
+spec:
+  build:
+    template:
+      envs:
+        - name: MAVEN_MIRROR_URL
+          value: http://my.company.registry.local
+----
++
+This configuration applies to all workflow builds in the same namespace that use the `preview` profile. When a workflow builder instance runs, it updates the internal Maven settings file to use the specified mirror as the default for external locations such as Maven Central.
+
+. Optional: If you need a specific configuration for a single workflow build, create the `SonataFlowBuild` CR before creating the corresponding `SonataFlow` CR. The `SonataFlowBuild` and `SonataFlow` CRs must have the same name. 
++
+.Example of Maven mirror configuration in a `SonataFlowBuild` CR
+[source,yaml]
+----
+apiVersion: sonataflow.org/v1alpha08
+kind: SonataFlowBuild
+metadata:
+  name: my-workflow <1>
+  annotations:
+    sonataflow.org/restartBuild: "true" <2>
+spec:
+  # suppressed for brevity
+  envs:
+    - name: MAVEN_MIRROR_URL <3>
+      value: http://my.company.registry.local
+----
++
+<1> The `SonataFlowBuild` CR must have the same name as the corresponding `SonataFlow` CR.  
+<2> The `sonataflow.org/restartBuild: "true"` annotation forces the existing build to restart with the new configuration.  
+<3> The `MAVEN_MIRROR_URL` environment variable specifies the custom Maven mirror.  
++
+[NOTE]
+====
+You can use the `SonataFlowBuild` CR configuration only when you require workflow-specific behavior, for example, debugging. For general use, configure the `SonataFlowPlatform` CR instead.
+====

modules/serverless-logic-adding-maven-mirror-deploy-dev-mode.adoc

@@ -0,0 +1,47 @@
+// Module included in the following assemblies:
+// * serverless-logic/serverless-logic-configuring-custom-maven-mirrors.adoc
+
+
+:_mod-docs-content-type: PROCEDURE
+[id="serverless-logic-adding-maven-mirror-deploy-dev-mode_{context}"]
+= Adding a Maven mirror when deploying in development mode
+
+You can configure a Maven mirror for workflows that run in `dev` mode by adding the `MAVEN_MIRROR_URL` environment variable to the `SonataFlow` custom resource (CR). 
+
+.Prerequisites 
+
+* You have created your {ServerlessLogicProductName} project. 
+* You have access to a {ServerlessLogicProductName} project with the appropriate roles and permissions to create applications and other workloads in {ocp-product-title}.
+* You have a workflow deployed in `dev` profile.
+* You have access to a custom Maven mirror or internal repository.
+
+.Procedure
+
+* Edit the `SonataFlow` CR to include the Maven mirror configuration as shown in the following example:
++
+.Example of Maven mirror configuration on SonataFlow CR
+[source,yaml]
+----
+apiVersion: sonataflow.org/v1alpha08
+kind: SonataFlow
+metadata:
+  name: greeting
+  annotations:
+    sonataflow.org/description: Greeting example on k8s!
+    sonataflow.org/version: 0.0.1
+    sonataflow.org/profile: dev
+spec:
+  podTemplate:
+    container:
+      env:
+        - name: MAVEN_MIRROR_URL <1>
+          value: http://my.company.registry.local
+  flow: #suppressed for brevity
+----
++
+<1> The `MAVEN_MIRROR_URL` variable specifies the custom Maven mirror.
+
+[NOTE]
+====
+Only workflows deployed with the `dev` profile can use Maven mirrors. Other deployment models run compiled code only, so they do not need to connect to a Maven registry.
+====

modules/serverless-logic-config-maven-mirror-on-custom-image.adoc

@@ -0,0 +1,48 @@
+// Module included in the following assemblies:
+// * serverless-logic/serverless-logic-configuring-custom-maven-mirrors.adoc
+
+
+:_mod-docs-content-type: PROCEDURE
+[id="serverless-logic-config-maven-mirror-on-custom-image_{context}"]
+= Configuring a Maven mirror on a custom image
+
+You can configure a Maven mirror for workflows that run in `dev` mode by adding the `MAVEN_MIRROR_URL` environment variable to the `SonataFlow` custom resource (CR). 
+
+.Prerequisites 
+
+* You have created your {ServerlessLogicProductName} project. 
+* You have access to a {ServerlessLogicProductName} project with the appropriate roles and permissions to create applications and other workloads in {ocp-product-title}.
+* You have access to a dockerfile or container build context that uses the SonataFlow Builder image.
+* You have access to a custom Maven mirror or internal repository.
+
+.Procedure
+
+. Set the Maven mirror as an environment variable in the Dockerfile as shown in the following example:
++
+.Example of custom container file with Maven mirror set as an environment variable
+[source,terminal]
+----
+FROM docker.io/apache/incubator-kie-sonataflow-builder:main AS builder
+
+# Content suppressed for brevity
+
+# The Maven mirror URL set as an env var during the build process
+ENV MAVEN_MIRROR_URL=http://my.company.registry.local
+----
++
+The `ENV` directive ensures that all builds with this Dockerfile automatically use the specified Maven mirror.
+
+. Set the Maven mirror as a build-time argument in the Dockerfile as shown in the following example:
++
+.Example of custom container file with Maven mirror set as an argument
+[source,terminal]
+----
+FROM docker.io/apache/incubator-kie-sonataflow-builder:main AS builder
+
+# Content suppressed for brevity
+
+# The Maven mirror URL passed as a build argument during the build process
+ARG MAVEN_MIRROR_URL
+----
++
+The `ARG` directive allows you to pass the Maven mirror value dynamically at build time.

serverless-logic/serverless-logic-configuring-custom-maven-mirrors.adoc

@@ -0,0 +1,24 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="serverless-logic-configuring-custom-maven-mirrors"]
+= Configuring custom Maven mirrors
+include::_attributes/common-attributes.adoc[]
+:context: serverless-logic-configuring-custom-maven-mirrors
+
+toc::[]
+
+{ServerlessLogicProductName} uses Maven Central by default to resolve Maven artifacts during workflow builds. The provided builder and development images include all required Java libraries to run workflows, but in certain scenarios, such as when you add a custom Quarkus extension, you must download the additional dependencies from Maven Central.
+
+In environments with restricted or firewalled network access, direct access to Maven Central might not be available. In such cases, you can configure the workflow containers to use a custom Maven mirror, such as an internal company registry or repository manager.
+
+You can configure a custom Maven mirror at different levels as follows:
+
+* Per workflow build by updating the `SonataFlowBuild` custom resource.
+* At the platform level by updating the `SonataFlowPlatform` custom resource. 
+* For development mode deployments by editing the `SonataFlow` custom resource.
+* When building custom images externally with the builder image
+
+include::modules/serverless-logic-adding-maven-mirror-building-workflows.adoc[leveloffset=+1]
+
+include::modules/serverless-logic-adding-maven-mirror-deploy-dev-mode.adoc[leveloffset=+1]
+
+include::modules/serverless-logic-config-maven-mirror-on-custom-image.adoc[leveloffset=+1]