Visit Azul.com Support

Get Started with Azul Platform Prime using Docker

Table of Contents
Need help?
Schedule a consultation with an Azul performance expert.
Contact Us

  • Stream Builds are fast-moving builds that include the latest JVM features. They are produced once a month and do not receive any security backports.

  • Stable Builds contain only critical fix backports, and are produced on an ongoing basis.

Customers can download builds from the Azul Customer Downloads page.

Want to try Azul Platform Prime for yourself? Request a trial.

For more information about Azul Platform Prime Stream and Stable Builds, see the Azul Platform Prime Roadmap.

These instructions guide you through the Azul Platform Prime installation using Docker.

Prerequisites

Install Docker by following the Docker documentation.

Using Docker Azul Zing Builds of OpenJDK

Docker images of Azul Zing Builds of OpenJDK (Zing) are provided through Docker Hub.

CentOS, Debian, and Ubuntu based official Docker images of Zing are available in the following repositories:

OS Image Name

Ubuntu

azul/prime

Debian

azul/prime-debian

CentOS

azul/prime-centos

Usage

The Azul Platform Prime repository supports numerous versions of OpenJDK-based Java SE JDKs. To run a container of your choice, add the Java version suffix you wish to pull. For example, to pull the image with JDK 21, run one of the following depending on the system you want it to be based on:

 
# Ubuntu
docker pull azul/prime:21

# Debian
docker pull azul/prime-debian:21

# CentOS
docker pull azul/prime-centos:21

Run Java apps

You can test the Docker image by running the following command in a terminal:

 
docker run -it --rm azul/prime:21 java -version

The command allocates a terminal and runs java. It prints a message similar to this:

 
openjdk version "21.0.6.0.101" 2025-04-29 LTS
OpenJDK Runtime Environment Zing25.04.0.0+2 (build 21.0.6.0.101+2-LTS)
Zing 64-Bit Tiered VM Zing25.04.0.0+2 (build 21.0.6.0.101-zing_25.04.0.0-b2-release-linux-aarch64, mixed mode)

If you see this message in your terminal, you’ve successfully executed java inside a container.

The command above simply executes java. To run a Java application, you must provide your application classes and resources to the java command. You do this by mounting a local directory from the container.

As an example, let’s assume that your application files are located in a single directory. You would normally run the app by executing java MyApp in that directory. Use the -v option of docker run to make the directory available inside the container. The command might look like this:

 
docker run -it --rm \
    -v ${PWD}:/usr/src/project  \
    -e CLASSPATH=/usr/src/project \
    azul/prime:21 java MyApp

Create your own Docker Image with Zing

Creating your own Docker image with Zing is a great way to ensure your application runs consistently in different environments.

First, create a file named Dockerfile in your application’s directory, where your application’s jar file is located. Make sure the file does not have a file extension. This file serves as the configuration for your Docker build process. Use the example file here or the example Dockerfiles in the next section to help you write your Dockerfile:

 
# Specify the JDK image to use from Docker Hub
FROM azul/prime:21

# Set the working directory in the container
WORKDIR /app

# Copy your Java application JAR file into the working directory
COPY My-App.jar /app

# The command to run your application
CMD ["java", "-jar", "My-App.jar"]

Once you have your Dockerfile, you can build your Docker image. Open your terminal and navigate to the directory containing your Dockerfile and jar file. Run the following command to build your Docker image:

 
docker build -t image-name .

When your Docker image is finished building, you should get a message like this:

 
[+] Building 20.9s (9/9) FINISHED

You are now finished building your Docker image. If you are using Docker Desktop, your image should already be in the list of images. To run your image, use:

 
docker run -d --name container-name image-name

Example Custom Docker Containers

The following examples demonstrate how to build custom Docker containers with Zing on different Linux distributions and architectures. These examples use the Azul Metadata API or FTP server to download Zing packages, allowing you to specify the exact Java version and distribution you need. Each example includes the necessary build arguments and commands to create a working container.

