This post will be something of a followup to my Kscope22 presentation on creating an Essbase 21 Docker image. Back in June during the presentation, I mentioned that while the images I had created prior to the conference were working fine, when I went to rebuild them for purposes of confirming the presentation details and creating new screenshots, I was inexplicably running into issues with the Essbase server. It would seem to start up fine, but I couldn’t actually login. I now know what that issue was and in the steps that I’ll describe in this post, I’ll call out what the fix is.

Unlike my previous efforts to build an Essbase Docker image based on the EPM 11.1.2.4 product line, the Essbase 21 Docker image actually relies on Oracle’s own scripts that they provide. This post will completely walk you through everything you need to do to create your own Essbase 21 Docker image, including how to patch it to a later point release such as 21.3, how to fix the bug I was running into in June, how to run it, load some sample data, share it with others, and different URLs for using the REST API, XMLA, and more.

Requirements

In order to build an Essbase 21 Docker image, you’ll need to have a few things:

• Git
• Docker
• Installation media for Oracle Java, Fusion Middleware, and Essbase 21 (I’ll explain how to get these)
• Linux server

Overview

In order to successfully build the Essbase 21 Docker image, we need to build an Oracle Fusion Middleware (FMW) Docker image, and in order to build the Fusion Middleware image, we need to build the Oracle Docker image. This is because the Oracle Essbase essentially sits on top of the FMW image. The following is a general overview of the process you’ll be following:

• Use Git to clone the Oracle Docker GitHub repository
• Download the various installation media that you need (Java, FMW, Essbase, and any patches you might need or want)
• Stage the installation media in with your cloned files from Oracle’s GitHub repository
• Build the Java image
• Build the FMW image
• Build the Essbase image
• Optional: push the Essbase image to a container registry

Clone Oracle Docker Images Repository

You’ll need to clone (download) the files from Oracle’s Docker images GitHub repository. You don’t strictly need Git to be installed since you could just download a ZIP of the repository, but you probably have Git installed already and if you’re really scared of the Git command-line interface, you could always download and use GitHub Desktop. If you browse to Oracle’s GitHub repository, you can see that the layout of the files looks like this:

Just to be absolutely clear, this is not a Docker repository or a Docker container registry, and there are no installer/binary files in this repository. This repository basically contains scripts for building Docker images for various Oracle products. This repository is organized with a folder per project. We’ll be working in the OracleJava, OracleFMWInfrastructure, and OracleEssbase folders, as those contain the Docker files (but again, not the actual installation media, which we still need) for helping build the Docker images. After you clone or otherwise download Oracle’s files, you should have a local folder with the same files:

As I mentioned earlier in the requirements, you’ll need/want a Linux server with Docker to build the Docker images. Actually, I don’t know if that’s strictly true. You might be able to run Oracle’s build scripts (written in Bash) on a Mac, and you might be able to run them on Windows (using WSL), but I haven’t tried – even though I run on a Mac, it has an M1 CPU which makes things a little trickier. So for building these images, I am using a ‘regular’ Linux server. Generally for my Docker stuff I am either using a physical server running on my home network (a Xeon-based system running Ubuntu 18.04), but for the blog I am using a Linux system that I spun up on Digital Ocean which is running Ubuntu 20.04. You could use a Linux EC2 system on AWS too and that should work just fine. On the Digital Ocean Ubuntu server, I installed Docker via a “snap”, which mostly worked fine although because I have the Oracle files staged on a separate drive, I wound up having to run snap connect docker:removable-media in order to grant the Docker service access to the drive. If you install Docker through apt or just have your files on the normal drive, you shouldn’t have to worry about this. I purposely added the removable drive/volume to this instance because I wanted to be able to easily attach it to some other system in the future.

Download Various Installation Media

Now that we have the scripts from Oracle’s repository (the recipe, if you will), we now need to stage in the various media (the ingredients). In this analogy, actually running the build scripts is akin to baking the raw cookie dough in our oven, and the resulting Docker images are the baked cookies. To stretch the analogy a little further, running the Docker image as a container is us eating the cookies.

Java Installation Media

