Adding Maven Build Cache Extension as opt-in feature

Closes #20882

.github/workflows/js-ci.yml

@@ -47,7 +47,7 @@ jobs:
 
       - name: Build Keycloak
         run: |
-          mvn clean install --batch-mode --errors -DskipTests -DskipTestsuite -DskipExamples -DskipAccount2 -DskipCommon -Pdistribution
+          ./mvnw clean install --batch-mode --errors -DskipTests -DskipTestsuite -DskipExamples -DskipAccount2 -DskipCommon -Pdistribution
           mv ./quarkus/dist/target/keycloak-999.0.0-SNAPSHOT.tar.gz ./keycloak-999.0.0-SNAPSHOT.tar.gz
 
       - name: Upload Keycloak dist

.github/workflows/operator-ci.yml

@@ -90,7 +90,7 @@ jobs:
 
       - name: Test operator running locally
         run: |
-          mvn install -Poperator -pl :keycloak-operator -am \
+          ./mvnw install --batch-mode -Poperator -pl :keycloak-operator -am \
               -Dquarkus.kubernetes.image-pull-policy=IfNotPresent \
               -Doperator.keycloak.image=keycloak:${{ env.version_local }} \
               -Dtest.operator.custom.image=custom-keycloak:${{ env.version_local }} \
@@ -138,7 +138,7 @@ jobs:
       - name: Test operator running in cluster
         run: |
           eval $(minikube -p minikube docker-env)
-          mvn install -Poperator -pl :keycloak-operator -am \
+          ./mvnw install --batch-mode -Poperator -pl :keycloak-operator -am \
               -Dquarkus.container-image.build=true \
               -Dquarkus.kubernetes.image-pull-policy=IfNotPresent \
               -Doperator.keycloak.image=keycloak:${{ env.version_remote }} \

.github/workflows/snyk-analysis.yml

@@ -34,7 +34,7 @@ jobs:
 
       - name: Check for vulnerabilities in Operator
         run: |
-          mvn -Poperator -pl operator -am -DskipTests clean install
+          ./mvnw -Poperator -pl operator -am -DskipTests clean install --batch-mode
           snyk test --policy-path=${GITHUB_WORKSPACE}/.github/snyk/.snyk --all-projects --prune-repeated-subdependencies --exclude=tests --sarif-file-output=operator-report.sarif operator
         continue-on-error: true
         env:

.mvn/extensions.xml

@@ -0,0 +1,25 @@
+<!--
+  ~ Copyright 2022 Red Hat, Inc. and/or its affiliates
+  ~ and other contributors as indicated by the @author tags.
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~ http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+
+<extensions>
+    <!-- https://maven.apache.org/extensions/maven-build-cache-extension/ -->
+    <extension>
+        <groupId>org.apache.maven.extensions</groupId>
+        <artifactId>maven-build-cache-extension</artifactId>
+        <version>1.0.1</version>
+    </extension>
+</extensions>

.mvn/maven-build-cache-config.xml