Ubuntu Container Using the Zing Download API

 
# Zing stable-release containerfile example
# docker build --build-arg=apikey=MYAPITOKEN -t zingtest -f zing_api_ubuntu_containerfile.txt
# docker run --rm -i -t zingtest java -version

FROM ubuntu:24.04

ARG apikey
ARG version=17
ARG release=stable

RUN apt update \
 && apt install -y curl gnupg dpkg-dev jq
RUN APIURL="https://api.azul.com/metadata/v1/zing/packages/?java_version=$version&os=linux&arch=$(dpkg-architecture -q DEB_HOST_GNU_CPU)&archive_type=deb&java_package_type=jdk&latest=true&crs_supported=true&build_types=$release" \
 && URL=$(curl -s -H "Authorization: Bearer $apikey" -H "accept: application/json" -X GET "$APIURL" | jq -r '.[].download_url' | head -1) \
 && curl -s -L -o /tmp/zing.deb "$URL" \
 && curl -s https://repos.azul.com/azul-repo.key | gpg --import \
 && gpg --verify /tmp/zing.deb \
 && apt install -y /tmp/zing.deb \
 && rm /tmp/zing.deb \
 && echo "export JAVA_HOME=$(dirname $(dirname $(readlink -f /etc/alternatives/java)))" >> /etc/bash.bashrc

Ubuntu Container Using the FTP Server (x86_64 and ARM64)

Ubuntu is a glibc-based distribution, so Zing runs without requiring additional compatibility layers. This example downloads Zing from the FTP server and extracts it to /opt/zing. The grep pattern automatically selects the correct architecture based on your build platform.

 
# Zing stable-release containerfile example for Ubuntu
# For x86_64:
# docker build --build-arg=ftpuser=CUSTOMERUSER --build-arg=ftppassword='CUSTOMERPASSWD' \
#   -t zingtest-ubuntu -f zing_ubuntu_containerfile.txt
# For ARM64:
# docker build --platform=linux/arm64 --build-arg=ftpuser=CUSTOMERUSER --build-arg=ftppassword='CUSTOMERPASSWD' \
#   -t zingtest-ubuntu-arm64 -f zing_ubuntu_containerfile.txt
# docker run --rm -i -t zingtest-ubuntu java -version

FROM ubuntu:24.04

ARG ftpuser
ARG ftppassword
ARG ftpselection=jdk17

# Install dependencies for Ubuntu
RUN apt-get update && apt-get install -y wget binutils && rm -rf /var/lib/apt/lists/*

# Download and extract Zing
# Note: Use "linux_x64.tar.gz" for x86_64 or "linux_aarch64.tar.gz" for ARM64
ENV FTPBASEURL=https://ftp.azul.com/releases/Zing/latest-stable/
RUN ftpfile=$(wget --user "$ftpuser" --password "$ftppassword" -qO- $FTPBASEURL \
  | grep "${ftpselection}.*linux_x64.tar.gz<" \
  | sed -E 's/.*href=\"(zing.*)\".*/\1/' | sort -n | tail -1) \
 && wget -O /tmp/zing.tar.gz --user "$ftpuser" --password "$ftppassword" $FTPBASEURL/$ftpfile \
 && mkdir -p /opt/zing \
 && tar -xzf /tmp/zing.tar.gz -C /opt/zing --strip-components=1 \
 && rm /tmp/zing.tar.gz

ENV JAVA_HOME=/opt/zing
ENV PATH="$JAVA_HOME/bin:$PATH"
ENV LC_CTYPE="en_US.UTF-8"
Note
 For ARM64 builds, change linux_x64.tar.gz to linux_aarch64.tar.gz in the grep pattern.

CentOS Stream Container Using the FTP Server

 
# containerfile example using the Azul Zing stable release
# docker build --build-arg=ftpuser=CUSTOMERUSER --build-arg=ftppassword='CUSTOMERPASSWD' \
#   -t zingtest -f zing_centos_containerfile.txt
# docker run --rm -i -t zingtest java -version
#
FROM quay.io/centos/centos:stream9

