Merge pull request #21770 from cescoffier/quarkus-micro-image-doc

Document how to extend the quarkus-micro-image

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

@@ -479,6 +479,8 @@ You can read more about UBI images on:
 * https://catalog.redhat.com/software/container-stacks/detail/5ec53f50ef29fd35586d9a56[Red Hat Universal Base Image 8]
 
 UBI images can be used without any limitations.
+
+xref:quarkus-runtime-base-image.adoc[This page] explains how to extend the `quarkus-micro` image when your application has specific requirements.
 ====
 
 Then, if you didn't delete the generated native executable, you can build the docker image with:

docs/src/main/asciidoc/quarkus-runtime-base-image.adoc

@@ -0,0 +1,102 @@
+////
+This guide is maintained in the main Quarkus repository
+and pull requests should be submitted there:
+https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
+////
+= Quarkus Base Runtime Image
+
+include::./attributes.adoc[]
+
+To ease the containerization of native executables, Quarkus provides a base image providing the requirements to run these executables.
+The `quarkus-micro-image:1.0` image is:
+
+* small (based on `ubi8-micro`)
+* designed for containers
+* contains the right set of dependencies (glibc, libstdc++, zlib)
+* support upx-compressed executables (more details on the xref:upx.adoc[enabling compression documentation])
+
+== Using the base image
+
+In your `Dockerfile`, just use:
+
+[source, dockerfile]
+----
+FROM quay.io/quarkus/quarkus-micro-image:1.0
+WORKDIR /work/
+COPY target/*-runner /work/application
+RUN chmod 775 /work
+EXPOSE 8080
+CMD ["./application", "-Dquarkus.http.host=0.0.0.0"]
+----
+
+== Extending the image
+
+Your application may have additional requirements.
+For example, if you have an application that requires `libfreetype.so`, you need to copy the native libraries to the container.
+In this case, you need to use a multi-stage `dockerfile` to copy the required libraries:
+
+[source, dockerfile]
+----
+# First stage - install the dependencies in an intermediate container
+FROM registry.access.redhat.com/ubi8/ubi-minimal:8.5 as BUILD
+RUN microdnf install freetype
+
+# Second stage - copy the dependencies
+FROM quay.io/quarkus/quarkus-micro-image:1.0
+COPY --from=BUILD \
+   /lib64/libfreetype.so.6 \
+   /lib64/libbz2.so.1 \
+   /lib64/libpng16.so.16 \
+   /lib64/
+
+WORKDIR /work/
+COPY target/*-runner /work/application
+RUN chmod 775 /work
+EXPOSE 8080
+CMD ["./application", "-Dquarkus.http.host=0.0.0.0"]
+----
+
+If you need to have access to the full AWT support, you need more than just `libfreetype.so`, but also the font and font configurations:
+
+[source, dockerfile]
+----
+# First stage - install the dependencies in an intermediate container
+FROM registry.access.redhat.com/ubi8/ubi-minimal:8.5 as BUILD
+RUN microdnf install freetype fontconfig
+
+# Second stage - copy the dependencies
+FROM quay.io/quarkus/quarkus-micro-image:1.0
+COPY --from=BUILD \
+   /lib64/libfreetype.so.6 \
+   /lib64/libgcc_s.so.1 \
+   /lib64/libbz2.so.1 \
+   /lib64/libpng16.so.16 \
+   /lib64/libm.so.6 \
+   /lib64/libbz2.so.1 \
+   /lib64/libexpat.so.1 \
+   /lib64/libuuid.so.1 \
+   /lib64/
+
+COPY --from=BUILD \
+   /usr/lib64/libfontconfig.so.1 \
+   /usr/lib64/
+
+COPY --from=BUILD \
+    /usr/share/fonts /usr/share/fonts
+
+COPY --from=BUILD \
+    /usr/share/fontconfig /usr/share/fontconfig
+
+COPY --from=BUILD \
+    /usr/lib/fontconfig /usr/lib/fontconfig
+
+COPY --from=BUILD \
+     /etc/fonts /etc/fonts
+
+WORKDIR /work/
+COPY target/*-runner /work/application
+RUN chmod 775 /work
+EXPOSE 8080
+CMD ["./application", "-Dquarkus.http.host=0.0.0.0"]
+----
+