Running the OAS 5.5.0 Client tools on Ubuntu 20.04 Focal Fossa

Running the OAS 5.5.0 Client tools on Ubuntu 20.04 Focal Fossa

Published on: Category: Oracle

An annoyance working with OAS, as with its predecessor OBIEE, is the fact that one of the core design components, the Oracle BI Administration Tool, is only supported on MS Windows. However, it has already been shown that it actually can be run if you use Wine on Linux. The post on Rittmann Mead by Borkur Steingrimsson for OBIEE 12c shows that it can work and connect both online and offline.

The main problem is the lack of a proper ODBC administrator application in Wine, equivalent to odbcad32 in MS Windows. At least for online use, an ODBC DSN for the BI server must be registered to connect to an online BI server repository. In the Rittman Mead article, the ODBC administrator is installed using MDAC2.8 and “Wine tricks”, but on a current 64-bit installation this doesn’t seem to work anymore. Also, there seems to be a reluctance to support “Wine tricks” in the Wine community itself.

However, it turns out you don’t actually need an ODBC administration GUI. Using the Wine registry editor, the driver registration can be done directly.                                                                                                     

To test things, you will need a running OAS instance. This procedure can also be used for OBIEE 12c where the sampleapp607 virtualbox appliance could be used, but there doesn’t seem to be an equivalent for OAS at the moment. However, in this post by Gianni Ceresa we can find a fairly straightforward OAS setup that uses Docker.                


To follow the steps in this article, you need to download some software first. In this example, I’m using Ubuntu 20.04 (the latest LTS at the time of writing) as the host OS.

Oracle VirtualBox: Although this is available in the software store, it’s better to use the latest version.

Docker: Using Ubuntu 20.04 as host, this can easily be set up straight from the apt repository.

Ubuntu 20.04 installation image: This is used to create a separate virtual machine specifically for the Administration tool.

A Git client for cloning docker-images from the GitHub repositories. When using Ubuntu as a host (as I am doing), you can install the command line git from the apt repository.             

Oracle BI Administration Tool installer: The installer must be the same version as the server it is going to connect to. This page also has links for FMW and OAS, but Gianni’s buildscript assumes the ZIP files are downloaded from e-delivery, as shown in his post.

This article assumes some familiarity with VirtualBox and Docker. It is assumed the downloaded files are extracted correctly and pass hash key verification. If not, the installations can fail in unpredictable ways.

Setting up the admin tool VM

For the BI admin tool, we are going to use an Ubuntu 20.04 virtual machine installation. Using the installation iso image, we create a completely new machine using the minimal installation. Make sure you have both a NAT and a Host-only network configured on 2 adapters and at least 30 GB disk space. Personally, I prefer to make the latter a fixed size. For ease of use you might also want to enable drag & drop and clipboard bi-directional.

By mounting the Ubuntu iso image before startup, we can create a minimal installation for now.

After installation you should restart, then first run the software updater. This will take some time.

After restart, it is advised to install the Guest Additions. Because of the “minimal installation”, a few prerequisites are missing, however. These need to be installed first, so use a command line.

$ sudo apt update
$ sudo apt upgrade
$ sudo apt install build-essential dkms linux-headers-$(uname -r)

When they are installed, the Guest Additions can be installed from the VirtualBox Devices menu.

Enable the Guest Additions by restarting, then proceed with installing Wine. Because the Guest additions are now active, the following lines can be copy-pasted from this article.

$ sudo dpkg --add-architecture i386
$ sudo apt update
$ sudo apt install wine64 wine32
$ winefile

The “winefile” command should initialize Wine and open the Wine File Manager.

The virtual machine is now ready to install the admin tools. Transfer the Windows installer to the Oracle Home Directory using your preferred method, then extract it there.

Use Wine to start the installer.

$ wine OAS-5.5.0-bi_client-win64.exe

During the installation process, accept all the default values.

After installation, you should now have the admin tools visible as applications on the new Ubuntu virtual machine.