ARG ftpuser
ARG ftppassword
ARG ftpselection=jdk17

ENV FTPBASEURL=https://ftp.azul.com/releases/Zing/latest-stable/
RUN ftpfile=$(curl --user "$ftpuser:$ftppassword" --list-only --silent --location $FTPBASEURL \
  | grep "${ftpselection}.*linux.$(rpm --eval '%{_arch}').rpm<" \
  | sed -E 's/.*href=\"(zing.*)\".*/\1/' | sort -n | tail -1) \
 && curl -O -L --user "$ftpuser:$ftppassword" $FTPBASEURL/$ftpfile \
 && rpm --import https://repos.azul.com/azul-repo.key \
 && (rpm -K $ftpfile | grep 'digests signatures OK') \
 && dnf localinstall -y $ftpfile \
 && rm $ftpfile \
 && dnf clean all

Alpine Linux (x86_64) Container Using the FTP Server

Alpine Linux is a minimal Linux distribution that uses musl libc instead of glibc. Since Zing is built against glibc, additional dependencies are required to provide glibc compatibility in Alpine environments. This example downloads and installs glibc, gcc-libs, and zlib from Arch Linux repositories and configures the dynamic linker to support Zing.

 
# Zing stable-release containerfile example for Alpine Linux x86_64
# docker build --build-arg=ftpuser=CUSTOMERUSER --build-arg=ftppassword='CUSTOMERPASSWD' \
#   -t zingtest-alpine -f zing_alpine_x86_containerfile.txt
# docker run --rm -i -t zingtest-alpine java -version

FROM alpine:latest

ARG ftpuser
ARG ftppassword
ARG ftpselection=jdk17

# Install dependencies for Alpine
RUN apk add tar xz wget zstd \
&& wget -O glibc.tar.xz https://archlinux.org/packages/core/x86_64/glibc/download \
&& wget -O gcc-libs.tar.xz https://archlinux.org/packages/core/x86_64/gcc-libs/download \
&& wget -O zlib.tar.xz https://archlinux.org/packages/core/x86_64/zlib/download \
&& mkdir /usr/glibc \
&& tar x --strip-components=1 -C /usr/glibc -f glibc.tar.xz \
&& tar x --strip-components=1 -C /usr/glibc -f gcc-libs.tar.xz \
&& tar x --strip-components=1 -C /usr/glibc -f zlib.tar.xz \
&& (echo '/usr/local/lib'; echo '/usr/glibc/lib'; echo '/usr/lib'; echo '/lib') > /etc/ld.so.conf \
&& mkdir -p /lib64 \
&& ln -s /usr/glibc/lib/ld-linux-x86-64.so.2 /lib64/ld-linux-x86-64.so.2 \
&& /usr/glibc/bin/ldconfig \
&& mkdir -p /usr/lib/locale \
&& gzip -c -d /usr/glibc/share/i18n/charmaps/UTF-8.gz > /tmp/UTF-8 \
&& cd /usr/glibc/share/i18n/locales \
&& LD_LIBRARY_PATH=/usr/glibc/lib /usr/glibc/lib/ld-linux-x86-64.so.2 /usr/glibc/bin/localedef -i en_US -f /tmp/UTF-8 en_US.UTF-8

# Download and extract Zing
ENV FTPBASEURL=https://ftp.azul.com/releases/Zing/latest-stable/
RUN ftpfile=$(wget --user "$ftpuser" --password "$ftppassword" -qO- $FTPBASEURL \
  | grep "${ftpselection}.*linux_x64.tar.gz<" \
  | sed -E 's/.*href=\"(zing.*)\".*/\1/' | sort -n | tail -1) \
 && wget -O /tmp/zing.tar.gz --user "$ftpuser" --password "$ftppassword" $FTPBASEURL/$ftpfile \
 && mkdir -p /opt/zing \
 && tar -xzf /tmp/zing.tar.gz -C /opt/zing --strip-components=1 \
 && rm /tmp/zing.tar.gz

