Search for a command to run...
Running Oracle Database 23ai & ORDS Locally via Containers
"Bumpy roads lead to beautiful places"
I discovered the silent install script for APEX just the other day...it's been there for years! Why is it not talked about in any blog?
apxsilentins.sql
Very helpful blog article, thank you! There is only one small typo in the line sql sys/oracle@localhost:1521/freepdb as sysdba. It must be freepdb1. :) But the rest worked flawless, thanks :)
Doh! Thanks for pointing that out, it's been fixed.
Glad that you found it helpful!
I'm using the Pod Manager extension in VS Code, very nice to have it all in one tool...
./setPassword oracle should be ./setPassword.sh oracle
This series will walk through the steps in order to install a local development environment that includes Oracle 23ai, ORDS & APEX.
💡 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....
I saw Dimitri's post on SQL Assertions today and it piqued my curiosity. Putting more business rules closer to data is almost always a great idea, as you can now call DML from any technology and rest
Almost 20 years ago to the date, I submitted my resignation to Oracle to go start my own company. It was a difficult decision to make, as APEX - or HTML DB as it was called then - was just starting to gain traction. However, I was presented with an o...
One of the more difficult parts of the software development lifecycle is deployment. While it seems simple on the surface - just write some scripts and run them - it gets pretty complicated pretty quickly as the level of sophistication of your system...
Another AI-centric tool that has raised a lot of interest is Claude Desktop. Like Cline, Claude Desktop uses the same reasoning engine at the core - Claude Code - to assist with development tasks. While they share the same engine, there are use cases...
When I first heard the term MCP used in the context of AI, I was immediately taken back to the 80s when the movie Tron was released. For those who have not seen it, Tron is a futuristic movie about a curious user who is literally sucked into a comput...
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.
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.
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.
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.
Navigate to https://podman.io/
Click Download
Select Podman Desktop for your OS
Once downloaded, install and start up Podman. You should see a screen that looks like this:
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.
Open Podman Desktop
Click the Containers icon
Click Create
Click Existing Image
Click Pull
Enter the following for Image to Pull:
container-registry.oracle.com/database/free:latest
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.
Now that we have the container downloaded, let’s start it up.
Open a new terminal window
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.
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
Log out of SQL*Plus, if you’re still logged in
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.
sql sys@localhost:1521/freepdb1 as sysdba
To install APEX manually, follow these steps.
Download APEX from https://www.oracle.com/tools/downloads/apex-downloads/
Unzip the downloaded file to your local machine.
Open up a new terminal and change directories to the /apex directory.
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.
create tablespace apex datafile 'apex_001.dbf' size 300m autoextend on;Now that we have our tablespace created, we’re ready to install APEX.
@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.
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.
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.
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.
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.
Open up a new local terminal
Enter the following command:
podman inspect oracle | grep IPAddress
Note the value of IPAddress, as that will be needed in the next step.
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.
Open up a new local terminal
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.
Run the following commands:
mkdir ords_secrets ords_config
chmod 777 ords_config
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.
/ords_config. The files there will point to your old database IP, causing issues when trying to launch the 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:
If all went well, we should be able to connect to the Oracle REST Data Services landing page.
Open up a new browser
Navigate to the following URL: http://localhost:8181
You should see the following page:
Click on the “Go” button under the Oracle APEX region.
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.
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.
I referred to a few different sites for guidance when writing up this blog. They are:
Oracle Database 23ai Free Edition Container
https://container-registry.oracle.com/ords/ocr/ba/database/free
Oracle RESTful Data Services Developer Container
https://container-registry.oracle.com/ords/ocr/ba/database/ords-developer
Launch your ORACLE APEX Instance in a Docker Container
https://medium.com/@hamzaeraoui2000/lunch-your-oracle-apex-in-a-docker-container-22a16e27a6b3
Title Photo by OSG Containers on Unsplash