Deliver Oracle Database 18c Express Edition in Containers

Use Docker with Oracle Database to create a consistent database experience for development, testing, and more.

By Adrian Png

September 12, 2019

Deploying modern day software and having it run consistently on any platform can be a challenge. Whether it is a database or web application, administrators often must deal with issues such as preinstalling software dependencies and configuring the necessary parameters. Containerization helps developers address some of these issues.

A Docker container is a solid choice for wrapping software dependencies and configuration into a single deployable unit. Containers can be more compact and run more efficiently than virtual machines while providing the benefits of process isolation. Refer to this article for more information on the benefits of using Docker and when to use Docker.

In this article, I will demonstrate how to run Oracle Database Express Edition using Docker on an Oracle Cloud compute instance.

Installing Docker

Docker is available in two editions. The Community Edition (CE) is available at no cost and supports a wide variety of operating systems including Microsoft Windows, macOS, and Linux. If support and security are crucial to your business, consider using Docker Enterprise instead.

Install Docker for Windows. Docker Desktop is available for Windows. Note that it requires Microsoft Hyper-V and, unfortunately, this feature is available only on Windows 10 Professional, Enterprise, and Education editions. For Windows 10 Home and previous versions, download the legacy Docker Toolbox instead.

Run the downloaded executable and follow the installation guide to get Docker up and running.

Install Docker for macOS. Docker Desktop is also available for macOS. To get Docker up and running on macOS, run the installation package and follow the installation guide. Note the minimum supported OS version, and download the legacy Docker Toolbox for older versions.

Install Docker for Linux. Docker is supported on a number of mainstream Linux distributions. Use one of the following individual guides to install Docker on your distribution:

• CentOS
• Debian
• Fedora
• Ubuntu

Typically the process involves removing outdated components that might have been previously installed, updating the host’s software repository, and then installing Docker using the operating system’s package manager, such as yum or apt.

If you are using an unsupported Linux distribution, an alternative would be to obtain and install the daemon and client binary files for Docker. Doing that is a more involved process.

Fortunately for Oracle Linux users, the Docker binaries are readily available from the official Oracle yum repository through the Add-ons channel. If Docker has not already been installed on your installation of Oracle Linux 7, first install and enable the Add-ons channel by using one of the following two-step procedures as root:

1. Install the yum configuration manager:

   $ yum install -y yum-utils
   

2. Enable the Add-ons channel:

   $ yum-config-manager –enable ol7_addons
   

Or

1. Edit the /etc/yum.repos.d/public-yum-ol7.repo file using your favorite editor.
2. Search for the [ol7_addons] section and confirm its value is enabled=1. If it is not, set it to that value.

Once the Add-ons channel has been enabled, install Docker using the following steps:

1. Install docker-engine using the yum package manager:

   $ yum install -y docker-engine
   

2. Start the Docker daemon:

   $ systemctl start docker
   

3. Optionally, enable the Docker daemon to ensure that it starts when the system boots up:

   $ systemctl enable docker
   

4. To allow nonroot users to manage Docker (for example, the opc user, which is the administrative user commonly created in Oracle Cloud compute instances), add them to the docker UNIX group:

   $ usermod -aG docker opc
   

5. Log in again to ensure the changes made to the account take effect.

Vagrant Boxes Vagrant is a DevOps tool that helps users quickly provision virtual machines for a variety of virtualization software, such as Oracle VM VirtualBox. Oracle also publishes an Oracle Linux 7 Vagrant box, along with a repository of configuration files and scripts that can be used to quickly create, for example, a virtual machine running Docker. These files are available on GitHub.

Potential Issues with SELinux Enforced

Security-Enhanced Linux (SELinux) is a kernel enhancement to secure the Linux operating system. Setting the SELinux value to enforcing can pose a challenge when you build and run Docker images. Often, the quick solution is to disable this feature. To do that, do the following as the root user.

Caution: Disabling security features is never a good choice. The following procedure should never be used in a production environment.

1. Edit the file /etc/sysconfig/selinux in your favorite editor:

   $ vi /etc/sysconfig/selinux
   

2. Set the SELINUX value to either permissive or disabled. The resulting file should contain the following if you set the value to permissive:

   $ cat /etc/sysconfig/selinux | grep SELINUX=
   # SELINUX= can take one of these three values:
   SELINUX=permissive
   