ENV JAVA_HOME=/opt/zing
ENV PATH="$JAVA_HOME/bin:$PATH"
ENV LC_CTYPE="en_US.UTF-8"

Alpine Linux (ARM64/aarch64) Container Using the FTP Server

Similar to the x86_64 version, the ARM64 Alpine container requires glibc compatibility. This example downloads and installs glibc, gcc-libs, zlib, and ld-lsb from Arch Linux ARM repositories and configures the dynamic linker to support Zing on ARM64 architecture.

Note
 The dependencies are regularly updated. If the wget lines fail, check http://mirror.archlinuxarm.org/aarch64/ for newer versions of the files. 
 
# Zing stable-release containerfile example for Alpine Linux ARM64
# docker build --build-arg=ftpuser=CUSTOMERUSER --build-arg=ftppassword='CUSTOMERPASSWD' \
#   -t zingtest-alpine-arm64 -f zing_alpine_arm64_containerfile.txt
# docker run --rm -i -t zingtest-alpine-arm64 java -version

FROM alpine:latest

ARG ftpuser
ARG ftppassword
ARG ftpselection=jdk17

# Install dependencies for Alpine
RUN apk add tar xz wget \
&& wget -O ld-lsb.tar.xz http://mirror.archlinuxarm.org/aarch64/extra/ld-lsb-3-9-aarch64.pkg.tar.xz \
&& wget -O glibc.tar.xz http://mirror.archlinuxarm.org/aarch64/core/glibc-2.42+r50+g453e6b8dbab9-1-aarch64.pkg.tar.xz \
&& wget -O gcc-libs.tar.xz http://mirror.archlinuxarm.org/aarch64/core/gcc-libs-15.2.1%2Br447%2Bg6a64f6c3ebb8-1-aarch64.pkg.tar.xz \
&& wget -O zlib.tar.xz http://mirror.archlinuxarm.org/aarch64/core/zlib-1:1.3.1-2-aarch64.pkg.tar.xz \
&& mkdir /usr/glibc \
&& tar x --strip-components=1 -C /usr/glibc -f ld-lsb.tar.xz \
&& tar x --strip-components=1 -C /usr/glibc -f glibc.tar.xz \
&& tar x --strip-components=1 -C /usr/glibc -f gcc-libs.tar.xz \
&& tar x --strip-components=1 -C /usr/glibc -f zlib.tar.xz \
&& (echo '/usr/local/lib'; echo '/usr/glibc/lib'; echo '/usr/lib'; echo '/lib') > /etc/ld.so.conf \
&& ln -s /usr/glibc/lib/ld-linux-aarch64.so.1 /lib/ \
&& /usr/glibc/bin/ldconfig \
&& mkdir -p /usr/lib/locale \
&& gzip -c -d /usr/glibc/share/i18n/charmaps/UTF-8.gz > /tmp/UTF-8 \
&& cd /usr/glibc/share/i18n/locales \
&& LD_LIBRARY_PATH=/usr/glibc/lib /usr/glibc/lib/ld-linux-aarch64.so.1 /usr/glibc/bin/localedef -i en_US -f /tmp/UTF-8 en_US.UTF-8

# Download and extract Zing
ENV FTPBASEURL=https://ftp.azul.com/releases/Zing/latest-stable/
RUN ftpfile=$(wget --user "$ftpuser" --password "$ftppassword" -qO- $FTPBASEURL \
  | grep "${ftpselection}.*linux_aarch64.tar.gz<" \
  | sed -E 's/.*href=\"(zing.*)\".*/\1/' | sort -n | tail -1) \
 && wget -O /tmp/zing.tar.gz --user "$ftpuser" --password "$ftppassword" $FTPBASEURL/$ftpfile \
 && mkdir -p /opt/zing \
 && tar -xzf /tmp/zing.tar.gz -C /opt/zing --strip-components=1 \
 && rm /tmp/zing.tar.gz

ENV JAVA_HOME=/opt/zing
ENV PATH="$JAVA_HOME/bin:$PATH"
ENV LC_CTYPE="en_US.UTF-8"