Getting the proper Java installation media is a little bit tricky for a couple of reasons. One, we need a very particular type of Java installer. Two, there is sometimes a mismatch between the version of Java that the Oracle Docker Java image wants and what we can easily download. And three, there is an issue with versions of Java newer than Java 1.8.0 update 331. If you remember me saying during Kscope22 that I was having issues with the Docker Essbase images I was building, in that they would seemingly build fine but then not actually work correctly, well, it turns out it is a very subtle Java issue. What is happening is that versions of Java 8 newer than and including update 331 had a very small change that impacts the Oracle FMW image, which in turn impacts the Oracle Essbase image. In order to sidestep this, we can either use a build of Java older than that, or we can apply a patch during the creation of the Oracle Essbase Docker image that patches FMW. We’ll opt for the latter approach, which is the ‘right’ thing to do.

That said, we are still left with a small issue of getting the proper Java media and dealing with any version mismatches. What I mean by this is, let’s take a look at the Dockerfile for the Oracle Java 8 Docker image over in the Oracle repository. The Dockerfile is the file that the Docker engine reads in order to build the actual image. It’s basically a list of commands to run on a Linux server that creates the thing we want, usually by copying in files, running scripts, creating folders, and other things. In the case of the Oracle Java Docker image, basically what it’s doing is copying in the Java installer, installing tar and gzip (so that it can actually extract the Java files), and creating some symbolic links. At the time of this writing, the Oracle Java 8 image is built specifically with server-jre-8u341-linux-x64.tar.gz – Server JRE 8 update 341. The “problem” here is that it’s difficult to find the Java media for 341 right now. I had this problem earlier when the Java Docker files were built with Java 8 update 333 but all I could find that was easily downloadable was the 331 media. And something similar is going on right now where the official files are looking for update 341 but the public download site doesn’t have it.

There are a few ways we can deal with this, but I think the best and simplest is this: go to the public Oracle Java download site for Java 8 update 211 and later, and then scroll down to find the absolute latest version of Java 8 in the form of the Server JRE for Linux, such as the 333 file shown here:

After that’s downloaded, you need to stage this file inside the docker-images/OracleJava/8 folder, so that a directory listing in that folder looks like this:

Next, if you have a mismatch between the version referenced in your Dockerfile and the version you downloaded, let’s update the Dockerfile so that it’s consistent with the version we downloaded. This means we need to edit three places in the file: two references to the filename, and one reference to the SHA256 file checksum. We can determine the SHA256 sum of the file by running the command sha256sum server-jre-8u331-linux-x64.tar.gz. After updating my file for the 331 version of Java, the top of the file now looks like this (this shows two of the updated lines, the third is lower in the file):

Again, if you have a matching Java version (e.g., you are able to download the 341 version of Java because you can find it or have an Oracle Java support contract), you don’t need to do this. Alternatively, you could checkout an older version of this repository where the Java version matches what’s available, but that approach could be problematic.

In any case, at this point you should now have everything set to be able to build the Java Docker image. You could build that now if you wanted, but in this guide we are going to stage the rest of the installation media and then do the builds.

Fusion Middleware Installation Media

Thankfully, this part is a bit simpler than some of the shenanigans we had to go through with the Java media. We just need one file. We’ll be working in the OracleFMWInfrastructure folder this time. Specifically, we need to stage the FMW installation media in the /docker-images/OracleFMWInfrastructure/dockerfiles/12.2.1.4 folder. You need to go get a file exactly named fmw_12.2.1.4.0_infrastructure_Disk1_1of1.zip, which you can find by going to the Oracle WebLogic Server Installers page, and then scrolling down to find the Fusion Middleware Infrastructure Installer in the 12.2.1.4 section:

Once downloaded, stage it in the 12.2.1.4 folder I mentioned, so that your directory listing looks like this:

That’s all we need to do for the FMW piece for now, until we build it. The patch that I mentioned we need for Java versions 8u331 and beyond will be applied to the Oracle Essbase image itself, not our FMW image, so we don’t need to worry about that here.

