Container Yourself

Photo by OSG Containers on Unsplash

Container Yourself

Running Oracle Database 23ai & ORDS Locally via Containers

Scott Spendolini's photo
Scott Spendolini
·

9 min read

Table of contents

Overview

Having a local development instance offers a lot of benefits. It’s fast, it works from anywhere - with or without the internet - and you can configure it any which way you want. It’s also typically free to use, since most vendors - including Oracle - provide versions of their software at no cost for developers.

I find this very useful as a way to test out upgrades or ideas quickly, as well as a backup system that I can use for demonstrations in the case of an issue with my cloud databases.

In the old times, this would involve installing Oracle directly onto your laptop and configuring and managing it there. This was messy, and often conflicted with other software, creating a configuration nightmare. With today’s enterprise management tools, it may not even be possible to do it this way on your work machine.

Enter containers. Containers are portable, self-contained “units” that contain all of the things that an application needs to run. They make moving applications across environments a lot easier, as all of the dependencies are already included. There’s a ton of information on containers elsewhere; having some basic knowledge about containers may make this post a little easier to understand, but is not required.

Building the Environment

To build a containerized APEX environment, we will need two containers - one for the database and one for ORDS. We can visit the Oracle Container Registry and grab pre-packaged containers for each.

Before we get started, we need to prepare our local machine. While Docker is the most popular container management software, it’s not the only one. There are several alternatives, such as Podman & Rancher. This post will make use of Podman - mostly because it’s the standard at Oracle and installing Docker is typically not permitted.

Be Persistent

A note about persistence and containers. A container will typically keep its filesystem intact when it’s stopped. However, if the container is deleted, then the filesystem usually goes with it.

Of course there are ways around this, but this post won’t get into that. Thus, if you end up deleting the Oracle Database container, your database gets deleted, too. It’s best to ensure that all of your code, seed scripts and anything else that lives in the database is stored in script files that are managed in a version control system.

In the case of the ORDS container, persisting the filesystem doesn’t really matter since we inject local configuration information into that container each time it starts.

💡
Note: I used my MacBook Air M2 machine to build and test the containers in this post. Steps for other platforms may vary slightly and/or may not work the same.

Download & Install Podman

First, we’ll need to download and install Podman.

Podman is an open source alternative to Docker. Most Docker commands work just fine with Podman.

  1. Navigate to https://podman.io/

  2. Click Download

  3. Select Podman Desktop for your OS

  4. Once downloaded, install and start up Podman. You should see a screen that looks like this:

Download the Oracle 23ai Free Container

Next, we’ll need to download the container that contains the Oracle 23ai Free Edition. This can be done either via command line or from within Podman Desktop.

  1. Open Podman Desktop

  2. Click the Containers icon

  3. Click Create

  4. Click Existing Image

  5. Click Pull

  6. Enter the following for Image to Pull:
    container-registry.oracle.com/database/free:latest

  7. Click Pull Image

The container will start to download. Depending on your network speed, it will take a few minutes for this to complete.

Once it’s completed, it should look like this:

Click Done to complete this section.

Start & Configure the Oracle 23ai Container

💡
NOTE: In order to survive reboots, it’s better to create the container from the command line and set a fixed IP address. This section has been updated to reflect that.

Now that we have the container downloaded, let’s start it up.

  1. Open a new terminal window

  2. Enter the following command:

     podman run --name oracle --ip 10.88.0.2 -p 1521:1521 container-registry.oracle.com/database/free &

This will create a new container called oracle and set the IP address to 10.88.0.2. This is important, since the wallet will bind to the IP address, and having it change after each reboot will get annoying. It will also map port 1521 to local 1521, so that your muscle memory will work when typing connection strings.

  1. Switch to Podman to verify that it worked. You should see a single entry in the Containers tab for oracle.

Here’s the cool part - in just a few seconds - yes, seconds - we were able to spin up a fully-functional Oracle 23ai database.

Don’t believe me? Click on Actions > Open Terminal tab and run the following SQL:

sqlplus / as sysdba

While we have the Terminal open, let’s change the password of SYS & SYSTEM, so that we can connect from outside of Podman.

To do this

  1. Log out of SQL*Plus, if you’re still logged in

  2. Run the following command in the Terminal:

    ./setPassword oracle

In the above example, the password was set to “oracle”, but you can use anything that you want.

Now, you should be able to connect to this container from outside of Podman. Let’s try to connect with SQLcl.

  1. Open a new terminal from your local machine and enter the following:

sql sys@localhost:1521/freepdb1 as sysdba

  1. Enter the password that you just set, and you should be connected to the FREEPDB1 PDB, as shown below:

Download & Install APEX

💡
Note: This step should not be necessary, as scripts to install APEX are included in the ords-developer container. Despite multiple attempts, I could not get it to work; thus APEX needs to be installed manually into the database container.

