Database & Cloud Technology Blog

Database & Cloud Technology Blog Follow: 

Database Management, Development, English Content, JSON, Spatial & Graph

Oracle Database Development with Docker

February 13, 2023 | 14 minute read

Witold Swierzy
Data Management Expert

Table of contents
Introduction

Docker Software Installation

Container Coniguration

Docker Image Creation

Summary

Introduction
Almost everyone has heard the opinion, that Oracle Database is the excellent example of an old, traditional, pure-relational,
old-fashioned etc, etc, etc... monolithic databaase, which, additionally to that, is also very expensive. Yup. We've heard it too.
But the fact is that it is completely false. In this article we will prove, that it is possible and easy to build a system, which
meets all the modern development approaches, can be provisioned in a minute, has everything needed to start developing
an application, which uses all possible data models and - is completely for free! To do this we will use the following
components

Oracle Database 21c XE

Oracle REST Data Services 22.4.3

Oracle Application Express 22.2

Below picture is also very well known, I think, to most of Oracle Database users and administrators: it describes one of
obvious use cases of Oracle Database multitenant option: support for containerized applications

But in this article we will describe a dicerent scenario: instead of providing support for external containers, we will build a
container which will provide all the typical Oracle Converged Database services: SODA, PGQL, REST, MongoDB API and
APEX. If you want to learn more about Oracle's converged database features, you can get an overview in the posting Oracle
Database Development #blockchain #graph #JSON #lowcode #spatial #SQL #textsearch #XML.

So - let's start doing this!

Docker Software Installation

At the irst stage we need to install docker. Below procedure describes its installation on Oracle Linux 8 and may be
dicerent on other operating systems. We assume in this post, that the host machine is already up and works under control
of this operating system. Oracle Linux 8, by the way, can be downloaded from here.

All the below commands need to be executed as root on our host machine:

Copy code snippet

# We will start from installing required packages...

dnf install -y dnf-utils zip unzip java-17-openjdk
# ...after that we will add Docker official repo to our host OS...
dnf config-manager --add-repo=[Link]
# ...runc needs to be uninstalled, as it is in conflict with Docker software...
dnf remove -y runc
# ...now we can install Docker...
dnf install -y docker-ce
# ...create directory for Docker images and containers...
mkdir /var/lib/docker
# ...and start the Docker engine as a system service
systemctl enable --now [Link]
# ...finally we need to create an OS account, belonging to "docker" group...
# ...we will use this account to work with containers and images...
# ...in case, when an OCI instance is used, it is enough to add "opc" user to this group
useradd -m -d /home/docker -g docker docker

Now we need to reconigure the system irewall

Copy code snippet

# We need to enable masquerading to provide network services to containers...

firewall-cmd –-permanent --zone=public --add-masquerade
# ...open well-known ports used by Oracle software...
firewall-cmd --permanent --add-port=1521/tcp
firewall-cmd --permanent --add-port=5500/tcp
firewall-cmd --permanent --add-port=8080/tcp
firewall-cmd --permanent --add-port=8443/tcp
# ...and remember about MongoDB port - it will be used by MongoDB API, which we plan to enable
firewall-cmd --permanent --add-port=27017/tcp

Container Con5guration
As we have Docker installed and conigured, so we can start to work on the second stage of our project - development of an
Oracle Database Express Edition Docker image. We will start from creating a "golden image" - Docker Oracle Linux 8
container where everything will happen... (now we don't need to work as root - instead of this we will use the account
created/modiied in the last step of Docker installation stage)

Copy code snippet

# As we need to install a couple of packages, like Oracle preinstall check, Oracle RDBMS, ords,...
# ...instead of uploading everything into the container, it is better to create it with a folder shared with the host...
# ...we also need to remember about port mapping...
# ...and providing some environment variables into the container, which we will use during software configuration
mkdir $HOME/orainstall
docker create -it --name oracle21xe -p 1521:1521 -p 5500:5500 -p 8080:8080 -p 8443:8443 -p 27017:27017 \
-e DBA_PWD=ConvergedDB_1234 -e USR_PWD=ConvergedDB_1234 \
-e DOCKER_HOST=NOHOSTNAME \
-v $HOME/orainstall:/orainstall oraclelinux:8

where

