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.
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 188.8.131.52 (184.108.40.206–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:
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
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: 220.127.116.11 18.104.22.168 22.214.171.124 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
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.
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 \
--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)
The character set to use when creating the database (default: AL32UTF8)
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 \
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
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
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:
After logging in, use SYS and your password, you get the performance hub dashboard for your database
That’s it for this post, please leave some feedback if you want.