Merge pull request #2859 from loicmathieu/feat/document_multi_stage_b…

…uild

doc: add multi stage build to the native guide

docs/src/main/asciidoc/building-native-image-guide.adoc

@@ -58,6 +58,11 @@ case; it now has to be installed as a second step after GraalVM itself is instal
 to do so.
 ====
 
+[TIP]
+====
+If you cannot install GraalVM, you can use a multi-stage Docker build to run Maven inside a Docker container that embeds GraalVM. There is an explanation of how to do this at the end of this guide.
+====
+
 == Solution
 
 We recommend that you follow the instructions in the next sections and package the application step by step.
@@ -206,7 +211,7 @@ that does not call your HTTP endpoints, it's probably not a good idea to run the
 If you share your test class between JVM and native execusions like we advise above, you can mark certain tests
 with the `@DisabledOnSubstrate` annotation in order to only run them on the JVM.
 
-== Producing a container
+== Creating a container
 
 IMPORTANT: Before going further, be sure to have a working container runtime (Docker, podman) environment.
 
@@ -266,6 +271,52 @@ docker run -i --rm -p 8080:8080 quarkus-quickstart/getting-started
 
 NOTE: Interested by tiny Docker images, check the {quarkus-images-url}/graalvm-{graalvm-version}/distroless[distroless] version.
 
+== Creating a container with a multi-stage Docker build
+
+The previous section showed you how to build a native executable using Maven, but implicitly required that the proper GraalVM version be installed on the building machine (be it your local machine or your CI/CD infrastructure).
+
+In cases where the GraalVM requirement cannot be met, you can use Docker to perform the Maven build by using a multi-stage Docker build. A multi-stage Docker build is like two Dockerfile files combined in one, the first is used to build the artifact used by the second. 
+
+In this guide we will use the first stage to generate the native executable using Maven and the second stage to create our runtime image.
+
+[source,dockerfile]
+----
+## Stage 1 : build with maven builder image with native capabilities
+FROM quay.io/quarkus/centos-quarkus-maven:graalvm-{graalvm-version} AS build
+COPY src /usr/src/app/src
+COPY pom.xml /usr/src/app
+RUN mvn -f /usr/src/app/pom.xml -Pnative clean package
+
+## Stage 2 : create the docker final image
+FROM registry.access.redhat.com/ubi8/ubi-minimal
+WORKDIR /work/
+COPY --from=build /usr/src/app/target/*-runner /work/application
+RUN chmod 775 /work
+EXPOSE 8080
+CMD ["./application", "-Dquarkus.http.host=0.0.0.0"]
+----
+
+
+Save this file in `src/main/docker/Dockerfile.multistage` as it is not included in the getting started quickstart.
+
+[WARNING]
+====
+Before launching our Docker build, we need to update the default `.dockerignore` file as it filters everything except the `target` directory and as we plan to build inside a container we need to be able to copy the `src` directory. So edit your `.dockerignore` and remove or comment its content.
+====
+
+[source,shell]
+----
+docker build -f src/main/docker/Dockerfile.multistage -t quarkus-quickstart/getting-started .
+----
+
+And finally, run it with:
+
+[source,shell]
+----
+docker run -i --rm -p 8080:8080 quarkus-quickstart/getting-started
+----
+
+
 == What's next?
 
 This guide covered the creation of a native (binary) executable for your application.