3. Reboot the server.

Running Oracle Database in Docker

Installing Oracle Database Express Edition on Oracle Linux can be as easy as “ABC”:

• A: Download the installer package.
• B: Install the package using the yum package manager.
• C: Configure the database.

More importantly, though, the entire installation procedure can be scripted and executed to need no user interaction. This allows for easy encapsulation of the database as a container image. Typically this involves a Dockerfile (see the Dockerfile reference for more information). Optionally it can involve build scripts that silently install and configure the software.

Lucky for us, Oracle took the big leap and made available a suite of Docker build scripts that help stand up many of its product offerings, including Oracle Database. These scripts are available on GitHub.

You can find the Docker images for a single instance of Oracle Database in the OracleDatabase/SingleInstance/dockerfiles subdirectory; the Dockerfile and supporting shell scripts for installing and configuring each release of the database are in the individual subdirectories. For Oracle Database Express Edition, the image is either 11.2.0.2 or 18.4.0, depending on the version of the database you want to run. This article focuses on the latter version.

Regardless of the database edition and version, you must first obtain a copy of the software binaries through Oracle’s technical resources web page. For Oracle Database Express Edition, the software binaries comprise a single RPM file. Git is also required.

To install Git, execute the following as the root user:

$ yum install -y git

Once the required database binary has been downloaded successfully, clone the project:

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

Copy the downloaded binary file to docker-images/OracleDatabase/SingleInstance/dockerfiles/18.4.0 and execute the build script:

$ cd docker-images/OracleDatabase/SingleInstance/dockerfiles

Specify the version and edition of the database to build:

$ ./buildDockerImage.sh -v 18.4.0 -x

The script installs the Oracle Database software, but it does not create and configure a database. When the build has been completed, it is tagged using the format oracle/database:<VERSION>-<EDITION>. You can verify this by listing the available Docker images on the host:

$ docker images
REPOSITORY              TAG           IMAGE ID          CREATED           SIZE
oracle/database         18.4.0-xe     6a5a6370de97      1 minute ago       8.57GB

Next, use Docker run to start an Oracle Database Express Edition container (see this reference for more information):

$ docker run --name myxedb \
    -d \
    -p 51521:1521 \
    -p 55500:5500 \
    -e ORACLE_PWD=mysecurepassword \
    -e ORACLE_CHARACTERSET=AL32UTF8 \
    oracle/database:18.4.0-xe

Let’s examine the different parameters for this run command:

• --name myxedb specifies the container name. If this option is not used, a random name is assigned by the Docker daemon.
• -d runs the container in detached (background) mode.
• -p 51521:1521 and -p 55500:5500 map a host to a container port.
• -e ORACLE_PWD=mysecurepassword and -e ORACLE_CHARACTERSET=AL32UTF8 set the environment variables. Here, ORACLE_PWD sets the administrative password, and ORACLE_CHARACTERSET sets the database’s character set.

Once the run command exits, check that the container is running by executing the docker ps command. Look for the “healthy” status.

$ docker ps
CONTAINER ID     IMAGE                       COMMAND                  CREATED           STATUS                    PORTS                                              NAMES
7298b3d299e4     oracle/database:18.4.0-xe   "/bin/sh -c 'exec $O…"   42 minutes ago    Up 42 minutes (healthy)   0.0.0.0:51521->1521/tcp, 0.0.0.0:55500->5500/tcp   myxedb

The Docker image has three mount points of interest, and you can map them to a corresponding directory on the host system:

• /opt/oracle/oradata is the data volume for the database and required database configuration files.
• /opt/oracle/scripts/setup is the directory containing either shell or SQL scripts that are executed once after the database setup (creation) has been completed.
• /opt/oracle/scripts/startup is the directory containing either shell or SQL scripts that are executed every time the container starts.

The data volume /opt/oracle/oradata lets you preserve the database’s data and configuration files on the host file system in case the container is deleted. The directory must be writable by a user with UID 54321, which is the oracle user within the container. There are two ways to ensure this:

With root access, change the ownership of the directory. For example, run the following command:

chown 54321:54321 /home/myuser/Docker/myxedb/oradata; 

Or make the directory writable by everyone by using chmod 777:

