Unlock GraphQL – ORDS on GraalVM with Docker

ORDS 23.3.0 introduced GraphQL functionality which makes it possible for a user to define complex queries on REST Enable tables and views in the database. Specific information on how to use GraphQL is in the ORDS Developer Guide. Although ORDS is known as a Java Web Application, the GraphQL implementation is primarily in JavaScript. To use the GraphQL feature, ORDS must be running on Oracle GraalVM with the JavaScript component installed.

That’s as simple as downloading the Oracle GraalVM ( for Java 11 or Java 17 ), installing the JavaScript component, and running ORDS as usual with that JVM. See GraalVM Configuration in the Installation and Configuration Guide.

Running with docker / podman / kubernetes is also straight forward but there are one or two steps that may not be intuitive. Building on concepts introduced in a previous article I’ll walk through the steps to create an image for running the latest release of ORDS on Oracle GraalVM Enterprise.

The goal is to build a docker image which is based on a GraalVM image. The build process for that image will install the required GraalVM JavaScript component and download the latest release of ORDS. The resulting image can be used to spin up a new container which is running ORDS standalone. Similar to the containers used from the above previous article, the containers will use a shared docker volume for configuration.

Getting GraalVM

GraalVM is a high-performance runtime that provides support for various programming languages and execution modes. It includes a Java Virtual Machine (JVM) that is enhanced with the GraalVM compiler, which can improve the performance of Java applications such as ORDS. GraalVM is a polyglot virtual machine that supports multiple programming languages, including JavaScript, Python and more. To use these programming languages, specific components must also be installed, and as is common, licences for their use must be agreed. The Oracle Free Use Terms and Conditions licence that ORDS is available under, and the GraalVM Free Use Terms and Conditions licence that GraalVM is available under, do not extend to these components. Although convenient Docker images are available, to run a Java application which also uses JavaScript requires that JavaScript runtime component to be installed in the image. To install that component requires an activated download token which confirms you have accepted the software licence. This article will cover getting that token, but first, which image should be used?

GraalVM Image

Oracle GraalVM Enterprise container images are published in the Oracle Container Registry and there are quite a few to choose from. The following images are available:

We will require a GraalVM Enterprise JDK to run ORDS which is a Java application but will also require the JavaScript component installed so we’ll need the Graal Updater utility too. That means the enterprise image is the one for us. In fact, we’ll use container-registry.oracle.com/graalvm/enterprise:ol8-java17 which gives us a Java 17 JDK. At the time of writing, the only supported Java versions for ORDS are Java 11 and Java 17.

GraalVM Download Token

To install the GraalVM JavaScript component requires an activated download token. This token indicates that you have accepted a licence agreement for using the component and in this article we pass it as a parameter when building the image. There are a number of ways to obtain a token, in fact just by using the Graal Updater utility ( gu ) to install a component will initiate it…

Downloading: Artifacts catalog from gds.oracle.com
Skipping ULN EE channels, no username provided.
Downloading: Component catalog from www.graalvm.org
Processing Component: Graal.js
Enter your download token and press ENTER, or press ENTER to generate a new download token.
Enter a valid download token:

However, at this stage up may not have the Graal Updater on your machine. The most convenient way on a unix based operating system with bash is the handy dandy GraalVM Download Token Generator.