To install APEX manually, follow these steps.

  1. Download APEX from https://www.oracle.com/tools/downloads/apex-downloads/

  2. Unzip the downloaded file to your local machine.

  3. Open up a new terminal and change directories to the /apex directory.

  4. Connect to the container database as SYS. You can use the following command to do so: sql sys/oracle@localhost:1521/freepdb1 as sysdba

It’s a good idea to create a dedicated tablespace for APEX. This keeps it separate from other schemas.

  1. Create a new tablespace with the following command:
    create tablespace apex datafile 'apex_001.dbf' size 300m autoextend on;

Now that we have our tablespace created, we’re ready to install APEX.

  1. Install APEX with the following command:
    @apexins apex apex temp /i/

This step will likely take a few minutes to complete, depending on your local machine’s specifications.

Once completed, there’s two more administrative tasks we need to do. First, we need to unlock the APEX_PUBLIC_USER account. This is needed for ORDS to properly connect to the database.

  1. To unlock APEX_PUBLIC_USER, run the following command:
    alter user apex_public_user account unlock;

Lastly, let’s reset the APEX administrator account so we will be able to login to the Internal workspace once ORDS is up and running.

  1. Run the following command and follow the prompts.

    @apxchpwd

Take the default values for the username and email. You will need to create a somewhat complex password that has at least 1 uppercase character, 1 number and 1 special character. This will be the password that you use to login to the ADMIN user in the INTERNAL workspace.

Here’s an example of what the output should look like:

The APEX database schemas & objects should now be successfully installed in your container database.

Download, Start & Configure the ORDS Container

This next step is pretty cool, as it will do the following:

  • Download the ORDS container

  • Configure the connection string in ORDS

  • Connect to your container database

  • Install and configure ORDS in the database

  • Install and configure APEX in the database

  • Start the ORDS Jetty listener so you can connect to APEX

Before we do this, there’s a couple pre-requisites that need to be completed. We need to create a pair of local directories and add a configuration file so that ORDS knows where to connect to.

Determine the IP of the Database Container

For ORDS to connect to the database, we’ll need to get the IP address of the container database. This is the IP address that containers use to talk to each other, not what we use to connect to it from our local machine.

  1. Open up a new local terminal

  2. Enter the following command:
    podman inspect oracle | grep IPAddress

  3. Note the value of IPAddress, as that will be needed in the next step.

Create the Directories & Files

Next, we need to create a pair of directories and a file on our local machine. This file will be used to seed ORDS with the connect information so that it can connect to the container database.

  1. Open up a new local terminal

  2. Change directories to where you want to store the connect information for your container database. This should be somewhere relatively permanent on your local machine, as you will need to refer to this configuration data to restart the ORDS container from time to time.

  3. Run the following commands:
    mkdir ords_secrets ords_config
    chmod 777 ords_config

  4. Next, run the following command, replacing [database container IP] with the IP address of the database container from the previous section :
    echo 'CONN_STRING=sys/oracle@[database container IP]:1521/freepdb1' > ords_secrets/conn_string.txt

This file will be deleted once the ORDS container is started, so there is little risk for the password being discovered.

💡
NOTE: If something goes wrong here and you had to re-created a new container database, be sure to remove all files from /ords_config. The files there will point to your old database IP, causing issues when trying to launch the ORDS container.

Install and Run ORDS Container

Now that everything is in place, let’s start the ORDS container. From the same terminal where you just ran the last commands, enter and run the following command:

podman run --rm --name ords -v `pwd`/ords_secrets/:/opt/oracle/variables -v `pwd`/ords_config/:/etc/ords/config/ -p 8181:8181 container-registry.oracle.com/database/ords-developer:latest &

This will run for about a minute. Once the screen looks similar to this, it should be ready to test:

Looking at the Containers tab in Podman, we can see that our ords container is up and running:

Connecting to APEX

If all went well, we should be able to connect to the Oracle REST Data Services landing page.

  1. Open up a new browser

  2. Navigate to the following URL: http://localhost:8181

You should see the following page:

  1. Click on the “Go” button under the Oracle APEX region.

  2. Enter internal for Workspace, admin for Username and the password that you set in the previous section via the @apxchpwd script for Password and click Sign In.

Congratulations! You can now start to create workspaces and do anything else that’s possible with Oracle APEX.

Also - it’s OK to close the terminal that started the ORDS container at this point. The ORDS container will continue to run until it’s terminated manually.

Summary

Building a local instance offers many benefits to both casual and professional developers. It provides a place to learn new things, test existing ones and even build real software. With complete control and no cost, developers can spin these up and down all day long, and owe nothing to anyone.

Mac users have especially been waiting a while for a near-native Oracle Database, and with this new container and Podman, the wait is finally over.

References

I referred to a few different sites for guidance when writing up this blog. They are:

OracleorclapexpodmancontainersAIOracle 23aiords