$ mkdir -p /home/myuser/Docker/myxedb/oradata
$ chmod 777 /home/myuser/Docker/myxedb/oradata
$ docker run --name myxedb \
    ...
    -v /home/myuser/Docker/myxedb/oradata:/opt/oracle/oradata \
    -v /home/myuser/Docker/myxedb/scripts/setup:/opt/oracle/scripts/setup \
    -v /home/myuser/Docker/myxedb/scripts/startup:/opt/oracle/scripts/startup \
    oracle/database:18.4.0-xe

Connecting to the Database

When the database is running in the Docker container, the database port is exposed using the -p parameter. Suppose, for example, SQL*Plus is installed on the Docker host system. To connect to the database, execute the following command:

$ sqlplus sys/mysecurepassword@//localhost:51521/XE

Or, to connect to a pluggable database, execute this:

$ sqlplus sys/mysecurepassword@//localhost:51521/XEPDB1

Alternatively, create a bash session within the container, using the OS user oracle.

$ docker exec -it --user=oracle myxedb bash

Set up the required Linux environment variables for Oracle Database:

[oracle@7298b3d299e4 /]$ . oraenv
ORACLE_SID = [XE] ? XE
The Oracle base remains unchanged with value /opt/oracle

Then access SQL*Plus as you would on any Oracle Database system:

[oracle@7298b3d299e4 /]$ sqlplus sys@XEPDB1 as sysdba

SQL*Plus: Release 18.0.0.0.0 - Production on Tue May 7 17:31:48 2019
Version 18.4.0.0.0

Copyright (c) 1982, 2018, Oracle.  All rights reserved.

Enter password:

Connected to:
Oracle Database 18c Express Edition Release 18.0.0.0.0 - Production
Version 18.4.0.0.0

SQL> sho con_name

CON_NAME
------------------------------
XEPDB1
SQL>

Container Names and Docker Networks

When Docker creates and runs containers, it generates random container names. The example Docker run commands shown earlier used the --name option to name the container myxedb. Note that the container name is a resolvable hostname within a Docker network.

To list the available Docker networks, execute the following command:

$ docker network ls
NETWORK ID          NAME                DRIVER              SCOPE
e7cc4767cc56        bridge              bridge              local
d5367c57ff2a        host                host                local
3b19dd6e3fa1        none                null                local

To create a Docker network, use the create command and specify a name for the network:

$ docker network create myoracle_network

Check that the Docker network was successfully created:

$ docker network ls
NETWORK ID          NAME                DRIVER              SCOPE
e7cc4767cc56        bridge              bridge              local
d5367c57ff2a        host                host                local
ee1a2d5df4ad        myoracle_network    bridge              local
3b19dd6e3fa1        none                null                local

To attach your Docker container to a specific network when you execute the run command, use the --network option:

$ docker run --name myxedb \
    ...
    --network myoracle_network \
    oracle/database:18.4.0-xe

Deploying to Oracle Cloud

Oracle Cloud is a great platform to consider if you are looking to deploy your Docker host and Oracle Database Express Edition to the cloud. Sign up to get a US$300 credit or 3,500 hours free on the Oracle Cloud for 30 days.

The following sections will help you get started with creating a single Oracle Cloud compute instance running Docker.

Compute instances are sold in shapes. (Resources provided by the various shapes are documented here.) Shape availability is dependent on the Oracle Cloud region. In the following demonstration, I select the VM.Standard.E2.1 shape, which provides one operator console processing unit (OCPU), which provides two vCPUs, a generous 8 GB of memory, and about 50 GB of storage.

Note that Oracle Cloud offers dedicated container-based services, and Oracle Cloud Infrastructure Registry service is available to Oracle Cloud customers at no cost other than for the storage and network resources consumed. This is a private Docker registry that can be used to store the Oracle Database Express Edition Docker image, so database containers can be easily deployed on other Docker host servers.

Ensure you have the required components. The following Oracle Cloud components are required for a basic Oracle Cloud compute setup:

• Virtual cloud network (VCN)
• Subnet
• Internet gateway
• Security rules
• Virtual machine

The goal is to set up a simple topology, as shown in Figure 1.

Figure 1: Oracle Cloud target topology

Create a compartment. Before you create the VCN, note that compartments are a great way to partition your resources for various intents. Do the following to create a compartment:

