đź’ˇ
NOTE: this is a follow-up post from my last entry,
Container Yourself. It’s best to start there if you’re going to follow along and perform the steps outlined here.
I didn’t really notice this, but the version of APEX that I downloaded was 24.1.0. Thus, I’m six patch sets behind what’s current as of the publish date of this post.
Remember: APEX patches typically contain two parts:
Container Differences
In the world of containers, things are a little different - especially with the ORDS Developer container. Looking into how it’s setup, when ORDS starts, it points to a specific location in the container for the APEX images. And that path is somewhat hard-coded.
Here’s the the two commands that run when ORDS starts up:
APEXI=/opt/oracle/apex/$APEX_VER/images
ords --config $ORDS_CONF_DIR serve --port 8181 --apex-images $APEXI
$APEX_VER gets translated into 24.1.0 in this case, so the APEX images directory becomes /opt/oracle/apex/24.1.0/images. Since this is in the container’s filesystem, there’s no easy way to make updates to the images in there and have it persist.
Verifying an APEX Release
To figure out which release of APEX you’re running, you’re going to need to do one of two things, depending on whether you’re looking at the database objects or the “images” directory.
I use “images” lightly here, as most of what APEX relies on these days are Javascript and CSS files. Looking at some of the images that are included, they date back to HTML DB 1.5, where tabs were constructed by assigning images to <td> tags in an HTML table. Good times!
APEX Database Objects Version
The name of the schema is an obvious tell here - APEX_240100 is clearly APEX 24.1. But it gives you no clue as to the patch sets that have been applied. To get that, we have to run the following:
select version from dba_registry where comp_id = 'APEX';
This will return a more specific version of APEX, like below:
APEX “images” Files Version
Hidden in the root directory of the APEX images directory is a file called apex_version.js. The contents of this file are simple:
var gApexVersion = “24.1.0”;
This will always have store the three-digit version of the APEX images directory.
If you don’t have access to the filesystem, simply enter the following URL to see this file’s contents in a browser:
https://servername.com/i/apex_version.js
Upgrading All the Things
So it’s obvious we’re running APEX 24.1.0, and need to upgrade to 24.1.6 - the most current release at the time this was written.
The database side is pretty straightforward - run the patch as SYS and you’re done.
The filesystem part is a little more involved. Since we can’t modify anything in the container, we need to host the files outside of the container. My first thought was to use the APEX CDN point to the proper version. That is a viable solution, so as long as you have network access to the CDN. Since one of the goals here was to have a portable development system that did not rely on the internet, I had to come up with something else.
We can host the APEX image directory locally, and when we run the ORDS container, we can add a parameter to map the directory that the container uses (/opt/oracle/apex/24.1.0/images) to our local directory - which we will then upgrade to 24.1.6.
Let’s walk through the steps do to this.
Download and Stage the APEX Images Directory
First of all, we need to download the APEX 24.1.0 images directory. This can be found in any distribution of APEX itself.
You can find and download all versions of APEX here:
https://www.oracle.com/tools/downloads/apex-downloads/
In this case, I simply downloaded and unzipped the English-language only version.
Next, we need a place to stage these files that is relatively permanent. I chose to move the whole images directory to the same top-level directory that I used to store my ORDS configuration and secrets. Here’s what it looks like in the filesystem:
I simply copied the images folder from the patch directory to my custom directory by dragging it via the Finder; you can move it any way you like.
Restart the ORDS Container
Now that we have our custom images directory in place, let’s use a slightly different command to create a new ORDS container. This command contains an additional volume mapping that will use our images directory in place of the one in the container.
Terminate your existing ORDS container via Podman
Open a new terminal window
Change directories to the directory that contains your images, ords_config and ords_secrets directories
Run the following command:
podman run --rm --name ords -v `pwd`/ords_secrets/:/opt/oracle/variables -v `pwd`/ords_config/:/etc/ords/config/ -v `pwd`/images/:/opt/oracle/apex/24.1.0/images -p 8181:8181 container-registry.oracle.com/database/ords-developer:latest &
This additional volume mapping - -v `pwd`/images/:/opt/oracle/apex/24.1.0/images - will point the container images directory at our local directory - which right now should have identical contents.
From now on, this is the command that you want to use when re-launching ORDS containers.
Confirm the Directory Mapping
Let’s confirm that the change worked.
Open a new browser.
Enter the following URL, replacing servername.com with your hostname:
https://servername.com/i/apex_version.js
If successful, you will still see this text:
var gApexVersion = “24.1.0”;
Download and Install the Patch
Now that we have the volume mapped, we will need to download and install the patch for APEX 24.1.6. This patch can only be downloaded from Oracle Support with a valid account. For reference, the patch number is 36695709.
Once you have downloaded and unzipped the patch, follow the instructions in the README.txt file to install the database side of the patch. This should take no more than a few minutes.
When you get to Step 7 of the patch, follow the instructions with the assumption that the /images directory on the APEX server is the one that you’re hosting on your local machine.
In my case, this was the command that I ran from within the main patch directory:
cp -rp images ~/Podman/freepdb1/
Verify the Patch
Now that the patch is applied, let’s check both places to ensure that it was successful.
First, the filesystem:
Open a new browser.
Enter the following URL, replacing servername.com with your hostname:
https://servername.com/i/apex_version.js
If successful, you will still see this text:
var gApexVersion = “24.1.6”;
Next, the database:
Open a new terminal window and connect to your database a SYS
Run the following command:
select version from dba_registry where comp_id = 'APEX';
You should see the following:
Summary
Congratulations! Your container database is now running APEX 24.1.6, and your ORDS container is using your local directory to provide the correct files for that release.
You should be able to stop & start the ORDS container as often as you need using the command referenced in the Restart the ORDS Container section.
One thing to keep in mind is that you no longer need to create a conn_string.txt file to start to the ORDS container. In fact, if you do, you will get an APEX version mis-match error.
And lastly - just another reminder that the database running in your container is volatile. If you delete the container, you delete the database, too. You will then need to create a new container from the Oracle 23ai image, install APEX, upgrade to 24.1.6, etc. to restore your configuration.
Title Photo by Amira El Pohail on Unsplash