@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!--
+  ~ Copyright 2022 Red Hat, Inc. and/or its affiliates
+  ~ and other contributors as indicated by the @author tags.
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~ http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+
+<cache xmlns="http://maven.apache.org/BUILD-CACHE-CONFIG/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       xsi:schemaLocation="http://maven.apache.org/BUILD-CACHE-CONFIG/1.0.0 https://maven.apache.org/xsd/build-cache-config-1.0.0.xsd">
+    <configuration>
+        <enabled>false</enabled>
+        <hashAlgorithm>XX</hashAlgorithm>
+    </configuration>
+    <input>
+        <global>
+            <!-- matching all files, as there is no good file pattern to match files in META-INF/services by their file name -->
+            <glob>{*}</glob>
+        </global>
+        <plugins>
+            <plugin groupId="com.github.eirslett" artifactId="frontend-maven-plugin">
+                <dirScan>
+                    <excludes>
+                        <exclude tagName="installDirectory" />
+                    </excludes>
+                </dirScan>
+            </plugin>
+        </plugins>
+    </input>
+    <executionControl>
+        <runAlways>
+            <plugins>
+                <plugin artifactId="maven-failsafe-plugin"/>
+            </plugins>
+            <goalsLists>
+                <goalsList artifactId="maven-install-plugin">
+                    <goals>
+                        <goal>install</goal>
+                    </goals>
+                </goalsList>
+            </goalsLists>
+        </runAlways>
+        <reconcile>
+            <plugins>
+                <plugin artifactId="maven-surefire-plugin" goal="test">
+                    <reconciles>
+                        <!-- might reconsider later: if not putting them here, it might be simpler to run local tests incrementally -->
+                        <reconcile propertyName="skip" skipValue="true"/>
+                        <reconcile propertyName="skipExec" skipValue="true"/>
+                        <reconcile propertyName="skipTests" skipValue="true"/>
+                        <reconcile propertyName="testFailureIgnore" skipValue="true"/>
+                    </reconciles>
+                </plugin>
+            </plugins>
+        </reconcile>
+    </executionControl>
+</cache>

.mvn/wrapper/maven-wrapper.properties

@@ -14,5 +14,5 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.8.6/apache-maven-3.8.6-bin.zip
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.2/apache-maven-3.9.2-bin.zip
 wrapperUrl=https://repo.maven.apache.org/maven2/org/apache/maven/wrapper/maven-wrapper/3.1.0/maven-wrapper-3.1.0.jar

adapters/oidc/js/pom.xml

@@ -18,6 +18,10 @@
         <js.projectDir>../../../js</js.projectDir>
         <js.adapter.projectDir>${js.projectDir}/libs/keycloak-js</js.adapter.projectDir>
         <js.adapter.distDir>${js.adapter.projectDir}/dist</js.adapter.distDir>
+        <!-- as the frontend-maven-plugin depends on workingDirectory, list all parts which should be ignored from the checksum -->
+        <maven.build.cache.exclude.1>${maven.multiModuleProjectDirectory}/js/libs/keycloak-js/node_modules</maven.build.cache.exclude.1>
+        <!-- TODO: this is almost correct, as the DIST folder includes also two source files -->
+        <maven.build.cache.exclude.2>${maven.multiModuleProjectDirectory}/js/libs/keycloak-js/dist</maven.build.cache.exclude.2>
     </properties>
 
     <build>

docs/building.md

@@ -1,26 +1,12 @@
 ## Building from source
 
-Ensure you have JDK 11 (or newer), Maven 3.6.3 (or newer) and Git installed
+Ensure you have JDK 11 (or newer) and Git installed
 
     java -version
-    mvn -version
     git --version
 
