Fast-path to developing with Oracle APEX and Multilingual Engine

Support for In-Database JavaScript is one of the most exciting new features in Oracle Database 23c Free. JavaScript is the first language supported by Oracle Multilingual Engine (MLE), powered by GraalVM. Oracle APEX was one of the first platforms to support server-side JavaScript. If you want to get started developing using MLE and APEX without having to concern yourself with the installation, using container images is the fastest way to create a lab environment. It can be as simple as podman-compose up.

This post describes a fast path to creating a development lab to experiment with MLE and APEX using Docker Compose. Why compose? Because it can be used to consistently tie multiple container images together, including network & and name resolution, with a single command to start and stop containers. Please note that the compose format is not exclusively tied to Docker. This post was created using podman-compose on Oracle Linux 9.3.

Lab environment

This post was written using Oracle Linux 9.3 (x86-64) and

podman 4.6.1
podman-compose 1.0.6
podman-plugins 4.6.1
kernel-uk 5.15.0-201.135.6.el9uek.x86_64

These were installed using the standard package sources and were current at the time of this writing.

Oracle’s Container Registry

Oracle provides a container registry for all container images used in this post. These are:

Software	Usage Instructions
Oracle Database 23c Free	https://container-registry.oracle.com/ords/ocr/ba/database/free
Oracle REST Data Services	https://container-registry.oracle.com/ords/ocr/ba/database/ords

Save yourself some time by pulling the container images from the registry and read on while they are downloading.

podman pull container-registry.oracle.com/database/ords:latest
podman pull container-registry.oracle.com/database/free:latest

This might take a minute, depending on your bandwidth.

Overview

The compose file you’ll see in this article creates two services based on the container images just downloaded:

Oracle Database 23c Free (23.3.0)
ORDS (23.4.0)

If you read this sometime after its publication, versions might have changed, but the overall principles should still apply.

The database provided by the container image will automatically create a single Pluggable Database (PDB) named freepdb1 when the container is started for the first time. The ORDS container image will automatically install APEX and ORDS into that PDB.

Ensure you have enough memory and disk space to run both containers.

Compose File

The following is an example of a minimally viable compose file. It doesn’t do anything to harden the setup, there is no TLS (aka SSL), and the initial DBA passwords are defined in clear text. In other words, it is utterly unfit for production use. Please use it as your lab only.

# THIS IS NOT A PRODUCTION SETUP - LAB USE ONLY!
version: "3"
services:
    dbfree:
        image: container-registry.oracle.com/database/free:latest
        ports:
            - 1521:1521
        environment:
            - ORACLE_PWD=secretPassword
        volumes:
            - oradata-vol:/opt/oracle/oradata
        networks:
            - backend

    ords:
        depends_on:
            dbfree
        image: container-registry.oracle.com/database/ords:latest
        networks:
            - backend
        volumes:
            - ords-config-vol:/etc/ords/config
            - ./setup:/opt/oracle/variables:Z
        ports:
            - 8181:8181

volumes:
    oradata-vol:
    ords-config-vol:
networks:
    backend:

Store the file in a directory of your liking as compose.yml.

If you are unfamiliar with compose files, I suggest you look at the reference documentation.

Note that the Oracle DBA passwords are provided as part of this file, which is a Very Bad Practice and one of the reasons this file isn’t suitable for production use. However, the passwords are used for the initial setup only; later, you can read how to reset them after the setup is complete. Unfortunately (Podman) secrets didn’t work with the compose file, or else they would have been used.

Firstboot: installing APEX and ORDS

The database must be started first. Otherwise, the ORDS container cannot perform the APEX installation.

podman-compose up dbfree

The database should be up and running in less than a minute – the first step has been completed. Now, please create a directory named setup in the same directory storing the compose.yml file and create setup/conn_string.txt with the following contents:

CONN_STRING=sys/secretPassword@dbfree:1521/freepdb1

The connection string in this file is used to install APEX and ORDS in freepdb1. Start the installation by bringing the ORDS container up.

podman-compose up ords

The ORDS container will detect the absence of a configuration and use the information in conn_string.txt to connect to the database and perform the APEX and ORDS installation. After the installation has been completed, you can test if it was successful by connecting to ORDS using your favourite browser. How do you know if the installer completed its work? Your terminal should show you something along these lines:

java.vm.version=11.0.15+8-LTS-149
sun.io.unicode.encoding=UnicodeLittle
jdbc.InitialLimit=10
db.connectionType=basic
java.class.version=55.0

2024-01-11T10:51:09.473Z INFO        

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


2024-01-11T10:51:09.522Z INFO        Oracle REST Data Services initialized
Oracle REST Data Services version : 23.4.0.r3461619
Oracle REST Data Services server info: jetty/10.0.18
Oracle REST Data Services java info: Java HotSpot(TM) 64-Bit Server VM 11.0.15+8-LTS-149

You should see the ORDS landing page:

Once you’re happy that your installation completed successfully, remove setup/conn_string.txt if it still exists. Otherwise, the ORDS container assumes that the installation has to be repeated. You should also change the DBA passwords as described in the container image’s documentation.

And while you are at it, change the default APEX admin password as well. Log in to the INTERNAL workspace as described in the documentation to change the password.

Next steps

After the validation of your environment, you can perform multiple steps:

Change all passwords as mentioned above if you haven’t already
Stop the environment using podman-compose stop
Check the status using podman-compose ps
Start the APEX environment when you need it using podman-compose start
Check the logs of either container using podman logs . Adding the -f flag tails the log

Experiment with server-side JavaScript in APEX :)

Summary

Getting to a working APEX development environment for your lab with just two commands (initially, later, it’s just one) is quite the time saver. Please remember that the procedure described in this post is merely suitable for your own lab. Have fun!