1. Click the hamburger menu (≡) and choose Identity and then Compartments.
2. On the Compartments page, create a compartment under the tenancy’s root compartment: To do that, click Create Compartment.
3. In the Name field, enter DEV and in the Description field, enter a description for the compartment, as shown in Figure 2.
4. For Parent Compartment, choose (root).
5. Click Create Compartment.

Figure 2: Create a compartment

Create a VCN. All resources need to live within a VCN. A VCN encapsulates the network subnets, gateways, and other networking components. Do the following to create a VCN:

1. Click the hamburger menu (≡) and choose Networking and then Virtual Cloud Networks.
2. On the Virtual Cloud Networks page, click Create Virtual Cloud Network.
3. As shown in Figure 3, specify the target compartment by selecting DEV from the Create in Compartment list.
4. In the Name field, enter a name, if desired.
5. In the CIDR Block field, specify the network range for this subnet, for example, 10.1.0.0/16. (There are online tools that can help you determine the IPv4 range for a classless inter-domain routing [CIDR] block.)
6. Click Create Virtual Cloud Network.

Figure 3: Create a VCN

Create a public subnet, create an internet gateway, and specify the route tables. Next, do the following:

1. On the VCN Details page, check that the correct compartment is selected on the left side of the page, and then click Create Subnet.
2. In the Name field, enter a name, if desired.
3. As shown in Figure 4, specify the following values:
   • For Subnet Type, select Regional (Recommended).
   • For CIDR Block, enter 10.1.1.0/24 (or the CIDR block you choose earlier).
   • For Route Table, select Default Route Table for vcn-dev.
   • For Subnet Access, select Public Subnet.
   • For Security Lists, select Default Security List for vcn-dev.

Figure 4: Create a subnet

4. Back on the VCN Details page, click Internet Gateways on the left.
5. On the Internet Gateways page, click Create Internet Gateway.
6. In the Name field, enter a name, if desired, and then click Create Internet Gateway, as shown in Figure 5.

Figure 5: Create an internet gateway

7. On the left, click Route Tables.
8. On the Route Tables page, select the default route table.
9. Click Edit Route Rules and then enter the following in the dialog box:
   • For Target Type, select Internet Gateway.
   • For Destination CIDR Block, enter 0.0.0.0/0.
   • For Compartment, select the compartment you created earlier.
   • For Target Internet Gateway, select the internet gateway you created earlier.

Create the virtual machine for the compute instance. To create the virtual machine, do the following:

1. Click the hamburger menu (≡) and choose Compute and then Instances.
2. On the Instances page, click Create Instance.
3. Provide the following information, as shown in Figure 6:
   • For Name, enter <<mydockerhost>>.
   • For Select an availability domain for your instance, choose AD 1.
   • For Choose an operating system or image source, choose Oracle Linux 7.6 (other options include Ubuntu, CentOS, and Windows Server).
   • For Choose instance type, select Virtual Machine.
   • For Choose instance shape, select VM.Standard.E2.1.
   • For Boot volume, leave the defaults selected.
   • For Add SSH key, either submit the public key file or paste in the SSH key.
   • For VCN, select the compartment and VCN.
   • For Subnet, select the compartment and subnet.

Figure 6: Create a virtual machine

Accessing the Server

You can access the server via the assigned public IP address.

Log in to the server using an SSH client with the opc user and the private key that generated the SSH public key provided during instance creation. The opc user is on the sudoers list and can perform system administration and installation tasks.

Conclusion

Docker’s ability to compartmentalize a complete environment for running an Oracle Database instance presents many opportunities for DBAs and developers alike. Though Docker’s use in a production environment is often debated, it certainly has a role in development and testing, and it can be used to help form a continuous integration pipeline. Docker can run code in a consistent environment across all levels during the software development cycle.

Docker supports the move from traditional software delivery methods to more versatile and efficient software delivery methods, presenting many opportunities for database developers to learn and to try new technologies. With the information provided in this article, you should be able to get started with Docker and Oracle Database Express Edition in no time.

Happy Dockering!

Next Steps

LEARN more about Docker.

TRY Oracle Cloud.

Illustration by Wes Rowell

Adrian Png

Adrian Png is a senior consultant at Insum. He has a passion for emerging technologies and believes that innovation, optimization, and adaptability are required to succeed in the data economy.