Mar 25, 2020

8 min read

Building and running Oracle Database 19.3.0 EE Docker Containers

This article is based on an older post written by Gerard Venzl, maintainer of the Oracle Database Docker build files. Original post dates from Nov 2017 and can be found here. Also the the documentation provided on Github is a good reference.

I decided to replace one of my Oracle MySQL DB Docker instances with Oracle Database Enterprise Edition. This post will explain what I did and some things I encountered during the process.

Environment

The software needs to run on my server which has a Docker environment available.

My environment is as follows:

Oracle Linux 7.7 (4.14.35–1902.6.6.el7uek.x86_64)
Docker 19.03.5 (docker-ce-19.03.5–3.el7.x86_64)
Git 1.8.3.1 (1.8.3.1–21.el7_7.x86_64)

The Oracle Database I want to containerize:

Oracle Database 19.3.0 Enterprise Edition

Disk Space Requirements

It is important to make sure that you have enough disk space for the build. In my case the build failed because I didn’t have the required space available. I needed to do some housekeeping and delete unused volumes, images and containers on my Docker host.

The needed space at time of writing for Oracle Database 19.3.0 Enterprise Edition was 18GB, but I made sure I had 50GB of free space available, as even with 19GB I ran out of space.

Getting the required files and binaries

To be able to build the Oracle Database Docker images, you first need to clone the Docker build files from Github. Secondly, you need to download the DB binary files for the version of your choice.

Cloning the Git repo

The Docker build files are located at https://github.com/oracle/docker-images/ and after you browse to this location you will see the following:

Oracle Github repo for Docker build files

As you can see, apart from the Oracle Database, you can also find Docker build files for other Oracle products. We will clone the full repo by clicking on the green button in the top right corner (Clone or download):

Click on the “copy icon” next to the URL. Next we have to decide on a location for the cloned files. Again a disk space recommendation. In my case I have two volumes on my server:

root volume (/) including the docker runtime environment
home volume (/home)

On the first volume I freed up 50GB, but since we need to download and store the binary files for the Oracle DB as well, roughly 2.5GB, I decided to create a source folder in “/home/Oracle Docker Image Sources” to prevent storing more data on the root volume.

Now cd into this directory and run:

git clone https://github.com/oracle/docker-images.git

You will see some output like this:

Cloning into 'docker-images'...
remote: Enumerating objects: 11757, done.
remote: Total 11757 (delta 0), reused 0 (delta 0), pack-reused 11757
Receiving objects: 100% (11757/11757), 9.33 MiB | 4.27 MiB/s, done.
Resolving deltas: 100% (6923/6923), done.

And you will have a full copy of the Github repo on your local disk.

Downloading the binary files

In order to build the Docker image you need to download the binary files for the Oracle Database version of your choice. They can be obtained from Oracle Technology Network. NOTE: You will need an Oracle OTN account to be able to download the binary files. If you click the link you will be brought here:

Since I want to containerize 19.3 I need to download the Linux x86–64 binaries ZIP file. Important: it must be the ZIP file, not an other format. You can do two things:

Download the file manually through your browser and copy the file to where you need it
Obtain the download link from our browser, after the download started (this will include the authentication header) and use wget to download the binaries directly onto the server where we will build the image:

I did this in the Safari browser, I opened the downloads list through the button with the downward arrow icon and right-clicked on the file, this will give you a new menu with the “copy address” option. If you do this you can run a simple

wget [paste address link you just copied]

After sucesfull download the binary file (in ZIP format — do not uncompress) needs to be placed in the proper subdirectory of the Docker build files. In my case it needed to be moved into:

/home/Oracle Docker Images Sources/docker-images/OracleDatabase/SingleInstance/dockerfiles/19.3.0

Ok, we have all the files we need. Let’s start the build.

Building the image

The Docker build files include a nice helper script to support the build. If you are an advanced user, you can directly run your own docker build command.

The helper script is called “buildDockerImage.sh” and can be found in:

/home/Oracle Docker Images Sources/docker-images/OracleDatabase/SingleInstance/dockerfiles/

If you run the command with the -h flag

./buildDockerImage.sh -h

it will print out the usage instructions

Usage: buildDockerImage.sh -v [version] [-e | -s | -x] [-i] [-o] [Docker build option]
Builds a Docker Image for Oracle Database.Parameters:
   -v: version to build
       Choose one of: 11.2.0.2  12.1.0.2  12.2.0.1  18.3.0  18.4.0  19.3.0
   -e: creates image based on 'Enterprise Edition'
   -s: creates image based on 'Standard Edition 2'
   -x: creates image based on 'Express Edition'
   -i: ignores the MD5 checksums
   -o: passes on Docker build option* select one edition only: -e, -s, or -xLICENSE UPL 1.0Copyright (c) 2014-2019 Oracle and/or its affiliates. All rights reserved.