-**NOTE**
+Instead of using a locally installed Maven, call the Maven wrapper script `mvnw` in the main folder of the project.
-
+This will use the Maven version which is supported by this project.
-If you use Maven 3.8.1 or newer, please add the following mirror to your local
-`~/.m2/settings.xml` to avoid build errors:
-```
-<mirrors>
-  <mirror>
-    <id>jboss-public-repository-group-https</id>
-    <mirrorOf>jboss-public-repository-group</mirrorOf>
-    <name>Jboss public https</name>
-    <url>https://repository.jboss.org/nexus/content/groups/public/</url>
-  </mirror>
-</mirrors>
-```
-See [KEYCLOAK-17812](https://issues.redhat.com/browse/KEYCLOAK-17812) for more details.
 
 ---    
 First clone the Keycloak repository:
@@ -30,19 +16,19 @@ First clone the Keycloak repository:
     
 To build Keycloak run:
 
-    mvn clean install
+    ./mvnw clean install
     
 This will build all modules and run the testsuite. 
 
 To build the ZIP distribution run:
 
-    mvn clean install -Pdistribution
+    ./mvnw clean install -Pdistribution
     
 Once completed you will find distribution archives in `distribution`.
 
 To build only the server run:
 
-    mvn -Pdistribution -pl distribution/server-dist -am -Dmaven.test.skip clean install
+    ./mvnw -Pdistribution -pl quarkus/dist -am -Dmaven.test.skip clean install
 
 ---
 **NOTE**
@@ -51,6 +37,16 @@ Classes from `org.keycloak.testsuite.*` packages aren't suitable to be used in p
 
 ---
 
+This project contains opt-in support for incremental Maven builds using the [Apache Maven Build Cache Extension](https://github.com/apache/maven-build-cache-extension) which is disabled by default.
+
+To enable it for a single Maven command execution, enable it as follows: 
+
+    ./mvnw -D -Dmaven.build.cache.enabled=true ...
+
+To enable it by default, add it to the `MAVEN_OPTS` environment variable:
+
+    export MAVEN_OPTS="-Dmaven.build.cache.enabled=true"
+
 ### Building Quarkus Distribution
 
 Please, take a look at this [documentation](../quarkus/README.md).
@@ -59,19 +55,12 @@ Please, take a look at this [documentation](../quarkus/README.md).
 
 To start Keycloak during development first build as specified above, then run:
 
-    mvn -f testsuite/utils/pom.xml exec:java -Pkeycloak-server 
+    ./mvnw -f testsuite/utils/pom.xml exec:java -Pkeycloak-server 
 
 When running testsuite, by default an account with username `admin` and password `admin` will be created within the master realm at start.
 
-To start Keycloak from the server distribution first build the distribution it as specified above, then run:
-
-    tar xfz distribution/server-dist/target/keycloak-<VERSION>.tar.gz
-    cd keycloak-<VERSION>
-    bin/standalone.sh
-    
 To stop the server press `Ctrl + C`.
 
-
 ## Working with the codebase
 
 We don't currently enforce a code style in Keycloak, but a good reference is the code style used by WildFly. This can be 
@@ -97,6 +86,6 @@ classes. E.g. in IntelliJ IDEA use `Build → Build Project` instead of `Build
 If you are building the Operator from your IDE, make sure to build the project with the `operator` profile enabled in Maven
 as it's excluded by default:
 
-    mvn clean install -Poperator -DskipTests
+    ./mvnw clean install -Poperator -DskipTests
 
 ---

js/pom.xml

@@ -22,6 +22,13 @@
         <module>libs/keycloak-js</module>
     </modules>
 
+    <properties>
+        <!-- The JavaScript projects use the non-standard 'src' folder for their sources, therefore, name it here explicitly -->
+        <maven.build.cache.input.1>src</maven.build.cache.input.1>
+        <!-- The child projects will package from the 'dist' folder, which is listed as a resource, but isn't a source folder -->
+        <maven.build.cache.exclude.1>${project.basedir}/dist</maven.build.cache.exclude.1>
+    </properties>
+
     <build>
         <plugins>
             <plugin>

quarkus/README.md

@@ -33,7 +33,7 @@ When a build from the project root directory is started, this module is only ena
 
 To build this module and produce the artifacts to run a server, you first need to build the main codebase once. This step will put required modules of keycloak into your local maven cache in package `org.keycloak`:
 
-    mvn -f ../pom.xml clean install -DskipTestsuite -DskipExamples -DskipTests
+    ../mvnw -f ../pom.xml clean install -DskipTestsuite -DskipExamples -DskipTests
 
 This build can take some time, usually around two to four minutes depending on your hardware, and even longer depending on the maven packages that need to be downloaded and installed to the cache.
 
@@ -41,13 +41,13 @@ This build can take some time, usually around two to four minutes depending on y
 
 After the main codebase is built, you can build the quarkus distribution, including the zip and tar.gz files, by invoking the following command:
     
-    mvn clean install -DskipTests
+    ../mvnw clean install -DskipTests
 
 This command produces the distribution artifacts as ZIP and TAR file. The artifacts for the quarkus distribution will be available at the `/dist/target` subdirectory afterwards.
 
 As an alternative, you can build the distribution artifacts directly without a rebuild of the code by running the following command:
 
-    mvn -f dist/pom.xml clean install
+    ../mvnw -f dist/pom.xml clean install
 
 ## Running in Keycloak development mode
 When you start Keycloak in production mode, the HTTP port is disabled by default, and you need to provide the key material to configure HTTPS, a hostname and other configuration suitable for production. 
@@ -66,13 +66,13 @@ Please make sure to read our [Contribution Guidelines](../CONTRIBUTING.md) befor
 
 To run the server in Quarkus' development mode, invoke the following command:
 
-    mvn -f server/pom.xml compile quarkus:dev -Dquarkus.args="start-dev"
+    ../mvnw -f server/pom.xml compile quarkus:dev -Dquarkus.args="start-dev"
 
 You will be able to attach your debugger to port `5005`.
 
 For debugging the build steps right after start, you can suspend the JVM by running:
 
-    mvn -f server/pom.xml -Dsuspend=true compile quarkus:dev -Dquarkus.args="start-dev"
+    ../mvnw -f server/pom.xml -Dsuspend=true compile quarkus:dev -Dquarkus.args="start-dev"
 
 When running using `quarkus:dev` you are able to do live coding whenever you change / add code in the `server` module, for example when creating a new custom provider.
 
@@ -102,10 +102,12 @@ There are also some container based tests to check if Keycloak starts using one
 
 These tests are disabled by default. They using Quarkus development mode predefined database containers by default and can be run in the `tests` subdirectory by using e.g. 
 
-    mvn clean install -Dkc.test.storage.database=true -Dtest=MariaDBStartDatabaseTest
+    ../mvnw clean install -Dkc.test.storage.database=true -Dtest=MariaDBStartDatabaseTest
 
 to spin up a MariaDB container and start Keycloak with it.
 
-To use a specific database container image, use the option -Dkc.db.postgresql.container.image to specify the image tag of the postgres image to use or -Dkc.db.mariadb.container.image=<name:tag> for mariadb.
+To use a specific database container image, use the option `-Dkc.db.postgresql.container.image` to specify the image tag of the postgres image to use or `-Dkc.db.mariadb.container.image=<name:tag>` for mariadb.
+
 Example:
-mvn clean install -Dkc.test.storage.database=true -Dtest=PostgreSQLDistTest -Dkc.db.postgresql.container.image=postgres:
+
+    ../mvnw clean install -Dkc.test.storage.database=true -Dtest=PostgreSQLDistTest -Dkc.db.postgresql.container.image=postgres:alpine

themes/pom.xml

@@ -16,6 +16,11 @@
         <dir.common>src/main/resources/theme/keycloak/common/resources</dir.common>
         <dir.account2>src/main/resources/theme/keycloak.v2/account/src</dir.account2>
         <args.npm.install>ci --no-optional --ignore-scripts</args.npm.install>
+        <!-- ignore folders for incremental builds by the maven build cache plugin -->
+        <maven.build.cache.exclude.1>${project.basedir}/src/main/resources/theme/keycloak/common/resources/node_modules</maven.build.cache.exclude.1>
+        <maven.build.cache.exclude.2>${project.basedir}/src/main/resources/theme/keycloak/common/resources/web_modules</maven.build.cache.exclude.2>
+        <maven.build.cache.exclude.3>${project.basedir}/src/main/resources/theme/keycloak.v2/account/src/node_modules</maven.build.cache.exclude.3>
+        <maven.build.cache.exclude.4>${project.basedir}/src/main/resources/theme/keycloak.v2/account/src/web_modules</maven.build.cache.exclude.4>
     </properties>
 
     <build>