As a brief aside, note that in the README for the OracleEssbase Docker project, the original creator mentions that in lieu of creating our own FMW image (and Java image), we could potentially just download (via the docker pull command) Oracle’s FMW image from the Oracle Container Registry, tag it appropriately, and then use that instead of building our own. This sounds great, however, I tried to do just this and the Essbase image didn’t build for me. I think there may be some subtle configuration thing I haven’t quite figured out. If I can figure it out then in the future I may post an update, but for now I’m just relying on the method where we build everything ourselves.

Oracle Essbase Installation Media

Now on to staging the appropriate Essbase installation media. At an absolute minimum, you will need the Essbase 21.1 installer file. Realistically, what you’re going to want is a little more:

• Essbase 21.1 installer: this file is essbase-21.1.0.0.0-171-linux64.jar and is available from Oracle (eDelivery/Oracle Software Delivery Cloud). Even if you are planning to build an Essbase 21.2/3/4 Docker image, you’ll still be using this base media, as the way you get to, say, 21.3, is that you build an 21.1 server and then patch it to the eventual version (more on this in a bit)
• WebLogic patch for Java 8u333+ login bug: you’ll want the patch for WebLogic that fixes the issue I mentioned at Kscope. This is a file called p34065178_122140_Generic.zip and can be downloaded from Oracle support.
• Essbase version patch(es) optional: for example, the patch file to go from 21.1 to 21.3.2 is named p33925737_213000_Linux-x86-64.zip and can be downloaded from Oracle Support (more on this in a bit too). If you are fine with just an Essbase 21.1 server, then you don’t need to worry about any patches.

Let’s go get these files and stage them. Head over to Oracle Software Delivery Cloud and login, then search for Oracle Essbase. You should see something like the following:

You might be tempted by the download for Essbase 21.3, but that actually only contains Windows binaries, which were first made available in version 21.3. What we need and want is the Essbase 21.1 download, which is specifically for Linux (which is what our Docker images are based on). After downloading, you may end up with a zip file. If you do, unzip it to get a JAR file and then stage that in your docker-images/OracleEssbase/dockerfiles/21.1.0 folder, so that a listing of the files looks like this:

At this point, if we wanted to we could build the Java image, the FMW image, and then the Essbase image, but if we went to go start up the Essbase container, we wouldn’t be able to login due to the subtle Java issue I mentioned earlier. So let’s go get that patch from Oracle. Login to My Oracle Support, click on the Patches & Update tab, then search for patch number 34065178:

You should get the following patch in the results:

It’s a little hard to tell, but basically you can see that this is a patch for the Oracle Virtual Directory component, version 12.2.1.4.0. Download the patch and stage it in docker-images/OracleEssbase/dockerfiles/21.1.0/patches so that the contents of this folder look like this:

At this point, you have all of the files staged properly and assuming you have Docker installed and running, we can start to build the images.

Docker Image Build

The process here is that we’re going to build the Oracle Java image, then the FMW image (which relies on the Java image), and then the Essbase image (which relies on the FMW image).

Docker Java Image Build

Let’s go back to the docker-images/OracleJava/8 folder, which is where we will find the build.sh script we’re going to run, which will build the Oracle Java image for us. Enter ./build.sh to run the script:

If all goes well, you should see output similar to the following (your checksums may differ if you’re using a different Java version or the scripts have been updated from when I did this):

You now have an Oracle Java Docker image that is built on your local machine, and that you could run right now and do things with. You should be able to run the docker images command to get a listing of the Docker images that are available on your machine, and you should see new or existing entries for the Java images (oracle/serverjre:8 and oracle/serverjre:8-oraclelinux7):

You don’t really need to worry about these Java images directly, we just need them so that the next steps to build the FMW image will work, since they rely on the Java image.

Build the FMW Image

Navigate over to the docker-images/OracleFMWInfrastructure/dockerfiles folder, and then run the command ./buildDockerImage.sh -v 12.2.1.4:

This will take a few minutes (on this system it took 276 seconds), and then you should have the FMW image built locally. Now we can head over to the Essbase folder. Navigate to docker-images/OracleEssbase/dockerfiles. At this point you should only have two things there, a folder named 21.1.0, and a script called buildContainerImage.sh. On my system there are other folders, which I’ll discuss in a moment. Similar to what we just did with the FMW build, we’re going to run the buildContainerImage.sh script with a version flag in order to build the Essbase 21.1 image. Run the command ./buildContainerImage.sh -v 21.1.0 as in the following:

You’ll see a bunch of output for awhile. Basically what is happening is that a miniature Linux VM with WebLogic on it is being run in the background, and then the series of commands to copy, extra, install, and configure Essbase 21.1 on are being run on it. So it’s basically a console Essbase install where a response file is being used (instead of doing a console install interactively, or using the installer GUI). If all goes well, then at the tail end of the output, you should see something like the following:

At this point, we’ve now built an Essbase 21.1 image that exists on this local machine only. You can see in the output what we wound up with an image named oracle/essbase:21.1.0. In Docker parlance, this identifies an image with the repository named “oracle”, an image name of “essbase”, and an image tag of “21.1.0”. At this point, we can run the image on this machine. If you want to publish this image to your own container registry so that your colleagues can use it without having to go through the hassle of building it, there is another step you must take. I’ll cover that below. Let’s go ahead and run this image now and after that I will talk about patching to newer Essbase 21 versions, publishing, and more.

Start an Essbase 21 Container From Your New Image

Again, at this point we have an Essbase image that we built, but not a container (a running image). Presumably what you want is to have an actual Essbase server you can do things with. The Oracle repository that we cloned, in addition to having the Docker files that we used to build the image, also contains some samples to help us run an image. In the OracleEssbase folder, you’ll see the samples folder. In there, you’ll see the docker-compose folder. Finally, inside of that you will see three other folders:

These samples are based on the Docker Compose technology. This tool is often used by developers to run servers that have multiple services. In our case, we have two: an Essbase service (i.e., a server with just Essbase on it), and a relational database (which contains all of the schemas that the Essbase server uses to store information). I will go ahead and say that 99% of my experience using the Essbase 21 Docker Compose files is with SQL Server, using the files provided in the single-node-sqlserver. The other folders contain samples with slightly different configurations. I like the SQL Server configuration because that’s what I used when I developed all of the Essbase 11.1.2.4 Docker stuff, so I’m more comfortable with it, and secondly, SQL Server Docker instances come up very fast. Additionally, SQL Server has public images available so it’s one less thing we have to build here. So we’ll go in to the single-node-sqlserver folder and look around:

There are a couple of convenient scripts here for starting and stopping things. Let’s kick off the start_essbase.sh script. The first time you do this, if you don’t already have the Microsoft SQL Server Docker image locally, then the Docker image is going to pull it from the Microsoft Container Registry. This is a one-time thing; afterwards, you’ll have a local copy that will be used on subsequent executions. Once that’s done and the next steps proceed, you should see the following, indicating that it’s waiting for the Essbase service to be available:

Basically, there’s a script that’s on a loop and it’s pinging the Essbase service on the WebLogic server and waiting until it gets a valid response, indicating that the service has come up. The amount of time that this takes seems to vary. On my home Xeon server, it can be 30 seconds to a few minutes. On some cloud servers I’ve used, it can take substantially longer (I think sometimes the startup can really drag on with some of my cloud servers because of some weird DNS/networking issues, but I’m not totally sure). In any case, eventually you should see the output say Essbase service is ready at http://localhost:9000/essbase, indicating the the Essbase service is running. Of course, since I’m running this all on a remote server, trying to access localhost doesn’t do me much good. However, if I want to do a quick sanity test and see if I can reach, say, the Essbase APS server (one of the middle tier nodes that Java clients talk to), I could run a simple local curl command to see that I get something back, such as running curl -X GET http://localhost:9000/essbase/japi:

This might be a nice and quick test just to make sure it’s up, and if you are unable to access the Essbase web services/interface remotely but you are able to get to things locally, that might tell you if you have a firewall issue you need to sort out. Let’s try and login by navigating to the Essbase sign-in URL, located at http://server:9000/essbase/jet:

The default (although configurable) credentials to login to these servers is username admin and password welcome1. Sure enough, we are logged in and looking at our server with exactly zero applications right now:

I won’t go in to laborious detail since it is better covered elsewhere, but if you want setup the classic Sample Basic application, you can click on Import, then navigate through to the Gallery and demos and find the Sample_Basic.xlsx file, as shown below:

Afterwards, we have a live Essbase application/database (cube):

There you have it, we have now built our very own Essbase image and started it up. Similar to how we started it up, you can see the stop_essbase.sh script to shut it down. There’s not really a lot going on in the script, it’s just basically calling the Docker Compose system with the stop command to shut the two containers (the SQL Server and the Essbase server) down at the same time. You could kill the containers using a docker command or your GUI tool but it’s a lot more graceful to shut them down properly. Here’s the thing, though: if you stop the server with the stop script, and then start it back up with the start script, that’s basically a whole new server – and any databases you may have imported or created will be gone. Keep that in mind for the moment.

Okay, so we have a built and working Essbase 21.1 Docker image. That totally works fine and will probably suffice for most of your needs. But you might need or want a 21.2, 21.3, or newer image. The next section will talk about the process for doing this, which is pretty similar to what we just did.

Optional: Patching to Essbase 21.3 and Beyond

Let’s say we want to build an a Docker image of an Essbase 21.3.4 server. We are basically going to start with 21.1 server and then patch it up to the level we want. We can patch a 21.1 server to 21.2, or we can patch it up to 21.3, or 21.4, or whatever. The key thing to note is that we don’t have to apply all of the in-between patches. In other words, we can go straight from 21.1 to 21.3 without having to do the 21.2 patches. The process for building the image is basically the same as before, but we’re going to go download the patch we need from My Oracle Support (MOS). You may have noticed that in your OracleEssbase/dockerfiles folder there is a folder named 21.1.0 (although in my example, there are folders for 21.2.0 and others). The way the architecture of the buildContainerImage.sh script works is that we’re going to pass in the version flag to build, and then it’s going to look in a subfolder of the same name.

So first of all, let’s make a copy of the 21.1.0 folder named 21.3.4. You can accomplish this with the cp Linux command, such as cp -R 21.1.0 21.3.4. This will make a copy of the folder, including that 21.1 install media, and hopefully your Oracle Virtual Directory patch that we staged earlier. We will then add in the Essbase patch from Oracle. The easiest way (that I know of) is to login to MOS, navigate to Patches & Updates, and then in the Patch Search window, select Product or Family (Advanced). Then configure the Product, Release, and Platform as Hyperion Essbase, Oracle Essbase 21.3.0.0.0 (or whatever version at the time of this writing), and Linux x86-64 respectively, as in the following screenshot:

The list of patches will look like the following:

The file we want for patching to [in this case] Essbase 21.3.4 is in the firs trow. Note that there are a couple of “SCRIPTS” patch types. You don’t need those. I believe that much of the development going on in these minor patch updates is to dial in Essbase clustering support, and the script patches are only needed if you’re planning to do that. I am hoping to have my team look at these scripts later on so we can do some testing with clustering, but that’s for another day. After downloading, stage the patch file in the patches/ folder so that it looks something like this (note this is a screenshot from 21.3.2):

Note the patch file starting with p3392. As with before, we still have the directory patch in there, right below it. Now we can build the image, much as we did before, by using the buildContainerImage.sh script, but this time specifying the version:

Again, the version flag tells the build script which folder to work in, but it also controls the tag that will be used with the resulting image. Whereas before we built an image named essbase with the tag (version) 21.1.0, we are now going to end up with an image of the same name but a different tag, in this case, 21.3.2 (my apologies for bouncing around a little bit with the versions such as 21.3.2, 21.3.4, and 21.4 – the process is exactly the same, so don’t worry about the particulars too terribly much).

If you are a software company such as us, you may find yourself wanting or needing to build all of the different point releases of Essbase 21 in order to download the Java JAR files, to do testing, and other things.

Running a Patched Version of Essbase With Docker Compose