I used the following simple command to build the image (version 19.3.0 and Enterprise Edition)

./buildDockerImage.sh -v 19.3.0 -e

If all goes well the build should complete succesfully. You can check if you have the image available with

docker images

and you should see something like this

a freshly created image!

Operating the container

Ok you have made it this far. Good. But the purpose was not to build an image, but actually create a running container from the image that we can use. We want to run/create, stop and (re)start the container.

Running

The first step is creating the container and in the process it will run the container as well. We will use the “docker run” command for this step.

The documentation in from the repo is pretty good. The following is coming directly from the documentation:

docker run --name <container name> \
-p <host port>:1521 -p <host port>:5500 \
-e ORACLE_SID=<your SID> \
-e ORACLE_PDB=<your PDB name> \
-e ORACLE_PWD=<your database passwords> \
-e ORACLE_CHARACTERSET=<your character set> \
-v [<host mount point>:]/opt/oracle/oradata \
oracle/database:19.3.0-ee

Parameters:
   --name:        The name of the container (default: auto generated)
   -p:            The port mapping of the host port to the container port. 
                  Two ports are exposed: 1521 (Oracle Listener), 5500 (OEM Express)
   -e ORACLE_SID: The Oracle Database SID that should be used (default: ORCLCDB)
   -e ORACLE_PDB: The Oracle Database PDB name that should be used (default: ORCLPDB1)
   -e ORACLE_PWD: The Oracle Database SYS, SYSTEM and PDB_ADMIN password (default: auto generated)
   -e ORACLE_CHARACTERSET:
                  The character set to use when creating the database (default: AL32UTF8)
   -v /opt/oracle/oradata
                  The data volume to use for the database.
                  Has to be writable by the Unix "oracle" (uid: 54321) user inside the container!
                  If omitted the database will not be persisted over container recreation.
   -v /opt/oracle/scripts/startup | /docker-entrypoint-initdb.d/startup
                  Optional: A volume with custom scripts to be run after database startup.
                  For further details see the "Running scripts after setup and on startup" section below.
   -v /opt/oracle/scripts/setup | /docker-entrypoint-initdb.d/setup
                  Optional: A volume with custom scripts to be run after database setup.
                  For further details see the "Running scripts after setup and on startup" section below.

I decided to run it with default settings as much as possible, but if you want you can change parameters.

docker run --name oracledb19 -p 1521:1521 -p 5500:5500 \
-v oradata:/opt/oracle/oradata \
oracle/database:19.3.0-ee

With this command I gave the container a name (oracledb19), I mapped ports on the Docker server to the container exposed ports (1521 and 5500), I created a persistent volume for data that needs to be saved between container/hosts restarts and lastly I point to the freshly created image (oracle/database:19.3.0-ee) to be used for the creation of the container.

The first time the container starts, there will be a lot initialisation, so it takes some time to have the container operational.

As I used the default settings, a password is automatically generated. Look for the following on the console output to know what is the initial password:

ORACLE PASSWORD FOR SYS, SYSTEM AND PDBADMIN: 3y4RL1K7org=1password

Of course you should change it and luckily the container provides a nice tool to do this. However, you need to run the command inside the container. You can use the docker “exec” switch to accomplish just this:

docker exec oracledb19 ./setPassword.sh ChangedPassword

Stopping

Again the original post from Gerard provides some useful insights. If you are familiar with Docker you would probably run

docker stop oracledb19

like me. Yes, that is the normal way to stop a container. However, if you have a large database, it could actually take some time to stop the database itself gracefully. So if the container stops before this process has finished, we could have some issues. You can tell Docker to wait some time before killing the container. Use the -t switch and the number of seconds Docker should wait. Let us chose 30 seconds:

docker stop -t 30 oracledb19

Restart

If you have stopped the container and not have deleted it, it takes as simple

docker start oracledb19

to bring it up again. You can do a

docker container ls

to check the startup status. You will see an “UP” status when the container is ready to be used.

Connecting to the container

Now that the container is up and running you connect through the various standard ways of connecting, for example by using sqlplus or Oracle SQL Developer. You will be using port 1521 that we exposed to the outside world and the other default values like Database SID (ORCLCDB).

In a webbrowser you can go to https://yourhost:5500. Note: make sure to use HTTPS. This will give you access to Oracle Enterprise Manager DB Express, which is included in the container: