Add Dockerfile for portable builds and deployments

.github/workflows/push-container-images.yml

@@ -0,0 +1,45 @@
+name: push-container-images
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+
+  build:
+    strategy:
+      matrix:
+        runner:
+          - ubuntu-latest
+          - ubuntu-24.04-arm
+        base:
+          - corretto-8
+          - temurin-8
+          - zulu-8
+          - alpine-openjdk-8
+          - ubuntu-openjdk-8
+          - rhel-openjdk-8
+
+    runs-on: ${{ matrix.runner }}
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+
+      - name: Set up Docker
+        uses: docker/setup-buildx-action@b5ca514318bd6ebac0fb2aedd5d36ec1b5c232a2 # v3
+
+      - name: Build image
+        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6
+        with:
+          context: .
+          build-args: |
+            BASE=${{ matrix.base }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+

Dockerfile

@@ -0,0 +1,102 @@
+# syntax=docker/dockerfile:1.16-labs
+
+# This is the official Ion Fusion container file (aka Dockerfile).
+#
+# You can build an Ion Fusion runtime image with:
+#
+#     docker build -t fusion .
+#
+# Then you can run that with:
+#
+#     docker run --rm -it fusion repl
+#
+# You can also build an Ion Fusion SDK image with:
+#
+#     docker build -t fusion-sdk --target sdk .
+#
+# For more details, see: ./fusion/src/howto_build.md
+
+ARG BASE="corretto-8"
+# Available BASE values:
+# corretto-8 temurin-8 zulu-8 alpine-openjdk-8 ubuntu-openjdk-8 rhel-openjdk-8
+
+ARG BASE_JDK="base-jdk-${BASE}"
+ARG BASE_JRE="base-jre-${BASE}"
+
+
+# Base images
+# -----------
+
+# Amazon Corretto OpenJDK: https://hub.docker.com/_/amazoncorretto
+FROM amazoncorretto:8-al2-native-jdk@sha256:04aaf328807dfea094048b98b6cc8fcb248017c044082460248cb165c8c8dcf9 AS base-jdk-corretto-8
+
+FROM amazoncorretto:8-al2-native-jre@sha256:3b9d585c1cc14d88589bee02fff1e52bf032e3af8545166fee074b6f61ad1723 AS base-jre-corretto-8
+
+# Eclipse Temurin OpenJDK: https://hub.docker.com/_/eclipse-temurin
+FROM eclipse-temurin:8-jdk@sha256:26eef5df6131e5da7d556f1bd62fa118571ff00c0eac6d76ae30f5c7e7ce8b49 AS base-jdk-temurin-8
+
+FROM eclipse-temurin:8-jre@sha256:eb4cc550df86a3534356839ca37c5894e8dae83b29f84d7ca0684898d4057b2d AS base-jre-temurin-8
+
+# Azul Zulu OpenJDK: https://hub.docker.com/r/azul/zulu-openjdk
+FROM azul/zulu-openjdk:8@sha256:92f73f035d60fc0053570130c3bceba9926fb4deeecb227b45e839bd14fc0265 AS base-jdk-zulu-8
+
+FROM azul/zulu-openjdk:8-jre@sha256:dbfdbd36db44b29f3b9580bec87cd41fd6962962299f3a601a314478a2f03663 AS base-jre-zulu-8
+
+# Alpine Linux: https://hub.docker.com/_/alpine
+FROM alpine:latest@sha256:8a1f59ffb675680d47db6337b49d22281a139e9d709335b492be023728e11715 AS base-jdk-alpine-openjdk-8
+RUN apk add --no-cache openjdk8-jdk
+
+FROM alpine:latest@sha256:8a1f59ffb675680d47db6337b49d22281a139e9d709335b492be023728e11715 AS base-jre-alpine-openjdk-8
+RUN apk add --no-cache openjdk8-jre
+
+# Ubuntu Linux: https://hub.docker.com/_/ubuntu
+FROM ubuntu:latest@sha256:b59d21599a2b151e23eea5f6602f4af4d7d31c4e236d22bf0b62b86d2e386b8f AS base-jdk-ubuntu-openjdk-8
+RUN apt-get update && \
+    apt-get --assume-yes --no-install-recommends install openjdk-8-jdk-headless
+
+FROM ubuntu:latest@sha256:b59d21599a2b151e23eea5f6602f4af4d7d31c4e236d22bf0b62b86d2e386b8f AS base-jre-ubuntu-openjdk-8
+RUN apt-get update && \
+    apt-get --assume-yes --no-install-recommends install openjdk-8-jre-headless
+
+# Red Hat Enterprise Linux 8: https://hub.docker.com/r/redhat/ubi8
+FROM redhat/ubi8:latest@sha256:0c1757c4526cfd7fdfedc54fadf4940e7f453201de65c0fefd454f3dde117273 AS base-jdk-rhel-openjdk-8
+RUN dnf --assumeyes install java-1.8.0-openjdk-devel
+
+FROM redhat/ubi8:latest@sha256:0c1757c4526cfd7fdfedc54fadf4940e7f453201de65c0fefd454f3dde117273 AS base-jre-rhel-openjdk-8
+RUN dnf --assumeyes install java-1.8.0-openjdk-headless
+
+
+# Ion Fusion build image
+# ----------------------
+
+FROM ${BASE_JDK} AS build
+WORKDIR /opt/fusion
+# avoid javadoc build errors due to encoding issues:
+ENV LC_ALL="C.UTF-8" LANG="en_US.UTF-8" LANGUAGE="en_US.UTF-8"
+# install gradle via the wrapper:
+COPY --parents gradle/ gradlew build.gradle.kts settings.gradle.kts .
+RUN ./gradlew --version
+# copy in all remaining source files:
+COPY --parents doc/ ftst/ fusion/ rkt/ src/ tst-data/ .
+# run the gradle build, then clean up build dependencies:
+RUN ./gradlew --no-daemon --console=plain --stacktrace release && rm -rf ~/.gradle
+
+
+# Ion Fusion SDK image
+# --------------------
+
+FROM ${BASE_JDK} AS sdk
+COPY --from=build /opt/fusion/build/install/fusion /opt/fusion
+ENV PATH="/opt/fusion/bin:$PATH"
+ENTRYPOINT ["fusion"]
+
+
+# Ion Fusion runtime image
+# ------------------------
+
+FROM ${BASE_JRE}
+COPY --from=build /opt/fusion/build/install/fusion/bin /opt/fusion/bin
+COPY --from=build /opt/fusion/build/install/fusion/lib /opt/fusion/lib
+ENV PATH="/opt/fusion/bin:$PATH"
+ENTRYPOINT ["fusion"]
+

README.md

@@ -35,11 +35,10 @@ It is now an independent Apache-licensed project led by current and former Amazo
 
 # Getting Started
 
-To learn more about this project, browse our documentation at <https://docs.ion-fusion.dev>.
+To learn more about Ion Fusion, see the website: <https://ion-fusion.dev/>
 
-To try out the Fusion CLI, you'll need to build from source (sorry!).  
-See [Building Ion Fusion](https://docs.ion-fusion.dev/howto_build.html) for instructions and 
-some introductory tutorials.
+For more details on building the Ion Fusion SDK, the `fusion` utility, and the Ion Fusion container
+images, see the documentation on [building Ion Fusion](fusion/src/howto_build.md).
 
 
 # Support

fusion/src/howto_build.md

@@ -3,39 +3,144 @@
 
 # Building Ion Fusion
 
-> **Prerequisites:**
->
-> * Install a Java runtime, version 8 or later. We recommend [Amazon Corretto][].
-> * Install [Git][].
-> * Ensure that `java` and `git` are on your shell's `PATH`.
+This guide shows how to get a working copy of the Ion Fusion source code, and
+how to build the Ion Fusion software development kit (SDK) and container images.
 
-Building from source should be straightforward:
+- [Getting the source code](#getting-the-source-code)
+- [Building the SDK with Gradle](#building-the-sdk-with-gradle)
+- [Building the container images](#building-the-container-images)
+
+
+## Getting the source code
+
+Assuming [Git][] is installed, run:
 
     git clone https://github.com/ion-fusion/fusion-java.git
     cd fusion-java
+
+Alternatively, you can download an archive of the repository's code from:
+<https://github.com/ion-fusion/fusion-java/archive/refs/heads/main.zip>
+
+[Git]: https://git-scm.com/
+
+
+## Building the SDK with Gradle
+
+With a Java 8 runtime installed, you can build the Ion Fusion SDK natively
+from the source directory, with:
+
     ./gradlew release
 
-After a successful release build, you'll have a basic SDK under `build/install/fusion`. The notable
-artifacts within that directory are:
+After a successful release build, you'll have a basic Ion Fusion SDK under
+`build/install/fusion`, encompassing:
 
-* `bin/fusion` is the `fusion` CLI
-* `docs/fusiondoc/fusion.html` is the documentation for the Ion Fusion language
-* `docs/javadoc/index.html` is the documentation embedding Ion Fusion in your Java application
-* `lib` holds the jars needed for embedding
+* `bin/fusion`, the Ion Fusion command-line interface (CLI) utility.
+* `docs/fusiondoc/fusion.html`, the documentation for the Ion Fusion language.
+* `docs/javadoc/index.html`, the documentation for the `fusion-java` API, for integrating Ion Fusion into your Java application.
+* `lib/`, with the Ion Fusion JAR files required for integration.
 
-To experiment with the CLI, add the `bin` to your path:
+To experiment with the CLI, you can add the `bin` directory to your PATH:
 
     PATH=$PATH:$PWD/build/install/fusion/bin
     fusion help
 
-That should give you an overview of the CLI's subcommands.
+That will give you an overview of the CLI's subcommands.
 
 
-## What's Next?
+## Building the container images
 
-With the `fusion` CLI ready to go, you can follow the [CLI tutorial](tutorial_cli.html) and run
-some code!
+With a container CLI installed (such as [docker][], [podman][], [nerdctl][],
+[finch][] or [container][]) capable of building `linux/amd64` or `linux/arm64`
+containers, you can build the Ion Fusion container images from the source
+directory. Per your preferences, you can do this instead of, or as well as,
+building Ion Fusion via Gradle as described above.
 
+[docker]: https://www.docker.com/products/cli/
+[podman]: https://podman.io/
+[nerdctl]: https://github.com/containerd/nerdctl
+[finch]: https://github.com/runfinch/finch
+[container]: https://github.com/apple/container
 
-[Amazon Corretto]: https://aws.amazon.com/corretto
-[Git]: https://git-scm.com/
+### Runtime image
+
+The Ion Fusion runtime image is ideal for using the `fusion` CLI, and for
+runtime application deployments; it is based atop an OpenJDK Java Runtime
+Environment (JRE) installation, *not* a complete OpenJDK distribution.
+
+You can build the Ion Fusion runtime image with:
+
+    docker build -t fusion .
+
+You can then run the Ion Fusion runtime image with:
+
+    docker run --rm fusion help
+
+Thus, an alternative way to "install" the `fusion` CLI is simply:
+
+    alias fusion='docker run --rm fusion`
+
+You can alternatively run a shell from the Ion Fusion runtime image with:
+
+    docker run --rm -it --entrypoint sh fusion
+
+### SDK image
+
+The Ion Fusion SDK image is ideal for development and build purposes; it is
+based atop a complete OpenJDK installation.
+
+You can build the Ion Fusion SDK image with:
+
+    docker build -t fusion-sdk --target sdk .
+
+The SDK image supports building applications that integrate Ion Fusion:
+
+    docker run --rm --entrypoint sh fusion-sdk -c '
+    echo "public class Example {
+        public static void main(String[] args) {
+            dev.ionfusion.fusion.cli.Cli.main(args);
+            System.out.println(\"Hello, Fusion integration!\");
+        }
+    }" >Example.java
+    cp="$(echo /opt/fusion/lib/*.jar | tr " " :)"
+    javac -cp "$cp" Example.java
+    java -cp ".:$cp" Example version'
+
+### Varying the OpenJDK
+
+By default, the Ion Fusion container images are built atop the official
+[Amazon Corretto][] container images.
+
+You can alternatively build the Ion Fusion container images atop other OpenJDK
+distributions, with, for example:
+
+    docker build -t fusion --build-arg BASE=alpine-openjdk-8
+
+The Ion Fusion `Dockerfile` supports a range of possible `BASE` build arguments
+for controlling the underlying OpenJDK distrubution:
+
+- [Amazon Corretto][]: `corretto-8`
+- [Eclipse Temurin](https://hub.docker.com/_/eclipse-temurin): `temurin-8`
+- [Azul Zulu](https://hub.docker.com/r/azul/zulu-openjdk): `zulu-8`
+- [Alpinux Linux](https://hub.docker.com/_/alpine): `alpine-openjdk-8`
+- [Ubuntu Linux](https://hub.docker.com/_/ubuntu): `ubuntu-openjdk-8`
+- [Red Hat Enterprise Linux 8](https://hub.docker.com/r/redhat/ubi8):
+  `rhel-openjdk-8`
+
+You can even build the Ion Fusion container images atop entirely custom JDK and
+JRE base images, like:
+
+    docker build -t fusion \
+        --build-arg BASE_JDK=amazoncorretto:8-alpine-jdk \
+        --build-arg BASE_JRE=amazoncorretto:8-alpine-jre \
+        .
+
+For more details on how you can control the Ion Fusion container image build
+process, see the [Dockerfile](../../Dockerfile) source code.
+
+[Amazon Corretto]: https://hub.docker.com/_/amazoncorretto
+
+
+## What's Next?
+
+With the `fusion` CLI ready to go, you can follow the
+[CLI tutorial](tutorial_cli.html) and run some code!

fusion/src/tutorial_cli.md

@@ -12,7 +12,7 @@ Here we'll walk through some basic use cases with Ion Fusion's command-line inte
 > * Download the [Ion Fusion SDK][SDK], unpack it somewhere, and add its
 >   `bin` directory to your `PATH`.
 >
-> Alternatively, you can [build the CLI from source](howto_build.html).
+> Alternatively, you can [build Ion Fusion from source](howto_build.html).
 
 The `fusion` CLI has three modes of operation: an interactive REPL, script execution, and direct
 evaluation of expressions. We'll start with the latter: