Run Oracle Database Non-CDB in Docker – Step-by-Step Setup + Fix Common Errors

Introduction

Many enterprise applications still depend on the traditional Non-CDB database architecture used in Oracle Database before the multitenant model was introduced. While modern Oracle versions focus on container databases, many legacy systems still require a Non-CDB database environment for compatibility, testing, or learning purposes.

Setting up an Oracle database manually can be complex and time-consuming. This is where Docker becomes extremely useful. Docker allows developers and database administrators to quickly create isolated environments where databases can run inside containers without installing Oracle directly on the host machine.

By running Oracle Non-CDB databases in Docker, you can easily create repeatable test environments, experiment with database configurations, and work with legacy applications safely.

This guide is designed for DBAs, developers, DevOps engineers, and students who want to understand how to run an Oracle Non-CDB database inside a Docker container.

By the end of this tutorial, you will learn how to:

• Create an Oracle Non-CDB database in Docker

• Run and manage the containerized database

• Verify that the database is working correctly

  
  

Understanding Non-CDB vs CDB in Oracle Database

In Oracle Database, there are two main database architectures:

            Non-CDB (Non-Container Database)
            CDB (Container Database)
Understanding the difference between CDB vs Non-CDB is important when working with legacy applications or when deploying databases in containerized environments such as Docker.
What is a Non-CDB Database?

A Non-CDB (Non-Container Database) is the traditional Oracle database architecture used before Oracle introduced the multitenant model.

In this architecture:

• A single database instance manages everything

• Users, schemas, tables, and data exist in one standalone database

• There are no pluggable databases (PDBs)

Because of its simplicity, many legacy enterprise applications were built specifically for Non-CDB environments. As a result, many organizations still maintain Non-CDB databases for compatibility and testing purposes.

What is a CDB Database?

A CDB (Container Database) is part of Oracle’s multitenant architecture.

A single CDB can host multiple databases known as Pluggable Databases (PDBs).

Each PDB behaves like an independent database, but they share the same Oracle instance and system resources.

This architecture offers several advantages:

• Better resource utilization

• Easier database management

• Ability to run multiple databases in one instance

Quick Comparison: CDB vs Non-CDB

Feature	Non-CDB	CDB
Architecture	Single standalone database	Container with multiple PDBs
Resource sharing	No	Yes
Scalability	Limited	High
Primary use	Legacy applications	Modern deployments

Why Non-CDB Databases Are Still Used?

Even though Oracle promotes the multitenant architecture, Non-CDB databases are still widely used in many environments.

Here are some common reasons:
1. Legacy Applications
Many enterprise systems were originally built to run on Non-CDB architecture, making migration difficult or costly.
2. Learning and Training
Students and beginners often start with Non-CDB databases to understand the core structure of Oracle databases.
3. Development and Testing
Developers sometimes require a simple standalone Oracle database to test applications or reproduce issues.

Why Oracle Removed Non-CDB in 21c ??? big question right please refer : Link

Step-by-Step: Pull the Oracle Docker Image

1. Open oracle container registry - link
2. If no account created previously, create account for registry.
3. select image and click on continue, i am selecting enterprise and accept terms

4. After this click on profile and select auth and generate secret key:

5. Copy the secret key and store it safely.
6. Run docker command to login to registry

docker login container-registry.oracle.com

provide user name and the secret

7. Pull the Docker image using  pull command

docker pull container-registry.oracle.com/database/enterprise:19.3.0.0

Step-by-Step: Run the Non-CDB Container

1. Instead of running long Docker commands manually, we can define the container configuration using Docker Compose. Create a file called docker-compose.yml and add the following configuration.

version: "3.9"

services:

oracle:

container_name: base

image: container-registry.oracle.com/database/enterprise:19.3.0.0

ports:

- "1521:1521"

environment:

ORACLE_PWD: "Oracle19"

ACCEPT_EULA: "Y"

HOSTNAME: ${COMPUTERNAME}

Port mapping explanation

ports:

    - "1521:1521"

This maps port 1521 inside the container to port 1521 on your host machine.
ORACLE_PWD: "Oracle19" : - Sets the password for the SYS, SYSTEM, and PDBADMIN users.
ACCEPT_EULA: "Y" : - Accepts the Oracle license agreement automatically so the container can start.
HOSTNAME: ${COMPUTERNAME}: -Sets the hostname for the container using the system's computer name.

Port 1521 is the default Oracle Listener port, which allows external tools such as:

• SQL clients

• Database applications

• Developer tools

to connect to the database running inside the container.

Environment Variables

Environment variables configure the Oracle database during container startup.

2. Then run the docker compose comand to run the container

docker-compose up -d

3. After starting the container, you can verify that it is running with:

docker ps

you  will see below data:

If the container appears in the list, your Oracle Non-CDB Docker container is running successfully.

4. Enter into the container with:

docker exec -it <containerId> /bin/sh

5. Run the command to configure the DB, here i am using DB name sample

dbca -silent -createDatabase -templateName General_Purpose.dbc -gdbName sample -sid sample -sysPassword Oracle19 -systemPassword Oracle19 -emConfiguration NONE -datafileDestination /opt/oracle/oradata/ 

This command automatically creates a new Oracle database named sample with:

• General purpose configuration

• SID = sample

• SYS and SYSTEM passwords = Oracle19

• No Enterprise Manager

• Data stored in /opt/oracle/oradata

All of this happens without user interaction, which makes it ideal for automation and container environments.

Wait for few min, and you will see in the logs that DB is created.

6. Verify that the DB is created, run below command:

ps -ef | grep pmon

7. To check you have Non CDB DB run below command:

sqlplus / as sysdba <<'SQL'

SELECT cdb FROM v$database;

SQL

If the result is No its Non CDB oracle DB: 

you can also run the same command from Oracle SQL developer

a. Once opened click on the "+" symbol

b. In name and SID section provide DB name / SID name we given which is sample in this case,
mention Username and Password (as global we already mentioned in Docker-Compose.yml) then click on connect.

c. You will see the sample DB.

d. Now open worksheet and check the DB is non CDB

SELECT cdb FROM v$database;

Creating a Reusable Non-CDB Oracle Docker Image

At this stage you might think:

“I already have a running Oracle container. I can simply run docker commit and create a reusable image for my Non-CDB database.”

Unfortunately, it’s not that simple.

Common Errors / Problem:

By default, Oracle Database Docker images are designed to work with the CDB (Container Database) architecture with PDBs. Even if you commit the running container using Docker, the resulting image will still follow the default Oracle configuration.

To ensure that the container always starts with your Non-CDB configuration, you need to modify the startup process of the container. In container by default there is script "startUp.sh"

Update this script with below code, copy paste it at the end of the script

export ORACLE_SID=sample
sqlplus / as sysdba <<'SQL'
WHENEVER SQLERROR CONTINUE
STARTUP;
SELECT instance_name, status FROM v$instance;
SHOW PARAMETER service_names;
ALTER SYSTEM SET service_names='sample' SCOPE=BOTH;
ALTER SYSTEM REGISTER;
EXIT;
SQL

Now replace old script with latest changed script and then commit the container as an image. 

Whenever you start a container from this new image, the updated startup script will run automatically. This means the Oracle database will start with the Non-CDB configuration every time the container starts.

This approach is useful when you need to:

• Quickly spin up multiple Non-CDB environments

• Maintain consistent Oracle testing environments

• Run legacy Oracle applications that require Non-CDB architecture

=====================================================================

Related Articles:

• Complete guide to connect SQL DB to python