build.Containerfile: reproducible reference build via containerization

Currently, buildah, Podman and Docker are supported.

The goals of the reference build are:

- Make our release process more transparent
- Improve reproducibility by shielding our build from the hosts
  environment
- Reduce the trust necessary for running our build by shielding
  the hosts environment from possible side effects of our build

Note both the signing and the uploading of release artifacts are out
of scope for the reference build.

.dockerignore

@@ -0,0 +1,20 @@
+build.Containerfile
+**/.*
+
+# bitcoinj
+**/*.wallet
+**/*.spvchain
+
+# Gradle
+**/build/
+gradle/
+gradlew*
+
+# IntelliJ
+**/*.iml
+.idea/
+
+# Eclipse
+**/.project
+**/.classpath
+**/.settings/

README.adoc

@@ -74,6 +74,12 @@ To dump the state of the wallet in `~/bitcoinj/bitcoinj-test.wallet` with the te
 
 NOTE: These instructions are for macOS/Linux, for Windows use the `wallettool/build/install/wallet-tool/bin/wallet-tool.bat` batch file with the equivalent Windows command-line commands and options.
 
+### Building the reference build
+
+Our reference build (which is also used for our releases) is running within a container to provide good reproducibility.
+Buildah 1.26+, Podman 4.1+ and Docker (with BuildKit) are supported. We tested various combinations of host OSes
+(Debian, Ubuntu, macOS, Windows+WSL) and architectures (amd64, arm64). For usage instructions see `build.Containerfile`.
+
 ### Example applications
 
 These are found in the `examples` module.

build.Containerfile

@@ -0,0 +1,52 @@
+#
+# Reproducible reference build
+#
+# Usage:
+#
+# buildah build --file build.Containerfile --output <outputdir> .
+# or
+# podman build --file build.Containerfile --output <outputdir> .
+# or
+# docker build --file build.Containerfile --output <outputdir> .
+#
+# The build artifacts are written to the specified output directory.
+# To also run tests, add
+#
+# --build-arg ADDITIONAL_GRADLE_TASK=test
+#
+
+# stage: set up debian environment
+FROM debian:bullseye-slim AS setup-stage
+
+ENV DEBIAN_FRONTEND noninteractive
+RUN /usr/bin/apt-get update && \
+    /usr/bin/apt-get --yes install openjdk-11-jdk-headless gradle && \
+    /usr/sbin/adduser --disabled-login --gecos "" builder
+
+# stage: build
+FROM setup-stage AS build-stage
+
+ARG ADDITIONAL_GRADLE_TASK=""
+
+# give up privileges
+USER builder
+WORKDIR /home/builder
+
+# copy project source code
+COPY --chown=builder / project/
+
+# build project
+RUN /usr/bin/gradle --project-dir project/ \
+    --no-build-cache --no-daemon --no-parallel \
+    -Dmaven.repo.local=repo \
+    clean ${ADDITIONAL_GRADLE_TASK} :bitcoinj-core:publishToMavenLocal :bitcoinj-wallettool:installDist
+
+# stage: export build output
+FROM scratch AS export-stage
+COPY --from=build-stage \
+    /home/builder/repo/org/bitcoinj/*/*/*.jar \
+    /home/builder/repo/org/bitcoinj/*/*/*.pom \
+    /core/
+COPY --from=build-stage \
+    /home/builder/project/wallettool/build/install/wallet-tool/ \
+    /wallettool/