Setting up the target OAS 5.5.0 instance using Docker

At this point, it is possible to work with the administration tool in offline mode, but an OAS target and a database is needed to do something useful. If an OAS instance is already available, this part can be skipped.                                                      

The last part of Gianni's post outlines the procedure to get OAS 5.5.0 up and running while using Docker. This procedure uses a combination of the SingleInstance Docker image and Gianni’s OracleAnalyticsServer Docker image. Make sure you verify the bridge IP address used by the Oracle database container. You need it during the build of the Analytics server container as target host for the RCU database.

Once the installation and container setup are done, you should have 2 containers. Always start up the database container first. Verify if it is up and running.

If you have an Oracle client or an SQL developer available on the host, you can connect to localhost:1521:orclpdb1 directly. If not, you can start a bash process on the container and use sqlplus directly in the container.

$ docker exec -it <Oracle Database Container Name>

Once the database is up, the OAS container can be started. This might take a while because it is quite CPU heavy. You can track the status by attaching to the container after starting it up, but be aware that exiting then brings the container down again.

$ docker attach oas55

Using your regular browser on the host machine, you can verify the OAS instance on the host.





When you want to bring down the containers, first stop the oas55 container before shutting down the database container.

Configuring the BI Administration Tool to connect to OAS.

Now that an OAS instance and a database instance are available, we want to connect to them with the BI Administration Tool. If you try to connect online from the file menu right after the installation, you will get an error message that no system data source is defined.

On a Windows machine, you would use the ODBC administrator to define this, but there is no standard equivalent in Wine. However, we can define data sources directly if we use the Wine registry editor.

First, we need to verify that we can actually see the OAS container. The trick here is to use the fact that the docker image exposes the OAS ports to localhost. You can use these to access OAS with your host browser. Because the virtual machine is set up using a host-only network, the host itself is “visible” from the virtual machine on the host IP configured in VirtualBox. In our case

Because of this, we can use this IP address in the URL in a browser on a virtual machine itself.

Create a new .reg text file on the virtual machine with, for example, vi. Copy-paste the text below into the new file. Name it something like OAS55ODBC.reg. The file can now be imported into the registry editor using Registry → Import Registry File …

Windows Registry Editor Version 5.00


"OAS55"="Oracle BI Server-Oracle_Home"


You should get a confirmation that the file is successfully imported. If so, close the registry editor.

When you open the BI Administration Tool now, it should show the OAS55 entry when attempting to open an online repository.

Using the WebLogic account, you can now log onto the online repository of your OAS docker container.

Unfortunately, there are some bugs in play here which prevent, for instance, the help text to be displayed and the Query Related Objects right click submenu doesn’t work. These issues seem to occur quite frequently in Wine, so perhaps they can somehow be solved.

Importing objects in the physical layer from the Oracle database

Importing objects is fairly straightforward. The most important thing to remember is to use the Connect descriptor syntax for the data source.


The sample schemas, as shown in the example below, are not included in the database docker image and should be installed seperately. The scripts for are also not available but can be found on the Oracle github page here.

Running the catalog manager

The catalog manager is actually a Java program, but as it is installed together with the BI Administration Tool under Wine, it can be run with Wine as well.       

Again, we’ll use the host-only target to connect. Make sure to use the correct URL with analytics-ws, instead of analytics.

You will get a warning that an unsecured URL is used.


We would not recommend this setup for an enterprise environment as it is rather buggy and not supported. However, you would expect Windows licenses in such an environment anyway. This setup is intended for personal training or development using a non-Windows host (as I have). As stated before, the setup for the OBIEE 12c Administration Tools is pretty much identical. I hope this guide is useful for this purpose. Happy OAS-ing!

Patrick Schoenmakers
About the author Patrick Schoenmakers

Experienced Consultant with a demonstrated history of working in the information technology and services industry. Skilled in Oracle Database, Agile Methodologies, Data Warehousing and PL/SQL.

More posts by Patrick Schoenmakers