bash <(curl -sL https://get.graalvm.org/ee-token)

That will run a script to generate a token and initiate the licence agreement process. In this scenario I just copy the token string rather than persisting it.

About to request a download token for GraalVM Enterprise Edition...
Please provide an email address and review Oracle's Privacy Policy at https://www.oracle.com/legal/privacy/privacy-policy.html.
Enter a valid email address: pobalopalous@ordsexample.org
Your new download token is: 'NzY4MDYwYTk4ZjIyMTZmNTgzYWE3NzMwNGFkOGJiMmIwZTVlYTU3MmI3YThjZmY3NzExYzFlOWQxNjgyNTUwZGNiNzUxNmNlODIxNTkwYjM0MjA4NzkwNDVhNzUx'
Please check your email inbox and accept the license to activate your download token.
Would you like to persist this token in '/Users/pobalopalous/.gu/config' on this machine? (y/N): N
Download token not persisted.

Now I have an 88 character token but it has not been activated. Next, I must check my email for a link to accept the licence.

The link will take you through the Oracle SSO sign-on process if you’re not already logged in. Keep the download token value safe. It will be baked into your docker image so do not go publishing the image out on the internet, in other words … distributing the software, because the token can be linked back to your Oracle SSO account.

Get Building

Now that an activated download token is at hand we can get on with building the docker image. The Dockerfile is very similar to the one used in Get started with Oracle REST Data Services (ORDS) and Docker but has a couple of extra lines for installing the JavaScript component.

#
# Defines a docker image, based on the Oracle JDK image, to run Oracle REST Data Services. During the image building 
# process the most recent version of ORDS will be automatically downloaded and extracted.
#
# Volumes for configuration and lib/ext are defined.
#
# docker run -p 8080:8080 -v ords-config:/opt/ords-config/ -v ords-lib-ext:/opt/ords/latest/lib/ext ords-latest/graaljdk
#
# See https://peterobrien.blog/ for more information and examples.
#
FROM container-registry.oracle.com/graalvm/enterprise:ol8-java17
MAINTAINER Peter O'Brien

# Get an Oracle Graal EE Download token and provide that value when building the image.
# See https://github.com/graalvm/graalvm-jdk-downloader/blob/main/README.md#set-up-a-download-token-for-graalvm-enterprise-edition-installations
# docker build  --build-arg="GRAAL_TOKEN=Get your own token" --tag ords-latest/graaljdk .
# Note that token will be baked into the image.
ARG GRAAL_TOKEN
ENV GRAAL_EE_DOWNLOAD_TOKEN=$GRAAL_TOKEN
RUN gu install --auto-yes --non-interactive js

ENV LATEST=/opt/ords-latest/
ENV CONFIG=/opt/ords-config/
WORKDIR $LATEST
ADD https://download.oracle.com/otn_software/java/ords/ords-latest.zip $LATEST
RUN jar xf ords-latest.zip; rm ords-latest.zip; chmod +x bin/ords
VOLUME $LATEST/lib/ext/ $CONFIG
EXPOSE 8080
EXPOSE 8443
WORKDIR $CONFIG
ENTRYPOINT ["/opt/ords-latest/bin/ords"]
CMD ["serve"]

When running docker build with this Dockerfile the download token must be provided as an argument. Otherwise there will be a build failure similar to this:

Step 3/13 : RUN gu install --auto-yes --non-interactive js
 ---> Running in 86da6cdbc24f
Downloading: Artifacts catalog from gds.oracle.com
Skipping ULN EE channels, no username provided.
Downloading: Component catalog from www.graalvm.org
Processing Component: Graal.js
Enter your download token and press ENTER, or press ENTER to generate a new download token.
Enter a valid download token:The command '/bin/sh -c gu install --auto-yes --non-interactive js' returned a non-zero code: 5

Convenient Dockerfile

To make things even easier, I’ve created a Dockerfile that you can use and the only thing you have to change is the token value on the command line:

docker build  --build-arg="GRAAL_TOKEN=NzY4MDYwYTk4ZjIyMTZmNTgzYWE3NzMwNGFkOGJiMmIwZTVlYTU3MmI3YThjZmY3NzExYzFlOWQxNjgyNTUwZGNiNzUxNmNlODIxNTkwYjM0MjA4NzkwNDVhNzUx" --tag ords-latest/graaljdk https://gist.githubusercontent.com/pobalopalous/a8c78d45c69fdb40763c913e2bda82c6/raw/4b57a40639385085e51dae21dec4b3fec7b1708c/

Let’s break those docker build command arguments down..

--build-arg="GRAAL_TOKEN=NzY4MDYwYTk4ZjIyMTZmNTgzYWE3NzMwNGFkOGJiMmIwZTVlYTU3MmI3YThjZmY3NzExYzFlOWQxNjgyNTUwZGNiNzUxNmNlODIxNTkwYjM0MjA4NzkwNDVhNzUx"

This specifies the GRAAL_TOKEN build argument that the Dockerfile will use to set the GRAAL_EE_DOWNLOAD_TOKEN environment variable which is used by the gu install js command when building the image.

--tag ords-latest/graaljdk 

The image that we build is going to be called ords-latest/graaljdk. That will differentiate it from the ords-latest/oraclejdk image we created in Get started with Oracle REST Data Services (ORDS) and Docker.

https://gist.githubusercontent.com/pobalopalous/a8c78d45c69fdb40763c913e2bda82c6/raw/4b57a40639385085e51dae21dec4b3fec7b1708c/

That’s the URL for the Dockerfile build context I have created for you so you don’t have to copy the text locally. Isn’t that nice?

Run that with your download token and you’ll see something like this…

Downloading build context from remote url: https://gist.githubusercontent.com/pobalopalous/a8c78d45c69fdb40763c913e2bda82c6/raw/4b57a40Downloading build context from remote url: https://gist.githubusercontent.com/pobalopalous/a8c78d45c69fdb40763c913e2bda82c6/raw/4b57a40639385085e51dae21dec4b3fec7b1708c/ORDS_Latest_GraalVM_Dockerfile [==================================================>]  1.371kB/1.371kB
Sending build context to Docker daemon  3.072kB
Step 1/16 : FROM container-registry.oracle.com/graalvm/enterprise:ol8-java17
 ---> 64dca1a5fa2a
Step 2/16 : MAINTAINER Peter O'Brien
 ---> Running in 33db11ef151e
Removing intermediate container 33db11ef151e
 ---> d38b7a7f3b67
Step 3/16 : ARG GRAAL_TOKEN
 ---> Running in 7613b2d725f7
Removing intermediate container 7613b2d725f7
 ---> f67809364f83
Step 4/16 : ENV GRAAL_EE_DOWNLOAD_TOKEN=$GRAAL_TOKEN
 ---> Running in fa3dc864e3b5
Removing intermediate container fa3dc864e3b5
 ---> 5fb687d736d1
Step 5/16 : RUN gu install --auto-yes --non-interactive js
 ---> Running in 9fb627218998
Downloading: Artifacts catalog from gds.oracle.com
Skipping ULN EE channels, no username provided.
Downloading: Component catalog from www.graalvm.org
Processing Component: Graal.js
Downloading: Component js: Graal.js from gds.oracle.com
Installing new component: Graal.js (org.graalvm.js, version 22.3.3)
Refreshed alternative links in /usr/bin/
Removing intermediate container 9fb627218998
 ---> ecef6d97d8db
Step 6/16 : ENV LATEST=/opt/ords-latest/
 ---> Running in f661804977a7
Removing intermediate container f661804977a7
 ---> 1005a3e3690b
Step 7/16 : ENV CONFIG=/opt/ords-config/
 ---> Running in 50901e104315
Removing intermediate container 50901e104315
 ---> 8a376e3151ee
Step 8/16 : WORKDIR $LATEST
 ---> Running in bd9810fe29f9
Removing intermediate container bd9810fe29f9
 ---> c18a57d2a8db
Step 9/16 : ADD https://download.oracle.com/otn_software/java/ords/ords-latest.zip $LATEST
Downloading [==================================================>]  114.1MB/114.1MB
 ---> 3cec2554cd2b
Step 10/16 : RUN jar xf ords-latest.zip; rm ords-latest.zip; chmod +x bin/ords
 ---> Running in 50a97beac418
Removing intermediate container 50a97beac418
 ---> 3f9fff9bded5
Step 11/16 : VOLUME $LATEST/lib/ext/ $CONFIG
 ---> Running in 0276fc517e42
Removing intermediate container 0276fc517e42
 ---> 5a8b5e5947e6
Step 12/16 : EXPOSE 8080
 ---> Running in c4dbf726988b
Removing intermediate container c4dbf726988b
 ---> c2ad8e7b94d3
Step 13/16 : EXPOSE 8443
 ---> Running in da46a9b873a3
Removing intermediate container da46a9b873a3
 ---> 5619e6b04ece
Step 14/16 : WORKDIR $CONFIG
 ---> Running in d5959c70115b
Removing intermediate container d5959c70115b
 ---> 440d4e54a4ce
Step 15/16 : ENTRYPOINT ["/opt/ords-latest/bin/ords"]
 ---> Running in 4452ce4de261
Removing intermediate container 4452ce4de261
 ---> f23c5cf67824
Step 16/16 : CMD ["serve"]
 ---> Running in 9f9f69dce7ae
Removing intermediate container 9f9f69dce7ae
 ---> ab2e0a2981e0
Successfully built ab2e0a2981e0
Successfully tagged ords-latest/graaljdk:latest

If you have made it this far, you now have an ords-latest/graaljdk image ready to be put into action.

Now RUN !

This is the part we’ve been waiting for. Remember that just like in Get started with Oracle REST Data Services (ORDS) and Docker the database already has ORDS installed and the configuration directory is a docker volume called ords-adb-config which gets mapped to /opt/ords-config/ in the container.

docker run --detach --rm --name ords-latest-8080 \
             -p 8080:8080 \
             -v ords-adb-config:/opt/ords-config/ \
             ords-latest/graaljdk

That will run in the background so you can use the docker logs command to check the output: docker logs -f ords-latest-8080

ORDS: Release 23.3 Production on Fri Nov 17 13:32:11 2023

Copyright (c) 2010, 2023, Oracle.

Configuration:
  /opt/ords-config/

2023-11-17T13:32:11.890Z INFO        HTTP and HTTP/2 cleartext listening on host: 0.0.0.0 port: 8080
...
java.vm.name=Java HotSpot(TM) 64-Bit Server VM
java.vendor.version=GraalVM EE 22.3.3
...
2023-11-17T13:32:27.906Z INFO        

Mapped local pools from /opt/ords-config/databases:
  /ords/                              => default                        => VALID     


2023-11-17T13:32:28.233Z INFO        Oracle REST Data Services initialized
Oracle REST Data Services version : 23.3.0.r2891830
Oracle REST Data Services server info: jetty/10.0.17
Oracle REST Data Services java info: Java HotSpot(TM) 64-Bit Server VM 17.0.8+9-LTS-jvmci-22.3-b21

The GraphQL implementation in ORDS is based on REST Enabled tables and views. Therefore, to get any sensible use of GraphQL with ORDS one must first have a REST Enabled schema with some REST Enabled tables or views. Thankfully I already have that in my database so I can dive right in…

Over to you

To sum it up, this article explained how to create a Docker image using GraalVM, specifically focusing on adding the JavaScript component needed for ORDS GraphQL. The image build process involves installing the GraalVM JavaScript part and downloading the latest ORDS release, resulting in a Docker image. Before doing so, you had to get and activate a download token so that the JavaScript component could be installed in the image. This image, when used, makes it easy to start a standalone ORDS container. You now have a straightforward solution for using ORDS GraphQL in a GraalVM environment that is ready for production.

To explore all the powerful querying options available to you with ORDS GraphQL see the relevant chapter in the ORDS Developer Guide.