This is an automated email from the ASF dual-hosted git repository. dhanak pushed a commit to branch 10.1.x in repository https://gitbox.apache.org/repos/asf/incubator-kie-kogito-docs.git
commit 92f22db9898bf0d65c0102e467cb591f734632bd Author: Ricardo Zanini <[email protected]> AuthorDate: Fri May 16 16:27:33 2025 -0300 Fix #kie-tools-3124 - Adding documentation about Quarkus Registry (#722) * Fix #kie-tools-3124 - Adding documentation about Quarkus Registry * Update serverlessworkflow/modules/ROOT/pages/cloud/operator/config-maven-quarkus.adoc Co-authored-by: Walter Medvedeo <[email protected]> --------- Co-authored-by: Walter Medvedeo <[email protected]> --- serverlessworkflow/modules/ROOT/nav.adoc | 2 +- .../config-maven-quarkus.adoc} | 72 ++++++++++++++++++++-- 2 files changed, 68 insertions(+), 6 deletions(-) diff --git a/serverlessworkflow/modules/ROOT/nav.adoc b/serverlessworkflow/modules/ROOT/nav.adoc index e8179d647..bce7d877c 100644 --- a/serverlessworkflow/modules/ROOT/nav.adoc +++ b/serverlessworkflow/modules/ROOT/nav.adoc @@ -47,7 +47,6 @@ * xref:cloud/index.adoc[Cloud] ** xref:cloud/custom-ingress-authz.adoc[Securing Workflows] ** xref:cloud/deploying-sonataflow-management-console-on-kubernetes.adoc[Deploying Management Console on Kubernetes] -** xref:cloud/config-maven.adoc[Configuring Maven] ** Operator *** xref:cloud/operator/install-serverless-operator.adoc[Installation] *** xref:cloud/operator/global-configuration.adoc[Admin Configuration] @@ -57,6 +56,7 @@ **** xref:cloud/operator/build-and-deploy-workflows.adoc[Preview Profile] **** xref:cloud/operator/gitops-profile.adoc[GitOps Profile] **** xref:cloud/operator/configuring-workflows.adoc[Workflow Configuration] +**** xref:cloud/operator/config-maven-quarkus.adoc[Maven and Quarkus Registry] **** xref:cloud/operator/referencing-resource-files.adoc[Referencing Workflow Resources] **** xref:cloud/operator/customize-podspec.adoc[Custom Workflow PodSpec] **** xref:cloud/operator/add-custom-ca-to-a-workflow-pod.adoc[Add Custom CA to Workflow Pod] diff --git a/serverlessworkflow/modules/ROOT/pages/cloud/config-maven.adoc b/serverlessworkflow/modules/ROOT/pages/cloud/operator/config-maven-quarkus.adoc similarity index 58% rename from serverlessworkflow/modules/ROOT/pages/cloud/config-maven.adoc rename to serverlessworkflow/modules/ROOT/pages/cloud/operator/config-maven-quarkus.adoc index 8cce2d326..288d91227 100644 --- a/serverlessworkflow/modules/ROOT/pages/cloud/config-maven.adoc +++ b/serverlessworkflow/modules/ROOT/pages/cloud/operator/config-maven-quarkus.adoc @@ -1,13 +1,14 @@ // Note: This section can grow over time to add more Maven-related configuration and guides -= Adding a custom Maven Mirror to {product_name} images += Configuring Maven Mirrors and Quarkus Registry for {product_name} Images :compat-mode!: // Metadata: :description: Adding a custom maven mirror to images :keywords: maven, mirror, central, sonatype // links :maven_mirror_guide: https://maven.apache.org/guides/mini/guide-mirror-settings.html +:quarkus_registry_guide: https://quarkus.io/guides/extension-registry-user -This document describes how to configure the internal Maven settings on {product_name} images so that the maven process can access a custom mirror registry. +This guide explains how to configure Maven mirrors and Quarkus extension registries to support restricted or offline environments when building and running workflows. By default either the {product_name} Builder and Devmode images have all the required Java libraries to run. In some scenarios, such as adding a custom Quarkus Extension, the internal system will require to access the Maven Central registry. @@ -30,7 +31,7 @@ metadata: annotations: sonataflow.org/restartBuild: true <1> spec: - # supreessed for brevity + # suppressed for brevity envs: - name: MAVEN_MIRROR_URL <2> value: http://my.company.registry.local @@ -87,7 +88,7 @@ spec: env: - name: MAVEN_MIRROR_URL <1> value: http://my.company.registry.local - flow: #supreessed for brevity + flow: #suppressed for brevity ---- 1. The environment variable required to configure the maven URL @@ -101,7 +102,7 @@ To know more about running workflows in development mode, see xref:cloud/operato == Configuring the Maven Mirror on a custom image -When building workflows in an external system using the {product_name} Builder image, you may set this environment variable preferrebly in your build context. Alternatively, you may also set it in your custom container file. +When building workflows in an external system using the {product_name} Builder image, you may set this environment variable preferably in your build context. Alternatively, you may also set it in your custom container file. .Custom Container File with Maven Mirror set as an environment variable [source,Dockerfile,subs="attributes+"] @@ -124,3 +125,64 @@ FROM {sonataflow_builder_imagename}:{operator_version} AS builder # The Maven Mirror URL will be passed as an argument to the build process. ARG MAVEN_MIRROR_URL ---- + +== Quarkus Registry Support in Builder and Devmode Images + +{product_name}'s builder and devmode images support offline builds by preloading the link:{quarkus_registry_guide}[Quarkus extension registry]. This enhancement allows adding Quarkus extensions without accessing the public `registry.quarkus.io`, which is particularly beneficial in air-gapped or restricted environments. + +[IMPORTANT] +==== +The extension should be accessible through your Maven mirror, the images are **not** prepackaged with all extensions in the registry. +==== + +=== Overriding the Quarkus Registry Configuration + +To customize the Quarkus registry behavior, you can provide your own `.quarkus/config.yaml` file and specify its path using the `QUARKUS_REGISTRY_CONFIG_PATH` environment variable. + +.Custom container file overriding the default Quarkus Registry configuration file +[source,Dockerfile,subs="attributes+"] +---- +FROM {sonataflow_builder_imagename}:{operator_version} AS builder + +# Optional: Add Quarkus extensions +ARG QUARKUS_EXTENSIONS +ARG QUARKUS_ADD_EXTENSION_ARGS +ARG MAVEN_ARGS_APPEND + +# Copy application source +COPY --chown=1001 . ./resources + +# Provide a custom Quarkus registry configuration using a path inside the container context +ENV QUARKUS_REGISTRY_CONFIG_PATH=./resources/.quarkus/config.yaml + +RUN /home/kogito/launch/build-app.sh ./resources +---- + +In this example, the `.quarkus/config.yaml` file is placed within the `resources` directory of your project. The `build-app.sh` script will detect the `QUARKUS_REGISTRY_CONFIG_PATH` environment variable and copy the specified configuration file to the appropriate location inside the container. + +Overriding the Quarkus registry configuration file is particularly useful when you have a local registry mirror or need to connect to other registry such as `registry.quarkus.redhat.com`. + +[NOTE] +==== +If `QUARKUS_REGISTRY_CONFIG_PATH` is not set, the builder will fall back to the default registry configuration shipped with the image, typically `registry.quarkus.io`. +==== + +=== Verifying Offline Builds + +To ensure that your build process does not access the external Quarkus registry, you can run Maven in offline mode and monitor network activity: + +[source,shell,subs="attributes+"] +---- +mvn -o clean install | grep registry.quarkus.io +---- + +If the build is correctly configured for offline mode, there should be no output from the `grep` command, indicating that `registry.quarkus.io` was not accessed. + +== Additional Resources + +* xref:cloud/operator/deployment-profile.adoc[] +* xref:cloud/operator/developing-workflows.adoc[] +* xref:cloud/operator/build-and-deploy-workflows.adoc[] +* xref:cloud/operator/building-custom-images.adoc[] + +include::../../../pages/_common-content/report-issue.adoc[] \ No newline at end of file --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