DBA_PWD is the environment variable, which will provide to the container DBA password - in the above example we have
set it to "ConvergedDB_1234", and - of course - it can be customized later
USR_PWD is the environment variable, which will provide to the container end user password - in the above example also
set to "ConvergedDB_1234"

DOCKER_HOST is the environment variable, which is required only if you want to activate SSL for ORDS. In that case it
needs to be set to the real "[Link]" or IP address of the host machine. In the above example, as we'll see later,
"NOHOSTNAME" value causes, that ORDS will work only in non-SSL mode.

To complete next steps we need to download and store in $HOME/orainstall the following software

Oracle Database 21c Express Edition for Oracle Linux 8

Oracle REST Data Services 22.4.3

Oracle Application Express 22.2

Now we can start to conigure the container. Let's connect to it:

Copy code snippet

# let's create a root session inside of the container

docker start oracle21xe
docker exec -it oracle21xe /bin/bash

Now let's install few standard linux packages, which will be used in our coniguration

Copy code snippet

# inside of the container...

dnf install -y sudo hostname zip unzip which java-17-openjdk

As you see, for the purpose of this post we are using OpenJDK instead of OracleJDK... In case of any license-related
questions please refer to OracleJDK Licensing FAQs page or contact your sales representative.

Now we can install the software, which we have downloaded into orainstall folder: Oracle Database 21c Preinstall Check,
Oracle Database 21c XE, ORDS and Apex. The procedure is exactly the same as in case of installing it on a physical machine,
so I will not describe in this article how to do this. The only dicerence is that in case of installing Oracle Database software in
a Docker container we need to set ORACLE_DOCKER_INSTALL environment variable to true:

Copy code snippet

#...still inside of the container...

export ORACLE_DOCKER_INSTALL=true
#...typical Oracle rpms (preinstall check and database xe21c) installation and database configuration takes place here...
#PLEASE NOTE, that we assume in this post, that during execution of "oracle-xe-21c configure" the DBA password will be set to "ConvergedDB

The next step is technically optional. We can (but it is not a technical requirement) add oracle user to sudoers ile to allow it
to make sudo to root. But if we want to make our "Golden Oracle Database Image" customizable - we should do it - it would
be possible to make sudo to root and extend functionality of this installation.

Copy code snippet

#...and still inside of the container...

vi /etc/sudoers
root ALL=(ALL) ALL
oracle ALL=(ALL) ALL # this is the line we want to add to /etc/sudoers file

After that let's make our life a liqle bit easier, by adding some environment variables to oracle's .bashrc ile and seqing a
password for this account

Copy code snippet

# ...still and still inside of the container...

vi /home/oracle/.bashrc
# User specific aliases and functions
export ORACLE_NET_HOME=/opt/oracle/homes/OraDBHome21cXE/network/admin
export ORACLE_CFG_SCRIPTS=/opt/oracle/scripts
export ORACLE_HOME=/opt/oracle/product/21c/dbhomeXE
export ORACLE_SID=XE
export ORDS_HOME=/opt/oracle/ords
export ORDS_CONFIG=$HOME/ordsconfig
export PATH=$ORACLE_CFG_SCRIPTS:$ORACLE_HOME/bin:$ORDS_HOME/bin:$PATH
# ...now let's setup the password for oracle to ARandomOne_1234. It will be changed automatically to $DBA_PWD value
# during the first start of the container with all the software installed
passwd oracle

Now we can "install" ORDS and APEX - I mean - simply unzip iles into appropriate directories...

Copy code snippet

# ...let's become "oracle" user inside of the container we're working on...
su - oracle
# ...being already "oracle" - create a directory for ORDS configuration...
mkdir $HOME/ordsconfig
# ...and another directory, where we'll place all the scripts required to automate the startup and configuration process...
mkdir /opt/oracle/scripts
# ...and "install" ords and apex - which means simply unzipping appropriate files into appropriate directories.
unzip /orainstall/[Link] -d /opt/oracle/ords
unzip /orainstall/apex_22.[Link] -d /opt/oracle/product/21c/dbhomeXE

The next step is to conigure APEX and ORDS - exactly in the same way as in case of a traditional installation on a physical
machine. As these processes are well documented in many manuals, blog posts and even some Youtube videos, I will not
describe them here, just want to add the note, that even in case when we plan to run an SSL-based coniguration, at the
stage of initial coniguration of ORDS we'll conigure only h7p mode and port 8080... Why? Of course, if we have an SSL
certiicate, then we can conigure ORDS to use hqps from its irst run, but we assume in this post, that our container is not
being built for a production purposes, (which usually means, that we have company certiicates, public domains, etc...) but
rather for a demonstration. In that case ORDS started with --secure parameter will generate its own, self-signed certiicate,
which is good enough for doing some demos, even if it causes, that a web browser generates a warning...

