DES-6613 Updated documentation.

* Clarified requirements and limitations
* Added an upgrade guide explaining how to use build.py in existing pipelines
* Updated versions

Author: zlogic

README.md

@@ -4,7 +4,7 @@
 
 The Mendix Buildpack for Docker (aka docker-mendix-buildpack) is an **example project** you can use to build and run your Mendix Application in a [Docker](https://www.docker.com/) container.
 
-**⚠️ Warning** If your pipeline is based on Docker Buildpack V4 or an earlier version, see the [upgrading from Docker Buildpack v4](upgrading-from-v4.md) document. To use Docker Buildpack v5, some changes will be required in your build process.
+**⚠️ Warning** If your pipeline is based on Docker Buildpack v5 or an earlier version, see the [upgrading from Docker Buildpack v5](upgrading-from-v6.md) document. To use Docker Buildpack v6, some changes will be required in your build process.
 
 For a Kubernetes native solution to run Mendix apps, see [Mendix for Private Cloud](https://www.mendix.com/evaluation-guide/app-lifecycle/mendix-for-private-cloud/).
 
@@ -42,8 +42,13 @@ This project is a goto reference for the following scenarios :
 * Docker 20.10 (Installation [here](https://docs.docker.com/engine/installation/))
   * Earlier Docker versions are no longer compatible because they don't support multistage builds.
     To use Docker versions below 20.10, download an earlier Mendix Docker Buildpack release, such as [v2.3.2](https://github.com/mendix/docker-mendix-buildpack/releases/tag/v2.3.2)
+  * Alternatively, Podman version 5 or later
 * Python 3.8
-* For preparing, a local installation of `curl`
+  * No additional dependencies are needed
+* A UNIX-like operating system, such as Linux or macOS, or Windows Subsystem for Linux
+* An x86-64 (AMD64) based CPU
+  * ARM64 CPUs are not fully supported
+* For running the example tests, a local installation of `curl`
 * For local testing, make sure you can run the [docker-compose command](https://docs.docker.com/compose/install/)
 * A Mendix app based on Mendix 8 or a later version
 
@@ -52,7 +57,7 @@ This project is a goto reference for the following scenarios :
 ### Preparation: rootfs
 
 To save build time, the build pack needs a prebuilt rootfs containing the base OS and additional packages.
-This rootfs is based on [Red Hat Universal Base Image 8 minimal](https://developers.redhat.com/articles/ubi-faq) image.
+This rootfs is based on [Red Hat Universal Base Image 9 minimal](https://developers.redhat.com/articles/ubi-faq) image.
 
 To build the rootfs, run the following commands
 
@@ -127,7 +132,7 @@ docker build \
 
 For build you can provide next arguments:
 
-- **BUILD_PATH** indicates where the application model is located. It is a root directory of an unzipped .MDA or .MPK file. In the latter case, this is the directory where your .MPR file is located. Must be within [build context](https://docs.docker.com/engine/reference/commandline/build/#extended-description). Defaults to `./project`.
+- **BUILD_PATH** indicates where the application model is located. It is a root directory of an unzipped .MDA or .MPK file. In the latter case, this is the directory where your .MPR file is located. Must be within [build context](https://docs.docker.com/engine/reference/commandline/build/#extended-description). Should not be used when using the `build.py` script. Defaults to `./project`.
 - **ROOTFS_IMAGE** is a type of rootfs image. Defaults to `mendix-rootfs:app` (a locally prebuilt image).
 - **BUILDER_ROOTFS_IMAGE** is a type of rootfs image used for downloading the Mendix app dependencies and compiling the Mendix app from source. Defaults to `mendix-rootfs:builder` (a locally prebuilt image).
 - **EXCLUDE_LOGFILTER** will exclude the `mendix-logfilter` binary from the resulting Docker image if set to `true`. Defaults to `true`. Excluding `mendix-logfilter` will reduce the image size and remove a component that's not commonly used; the `LOG_RATELIMIT` environment variable option will be disabled.
@@ -398,9 +403,7 @@ Contributions are welcomed:
 
 ### Build Details
 
-This was built with the following:
-
-* Docker version 20.10
+Docker Buildpack is tested by running a Github Actions pipeline.
 
 ### Versioning
 

upgrading-from-v5.md

@@ -0,0 +1,59 @@
+# Upgrading from Docker Buildpack v5
+
+Docker Buildpack v6 contains a breaking change and might require some changes in your CI/CD pipeline:
+
+Building Mendix projects from source (\*.mpr or \*.mpk files) is now done using a build.py script.
+If your CI/CD pipeline uses Docker Buildpack to build \*.mda files (compiled Mendix apps), no further changes are needed.
+
+If you're upgrading from Docker Buildpack v4 (or an older version), you'll also need to follow the [upgrading from Docker Buildpack v4](upgrading-from-v4.md) instructions.
+
+## Using the build.py script
+
+Docker Buildpack v6 no longer uses CF Buildpack to compile MPR (or MPK) files - to continue supporting newer versions of Mendix, Java and the base OS.
+Instead, a custom `build.py` script will:
+
+1. Prepare a clean [Docker context](https://docs.docker.com/build/concepts/context/) in the path specified by `--destination`. All files required to build the app image will be copied to this destination.
+2. Detect the file type of the source path specified by the `--source` arg (an MPK file, an MPR file, an MDA file or an unpacked MDA directory).
+3. If necessary (`--source` specifies project that needs to be compiled)
+   1. Create an image containing [mxbuild](https://docs.mendix.com/refguide/mxbuild/) and its dependencies.
+   2. Run an `mxbuild` in a container, and copy the resulting MDA contents to the destination path specified by `--destination`.
+4. Otherwise (`--source` specifies a path to an MDA file or unpacked MDA directory), `build.sh` will just copy the MDA contents to the destination path specified by `--destination`.
+
+Once the `build.py` script runs successfully, the path specified by `--destination` will contain a Docker context and everything needed to run a `docker build` command.
+
+### Updating an existing pipeline to use build.py
+
+There instructions are provided as a reference, based on a typical pipeline. Your CI/CD pipeline might be different - for support with updating a custom pipeline, please check the [Mendix Support Policy](https://www.mendix.com/evaluation-guide/evaluation-learning/support/).
+
+1. Verify your pipeline image or runner has Python 3.8 available, and uses a UNIX-like operating system (Linux, macOS or Windows Subsystem for Linux).
+2. Locate the `docker build` step in your CI/CD pipeline that builds the app image. This should be the step that builds the Mendix app, and not the rootfs or its dependencies. Any `docker build` commands that build the rootfs should not be changed.
+3. Before the `docker build` step, add the following lines (replacing `<path-to-source>` with the path to the project source, and `<destination-dir>` with an empty/temporary writable path):
+   ```shell
+   ./build.py --source <path-to-source> --destination <destination-dir> build-mda-dir
+   ```
+4. In the `docker build` step:
+    * Remove `--build-arg BUILD_PATH` args.
+    * Remove `-f` and `--file` args specifying a Dockerfile, if they exist.
+    * Update the [Docker context](https://docs.docker.com/build/concepts/context/) path to the `<destination-dir>`.
+
+After the update, your pipeline might look like this:
+
+```shell
+# Preparation steps
+# Downloag Docker Buildpack
+DOCKER_BUILDPACK_VERSION=v6.0.0
+curl -LJ -o - https://github.com/mendix/docker-mendix-buildpack/archive/refs/tags/${DOCKER_BUILDPACK_VERSION}.tar.gz | tar --strip-components=1 -xvz
+# Checkout the Mendix app source
+git clone <mendix-app-git> mendix-app-src
+# Build the Mendix app from mendix-app-src to a temporary location
+./build.py --source mendix-app-src --destination /tmp/docker-buildpack-context build-mda-dir
+# Prepare and push the Docker image, using /tmp/docker-buildpack-context as the Docker context
+docker build --tag example.com/mendix-app:latest /tmp/docker-buildpack-context
+docker push example.com/mendix-app:latest
+# Follow-up steps
+```
+
+# Other changes
+
+Docker Buildpack v6 switched from `ubi8` to `ubi9` images ([Red Hat Universal Base Images](https://developers.redhat.com/articles/ubi-faq) whenever possible.
+Building Mendix 8 and 9 apps still uses `ubi8`, as those versions depend on an older version of Mono that doesn't work in newer operating systems.