Configuring Maven Mirrors and Quarkus Registry for SonataFlow Images

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 SonataFlow 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.

In case you are running under restricted network access, you may point the container to access an internal mirror instead. See more information about this procedure on the Guide to Mirror Settings on the Maven documentation.

Configuring the Maven Mirror on the Operator

Adding a Maven Mirror when building workflows

You may edit either the SonataFlowBuild or SonataFlowPlatform custom resources and add the variable MAVEN_MIRROR_URL.

Maven Mirror configuration example on SonataFlowBuild

apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowBuild
metadata:
  name: my-workflow
  annotations:
    sonataflow.org/restartBuild: true (1)
spec:
  # suppressed for brevity
  envs:
    - name: MAVEN_MIRROR_URL (2)
      value: http://my.company.registry.local

Annotation to force the existing build to trigger a new execution
The environment variable required to configure the maven URL

Changing the SonataFlowBuild it will only impact the given workflow instance it represents. In this case, a workflow instance in the same namespace with the name my-workflow.

For more information about restarting the build see Restarting a Build.

To change the Maven mirror for all build instances for the preview profile, you have to change the given SonataFlowPlatform within the same namespace.

Maven Mirror configuration example on SonataFlowPlatform

apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowPlatform
metadata:
  name: my-platform
spec:
  build:
    template:
      envs:
        - name: MAVEN_MIRROR_URL (1)
          value: http://my.company.registry.local

The environment variable required to configure the maven URL

When a workflow builder instance runs, it will use this information to configure the internal Maven settings file to use this URL as the default mirror to external locations, such as the Maven Central repository.

For more information about building workflows with the operator see Building and Deploying Workflows with the Operator.

Adding a Maven Mirror when deploying on Development Mode

When deploying workflows in devmode, you may also add the Maven Mirror to the SonataFlow custom resource.

Maven Mirror configuration example on SonataFlow

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

The environment variable required to configure the maven URL

Only workflows deployed with dev profile can use Maven Mirrors. Other deployment models only execute compiled code which won’t need to connect to a Maven registry to run.

To know more about running workflows in development mode, see Developing Workflows with the Operator.

Configuring the Maven Mirror on a custom image

When building workflows in an external system using the SonataFlow 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

FROM docker.io/apache/incubator-kie-sonataflow-builder:main AS builder

# Content supressed for brevity

# The Maven Mirror URL set as an env var during the build process.
ENV MAVEN_MIRROR_URL=http://my.company.registry.local

Custom Container File with Maven Mirror set as an argument

FROM docker.io/apache/incubator-kie-sonataflow-builder:main AS builder

# Content supressed for brevity

# 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

SonataFlow’s builder and devmode images support offline builds by preloading the 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.

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

FROM docker.io/apache/incubator-kie-sonataflow-builder:main 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.

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:

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

Found an issue?

If you find an issue or any misleading information, please feel free to report it here. We really appreciate it!