After coniguring ORDS we may want to (as it is not being done in ords installation automatically)

Create an additional database user, which will play the role of a "developer" and grant to this account privileges allowing
for development a database application.
Conigure a Database Actions user. It is described, for example here.

Enable MongoDB API. It is described, for example here.

Create sample database schemas. It is also well described in multiple places.

The last step is speciic to our confguration and - the most important - we need to automate the initial coniguration and
startup of OracleNet, database and ords... Of course - there are many ways of how to do this, but there's always need to
remember about one fundamental dicerence between a docker-based installation and installation on a physical or even
virtual, but "traditionally virtualized" machine: Docker Oracle Linux 8 image doesn't use systemd, since then
typical oratab-based methods are in such cases not applicable. In this article we'll use an ancient and (almost, fortunately
not quite) forgoqen art of shell scripting ;).

Below diagram presents scripts which we want to develop. All of them will be stored in /opt/oracle/scripts directory and
owned by "oracle" user:

Copy code snippet

[Link] (main script, which will be used in EntryPoint attribute of the Docker image we're working on)
|
|---- [Link] (executed only once, during container first start, it configures [Link] and [Link] files
|
|---- [Link] (executed every time when container starts. It starts listener and the database)
| |
| |
| ---- [Link] (starts the database)
|
|---- [Link] (executed only once, during container first start, it configures passwords for database users
| and oracle OS user
| |
| |
| ---- [Link] (called by [Link], it changes passwords directly in the database)
|
|
---- [Link] (executed every time container starts - it starts ords)

So - at the beginning let's automatize the OracleNet iles coniguration. We need to do this, as their content ([Link] and
[Link]) depends on a hostname of the CONTAINER. And this hostname may be setup automatically during a
container creation...

Copy code snippet

# ...being still "oracle" user inside of the container...

# ...let's copy [Link] and [Link] to .sample files....
cp $ORACLE_NET_HOME/[Link] $ORACLE_NET_HOME/[Link]
cp $ORACLE_NET_HOME/[Link] $ORACLE_NET_HOME/[Link]
# ...and change all occurences of the container hostname to %HOSTNAME% tag in these .sample files...
# ...and now we can start to work on the first of the serie of scripts we need to develop...
--- content of [Link] ---
#!/bin/bash
if [ ! -f ${ORACLE_CFG_SCRIPTS}/system_already_configured ];
then
export HOSTNAME=`hostname`
printf "Configuring new container %s.\n" $HOSTNAME
cp $ORACLE_NET_HOME/[Link] $ORACLE_NET_HOME/[Link]
cp $ORACLE_NET_HOME/[Link] $ORACLE_NET_HOME/[Link]
sed -i 's/%HOSTNAME%/'$HOSTNAME'/g' $ORACLE_NET_HOME/[Link]
sed -i 's/%HOSTNAME%/'$HOSTNAME'/g' $ORACLE_NET_HOME/[Link]
printf "Container %s configured.\n" $HOSTNAME
fi
--- end of [Link] ---

The next two scripts will change database passwords to $DBA_PWD and $USR_PWD: [Link] and
[Link]

Copy code snippet

--- [Link] content ---

alter user sys identified by &1;
alter user system identified by &1;
alter session set container=xepdb1;
alter user pdbadmin identified by &1;
alter user hr identified by &2;
alter user oe identified by &2;
alter user pm identified by &2;
alter user ix identified by &2;
alter user sh identified by &2;
alter user bi identified by &2;
exit
--- end of [Link] content ---

--- [Link] ---

#!/bin/bash
# it changes oracle user password to the value provided by DBA_PWD environment variable...
echo -e "ARandomOne_1234\n${1}\n${1}"|passwd
# ...and executes [Link] with values provided by DBA_PWD and USR_PWD environment variables.
sqlplus "/ as sysdba" @/opt/oracle/scripts/[Link] ${1} ${2}
--- end of [Link] ---

Two other scripts are responsible for starting the database up:

Copy code snippet

--- [Link] ---

startup
exit
--- end of [Link] ---

--- [Link] ---

#!/bin/bash
lsnrctl start
sqlplus "/ as sysdba" @${ORACLE_CFG_SCRIPTS}/[Link]
--- end of [Link] ---

Now the script, which starts ORDS...

Copy code snippet

--- [Link] ---

#!/bin/bash

if [ "$DOCKER_HOST" = "NOHOSTNAME" ];
then
# if we have not changed DOCKER_HOST value to a non-default, then it means that we want to use only non-SSL configuration
nohup ords serve >> ${ORACLE_CFG_SCRIPTS}/[Link] 2>&1 &
else
# we have provided a non-default value for DOCKER_HOST, then it means, that we want to use SSL-based configuration
# in that case ords will generate its own self-signed certificate during the first startup
nohup ords serve --secure --port 8443 >> ${ORACLE_CFG_SCRIPTS}/[Link] 2>&1 &
fi
--- end of [Link] ---

 Now it's time to inalize our small project. The main script - [Link]

Copy code snippet


 --- [Link] ---


Copy code snippet

#!/bin/bash

# as we will use this script as the container entrypoint, it will not execute $HOME/.bashrc...
# ...so we need to setup the environment.
export ORACLE_NET_HOME=/opt/oracle/homes/OraDBHome21cXE/network/admin
export ORACLE_CFG_SCRIPTS=/opt/oracle/scripts
export ORACLE_HOME=/opt/oracle/product/21c/dbhomeXE
export ORACLE_SID=XE
export ORDS_HOME=/opt/oracle/ords
export ORDS_CONFIG=$HOME/ordsconfig
export PATH=$ORACLE_CFG_SCRIPTS:$ORACLE_HOME/bin:$ORDS_HOME/bin:$PATH

if [ ! -f ${ORACLE_CFG_SCRIPTS}/system_already_configured ];
then
printf "Starting OracleNet configuration\n" >> ${ORACLE_CFG_SCRIPTS}/[Link] 2>&1
${ORACLE_CFG_SCRIPTS}/[Link] >> ${ORACLE_CFG_SCRIPTS}/[Link] 2>&1
printf "OracleNet configuration completed\n" >> ${ORACLE_CFG_SCRIPTS}/[Link] 2>&1
if [ "$DOCKER_HOST" != "NOHOSTNAME" ];
then
printf "ORDS SSL reconfiguration.\n"
# we need to remove an old self-signed certificate if it exists. Otherwise ords will not generate a new one
rm -f ${ORDS_CONFIG}//global/standalone/self-signed.*
# we need to configure [Link] property in order to make SSL-based configuration working
ords config set [Link] ${DOCKER_HOST} >> ${ORACLE_CFG_SCRIPTS}/[Link] 2>&1
printf "ORDS SSL reconfiguration completed.\n"
fi
fi

# if the database instance is not up, there's need to start it up with apex
if [ `ps -ef|grep lgwr|wc -l` -lt 2 ];
then
${ORACLE_CFG_SCRIPTS}/[Link] >> ${ORACLE_CFG_SCRIPTS}/[Link] 2>&1
${ORACLE_CFG_SCRIPTS}/[Link] >> ${ORACLE_CFG_SCRIPTS}/[Link] 2>&1
fi

# if we start the container for the first time, there is need to change default passwords
if [ ! -f ${ORACLE_CFG_SCRIPTS}/system_already_configured ];
then
printf "Starting password configuration\n" >> ${ORACLE_CFG_SCRIPTS}/[Link] 2>&1
${ORACLE_CFG_SCRIPTS}/[Link] ${DBA_PWD} ${USR_PWD} >> ${ORACLE_CFG_SCRIPTS}/[Link] 2>&1
printf "Password configuration completed\n" >> ${ORACLE_CFG_SCRIPTS}/[Link] 2>&1
touch ${ORACLE_CFG_SCRIPTS}/system_already_configured >> ${ORACLE_CFG_SCRIPTS}/[Link] 2>&1
printf "New system configuration completed\n" >> ${ORACLE_CFG_SCRIPTS}/[Link] 2>&1
fi

tail -f /opt/oracle/scripts/[Link]

--- end of [Link] ----

Of course, we have to remember about adding execution privilege to all *.sh scripts we have created:

Copy code snippet

#...being still oracle inside of the container...

chmod 755 ${ORACLE_CFG_SCRIPTS}/*.sh

And that's all - our work on "golden image container" is done!

Docker Image Creation

Finally the job inside of the container is done. What we need to do now is to create a Docker image, test if it works (by
istantiating another image) and - if we want to do this - publish it to a registry. Since then the next steps will be executed on
the host machine.

First we need to create an image from the container we've prepared:

Copy code snippet

# ...inside of the host machine...

# ...let's stop the container we were working on...
docker stop oracle21xe
# ... create a "golden image" from this container ...
docker commit -a "Author's data" --change='ENTRYPOINT ["/opt/oracle/scripts/[Link]"]' \
--change='USER "oracle"' --change='ENV DOCKER_HOST=NOHOSTNAME' \
oracle21xe oracle21xegoldenimage

Now we can create a test container to check how our setup works

Copy code snippet

# ...still in a host machine as a docker user...

docker create -it --name test \
-p 1521:1521 -p 5500:5500 -p 8080:8080 -p 8443:8443 -p 27017:27017 \
-e DOCKER_HOST="<host>.<domain>|<host_ip_address>" \
oracle21xegoldenimage
# ...and finally - start the test container...
docker start test

We can test services provided by the container in the following way:

database, by using, for example SQLcl: sql user/password@<docker_host_machine>:1521/xepdb1

Application Express
in case, when SSL is conigured: hqps://<docker_host_machine>:8443/ords

in case, when SSL is not conigured: hqp://<docker_host_machine>:8080/ords

Database Actions
In case, when SSL is conigured: hqps://<docker_host_machine>:8443/ords/sql-developer

In case, when SSL is not conigured: hqp://<docker_host_machine>:8080/ords/sql-developer

Of course, as oracle user is in /etc/sudoers ile, we can use root account of the container to install additional packages or, in
general, perform further customizations. In general - we have full control over the image we've created, which, in case of a
test installation is rather an advantage (however - in case, when we want to use such image for a produciton purpose, such
coniguration may drive to some security threads).

Summary
To summarize all the steps we have completed:

We have created a Docker image, providing all the services, which are required in a modern development environment,
using Oracle Database as its foundation.
This image can be used to provision and start a new environment in a minute.

And inally - it is completely for free!

Such Oracle Database Golden Image can be easily used in dicerent CI/CD scenarios, it meets requirements of any modern
development environment or DevOps/SysOps approaches. Also Oracle 21c Express Edition has many features coming
directly from Enterprise Edition, like, for example, Partitioning or In-Memory options. It also supports multi- and cross-
model approach of Converged Database. Of course it has also some limitations, but it is an obvious result of its price - its
for free :). So - please, don't believe in rumours and fake opinions and instead of this...

Have a fun with Oracle Converged Database and Docker Containers :)

Important resources

Oracle Database 21c Express Edition Main Page

Oracle Database licensing information

Oracle Database Express Edition Download Page

Note

This Article has been updated to use the newest version of the Oracle Database software:
Oracle Databas 23c Free Developer Edition. Updated version can be found here

Witold Swierzy
Data Management Expert

Witold studied mathematics. He works at Oracle in Warsaw as a EMEA Data Management Expert.
His main responsibilities cover providing to our customers knowledge related to the newest options
Show more
and features of Oracle Database. He is also lecturer, working at Warsaw School of Economics, where
he gives lectures related to modern IT technologies.

 Previous Post Next Post 

Using transparent application continuity with Oracle Datenbanken - Monthly News - Februar
current Java frameworks - this is how it works 2023 Ausgabe
Marcel Boermann-Pfeifer | 15 min read Ulrike Schwinn | 2 min read

Resources for Why Oracle Learn What's New Contact Us

About Analyst Reports What is Customer Service? Try Oracle Cloud Free Tier US Sales 1.800.633.0738
Careers Best CRM What is ERP? Oracle Sustainability How can we help?
Developers Cloud Economics What is Marketing Automation? Oracle COVID-19 Response Subscribe to Oracle Content
Investors Corporate Responsibility What is Procurement? Oracle and SailGP Try Oracle Cloud Free Tier
Partners Diversity and Inclusion What is Talent Management? Oracle and Premier League Events
Startups Security Practices What is VM? Oracle and Red Bull Racing News
Honda

© 2024 Oracle Privacy / Do Not Sell My Info Cookie Preferences Ad Choices Careers