Now that you’ve built a patched version of Essbase, you might want to actually run it, right? We can use the Docker Compose scripts we used before (in the single-node-sqlserver folder), but we need to make an adjustment. When you use the start_essbase.sh [convenience] script, basically what it’s doing is using Docker Compose, and what Docker Compose does is it looks for a file named docker-compose.yml to figure out which services you want to bring up. In our case, that’s basically a Microsoft SQL Server container and our Essbase container. Let’s take a quick peek at that file though:

Note the highlighted line starting with image: this is the line of the Compose file that provides some details on the Essbase container that should run. The configuration value for the image name has a value of “${ESSBASE_DOCKER_IMAGE:-oracle/essbase:21.1.0}“. You can read this as the following: the value of image should be the contents of variable $ESBASE_DOCKER_IMAGE, and if that’s not set, then default to the value of oracle/essbase:21.1.0. So, everything is totally fine here if we just want to run our 21.1.0 image. But we want the 21.4.0 image, so we either need to edit this file manually or we need to provide a different value for the ESSBASE_DOCKER_IMAGE variable. There are actually quite a few ways we can do this, but the way I’m going to do it here is that we will provide our own variable values in a file named .env. Let’s run a directory listing that will show hidden files (on Linux systems, files starting with a dot are “hidden”) using ls -lah so you can see that I just have a .env file in the same folder as these other files:

Now I’ll use vi to edit the .env file (vi .env), and we can see the following contents of the file:

With this file in place, when I go to run start_essbase.sh (which, again, just runs docker-compose), it’ll consult the .env file and set the value of the ESSBASE_DOCKER_IMAGE variable to the value I specified. I like the approach of specifying a variable value in the .env file because it’s one less thing to remember in a command line, among other reasons. For example, you may want to distribute out a small set of files (start scripts and the compose file) to your colleagues so they can easily start their own local Essbase 21 server for testing and development).

Sharing With Others / Container Registry Overview

So far we’ve built our own Essbase 21 image and we’ve even built a patched version of the image so we can enjoy the latest and greatest features. This is all well and good for our local machine or perhaps some remote server. Now you kind of need to think about your next steps. If you are going to just stand up a simple Linux server as I have done, then you can call it good and just use that server to host Essbase 21 for whatever testing and development purposes you want.

However, you may have a more elaborate use case which is that you want anyone in your organization to be able to use the image, without having to go through the trouble of building it themselves. What you might want is to push this image to your container registry. I’m not going to go into exhaustive detail about this, but I will point out that here at Applied OLAP, we’re doing both: central test servers as well as the ability for people to run their own local image. This lets developers use a set of scripts to run a local Essbase server easily based on the images that have been built and pushed up to the registry. The short version of this process is that after building the image, we then tag it with a different name so that it we can push it to our repository, essentially this command:

docker tag oracle/essbase:21.4.0 appliedolap/essbase:21.4.0

Followed by a push command:

appliedolap/essbase:21.4.0

Some of our people have Windows versions of the start scripts (i.e. Windows versions of start_essbase.sh). I am looking into the feasibility of sharing those scripts or even better, getting them integrated in to Oracle’s repository. If you’ve made it this far and you want a copy, just contact me and I’ll send what we have over.

Common Essbase URLs

There are a handful of URLs that are useful on your Essbase server (I’ll write these in terms of localhost but you’ll need to edit them accordingly). Those of you that have been in the Essbase world for a long time probably know these, but those of you coming here because your company is currently endeavoring to check the box for Essbase support in your product and need to stand up a quick Essbase server so you can hit the XMLA endpoint may find this useful:

• Essbase JET UI: The modern, web-based interface that allows you to see your Essbase applications, create new ones, manage existing ones, and more. Kind of like EAS for the web, and less ugly
• Essbase REST API Swagger/OpenAPI: A web-based interface for testing the Essbase REST API as well as downloading the JSON definition file that you may be feeding in to a tool to generate bindings in your language of choice
• Essbase APS: Endpoint to configure the Dodeca Essbase connector (APSUrl) or for Essbase Java API connectivity that is going through APS instead of embedded mode
• Essbase XMLA: The Essbase XMLA endpoint
• WebLogic admin console: adjust settings for the entire WebLogic server, add an authentication provider, and more

The default username/password for all of these is admin/welcome1.