saurabhahuja71 · Nov 5, 2026
@@ -1,4 +1,4 @@
-Copyright (c) 1982 - 2026, Oracle Corporation.  All rights reserved.  
+Copyright (c) 1982 - 2026, Oracle Corporation.  All rights reserved.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

@@ -14,7 +14,7 @@ An example would be: `docker run ... -e TZ="Europe/Vienna" oracle/database:12.2.
 
 ## Can I run Oracle Database containers on Apple M1 (Arm) devices?
 
-Oracle Database 19c Enterprise Edition and 26ai Free Edition are now supported on ARM64 platforms. You will have to provide the installation binaries of [Oracle Database 19c](https://www.oracle.com/database/technologies/oracle19c-linux-arm64-downloads.html) and place them in the `dockerfiles/19.3.0` folder before running the `buildContainerImage.sh` script.
+Oracle Database 19c Enterprise Edition and 26ai Free Edition are now supported on ARM64 platforms. You will have to provide the installation binaries of [Oracle Database 19c](https://www.oracle.com/database/technologies/oracle19c-linux-arm64-downloads.html) and place them in the `containerfiles/19.3.0` folder before running the `buildContainerImage.sh` script.
 
 ## checkSpace.sh: ERROR - There is not enough space available in the container
 
@@ -48,6 +48,68 @@ podman unshare chown 54321:54321 ~/data/my_db
 
 Last but not least, if SELinux is enabled, the mapped folder should be properly labeled. If you encounter SELinux permission issues, you can add the `:Z` flag to the bind mounts.
 
+### Rootless Podman: bind-mount startup failures
+
+When a rootless Podman container fails while expanding the prebuilt database and
+the log contains errors such as `Cannot utime`, `Cannot change mode`, or
+`Permission denied`, check both the host directory ownership and the Podman
+storage configuration. The database image is not necessarily the cause of the
+failure.
+
+Use either rootless Podman or rootful Podman consistently for a data directory.
+Do not use `sudo podman` to create or modify a directory that will later be
+used by rootless `podman`.
+
+The following example is POSIX-shell syntax. Only move the old directory if its
+database contents are disposable or backed up:
+
+```shell
+HOST_DATA_ROOT=/path/to/containers
+cd "$HOST_DATA_ROOT"
+mv primdb1 "primdb1.bak.$(date +%Y%m%d%H%M%S)"
+mkdir -p primdb1
+chmod 750 primdb1
+podman unshare chown -R 54321:54321 "$HOST_DATA_ROOT/primdb1"
+podman unshare stat -c '%u:%g %a %n' "$HOST_DATA_ROOT/primdb1"
+```
+
+The `chown` must be run through `podman unshare`: container UID 54321 is
+normally represented by a subordinate host UID, not by host UID 54321. The
+rootless user must have suitable ranges in `/etc/subuid` and `/etc/subgid`.
+If the existing data must be retained, use a new directory and make a
+database-aware backup or copy instead of deleting or blindly changing the old
+directory.
+
+Rootless overlay storage also requires a mount program when `force_mask` is
+configured. In the rootless user's `~/.config/containers/storage.conf`, use
+the installed `fuse-overlayfs` path and do not enable `force_mask` when it
+masks the modes required by the database files:
+
+```toml
+[storage.options.overlay]
+mount_program = "/bin/fuse-overlayfs"
+# force_mask = "700"
+```
+
+An active `force_mask = "700"` can cause listener and database permission
+errors, including `TNS-12546` and `ORA-49801`, even after the bind directory
+ownership has been corrected. Confirm the effective rootless configuration with
+`podman info --debug`; it reports the user storage configuration, graph options,
+and whether SELinux is enabled.
+
+For persistent database data, a named volume is another option and avoids most
+host bind-mount UID and labeling issues:
+
+```shell
+podman volume create oracle-data
+podman run ... -v oracle-data:/opt/oracle/oradata ...
+```
+
+On an SELinux-enabled host, apply the documented bind-mount labeling (usually
+`:Z`) in addition to the ownership steps above. A host with SELinux disabled
+does not need an SELinux relabel; it can still fail because of rootless UID
+mapping, stale ownership, or `force_mask`.
+
 ## ORA-00600: internal error code, arguments: [pesldl03_MMap: errno 1 errmsg Operation not permitted], [], [], [], [], [], [], [], [], [], [], []
 
 This error happens if you try to use native compilation for PL/SQL but haven't assigned `exec` rights to `/dev/shm`.

@@ -49,14 +49,14 @@ The `buildContainerImage.sh` script is just a utility shell script that performs
 
 ### Building Oracle Database container images
 
-**IMPORTANT:** You will have to provide the installation binaries of Oracle Database (except for Oracle Database 21c XE and 26ai Free) and put them into the `dockerfiles/<version>` folder.
+**IMPORTANT:** For versions before 19.3.0, put the installation binaries in `dockerfiles/<version>`. For 19.3.0 and later, use `containerfiles/<version>`.
 You only need to provide the binaries for the edition you are going to install. The binaries can be downloaded from the [Oracle Technology Network](http://www.oracle.com/technetwork/database/enterprise-edition/downloads/index.html), make sure you use the linux link: *Linux x86-64*. The needed file is named *linuxx64_\<version\>_database.zip*.
 
-**Linux ARM64 Support:** Oracle Database 19c Enterprise Edition and 26ai Free Edition are now supported on ARM64 platforms. You will have to provide the installation binaries of [Oracle Database 19c](https://www.oracle.com/database/technologies/oracle19c-linux-arm64-downloads.html) and put them into the dockerfiles/19.3.0 folder. The needed file is named *LINUX.ARM64_1919000_db_home.zip*.
+**Linux ARM64 Support:** Oracle Database 19c Enterprise Edition and 26ai Free Edition are now supported on ARM64 platforms. You will have to provide the installation binaries of [Oracle Database 19c](https://www.oracle.com/database/technologies/oracle19c-linux-arm64-downloads.html) and put them into the `containerfiles/19.3.0` folder. The needed file is named *LINUX.ARM64_1919000_db_home.zip*.
 
 You also have to make sure to have internet connectivity for yum. Note that you must not uncompress the binaries. The script will handle that for you and fail if you uncompress them manually!
 
-Before you build the image make sure that you have provided the installation binaries and put them into the right folder. Once you have chosen which edition and version you want to build an image of, go into the **dockerfiles** folder and run the **buildContainerImage.sh** script:
+Before you build the image make sure that you have provided the installation binaries and put them into the right folder. Run the **buildContainerImage.sh** script from the `dockerfiles` directory; it selects the legacy `dockerfiles/<version>/Dockerfile` for versions before 19.3.0 and the modern `containerfiles/<version>/Containerfile` for 19.3.0 and later.
 
     [oracle@localhost dockerfiles]$ ./buildContainerImage.sh -h
 
@@ -126,7 +126,7 @@ Option 2: Download from a web URL that does not require authentication:
       -t oracle/database:19.3.0-ee \
       -o '--build-arg BACKUP_MODULE_URL=<backup-module-rpm-url>'
 
-Option 3: Install from a local file system location. Place the RPM under the selected version directory and pass its relative path using `BACKUP_MODULE_LOCAL_FILE`. For example, if the RPM is stored as `dockerfiles/23.26.0/backup-modules/bck2cloud.rpm`:
+Option 3: Install from a local file system location. Place the RPM under the selected version directory and pass its relative path using `BACKUP_MODULE_LOCAL_FILE`. For example, if the RPM is stored as `containerfiles/23.26.0/backup-modules/bck2cloud.rpm`:
 
     ./buildContainerImage.sh \
       -v 23.26.0 \
@@ -149,15 +149,19 @@ Patched container images can now be built by specifying the parameter -p. Downlo
 
 #### Building the container images using Podman
 
-Building Oracle Database container images using Podman is similar to Docker. Some additional environment variables are required to be set for proper functioning. The description is as follows:
+Building Oracle Database container images using Podman is similar to Docker. The build scripts automatically use Docker image format for Podman builds so that the `HEALTHCHECK` metadata is preserved. For rootless Linux builds, set the following environment variable:
 
-* `export BUILDAH_FORMAT=docker` (Required to support `HEALTHCHECK` specified in the Dockerfile)
 * `export BUILDAH_ISOLATION=chroot` (Required while building the container image in rootless mode)
 
-After setting these environment variables, the container image can be built using `buildContainerImage.sh` script as follows:
+After setting this environment variable, the container image can be built using `buildContainerImage.sh` script as follows:
 
     ./buildContainerImage.sh -e -v <version-to-build>
 
+RPM provenance is always recorded under `/usr/share/oracle/image-metadata/rpms`.
+Inspect it with:
+
+    podman run --rm --entrypoint /bin/sh IMAGE -c \
+      'ls -l /usr/share/oracle/image-metadata/rpms && cat /usr/share/oracle/image-metadata/rpms/*.txt'
 ### Running Oracle Database in a container
 
 #### Running Oracle Database Enterprise and Standard Edition 2 in a container
@@ -180,6 +184,7 @@ To run your Oracle Database image use the `podman run` command as follows:
     -e ENABLE_FORCE_LOGGING=true \
     -e ENABLE_TCPS=true \
     -e TRUE_CACHE=true \
+    -e TDE_ENABLED=true \
     -e TDE_WALLET_PWD=<your password for TDE wallet> \
     -e PRIMARY_DB_PWD_FILE=<Location of the primary database password file> \
     -e PRIMARY_DB_TDE_WALLET=<Location of the primary database TDE wallet> \
@@ -240,8 +245,11 @@ To run your Oracle Database image use the `podman run` command as follows:
        -e TRUE_CACHE:
                       To configure Oracle True Cache instance.
                       Supported from Oracle 26ai onwards.
+       -e TDE_ENABLED:
+                      Set to 'true' to configure TDE during Enterprise/SE2 database creation.
+                      Use together with TDE_WALLET_PWD or the tde_wallet_pwd Podman secret.
        -e TDE_WALLET_PWD:
-                      Password for TDE wallet to configure TDE.
+                      Password for the TDE wallet when TDE_ENABLED=true.
        -e PRIMARY_DB_PWD_FILE:
                       <Location of the primary database password file inside the True Cache container>  (Required if TRUE_CACHE=true)
        -e PRIMARY_DB_TDE_WALLET:
@@ -262,6 +270,9 @@ To run your Oracle Database image use the `podman run` command as follows:
                       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.
 
+For rootless Podman volume permissions and storage configuration, see the
+[SingleInstance FAQ](FAQ.md#rootless-podman-bind-mount-startup-failures).
+
 Once the container has been started and the database created you can connect to it just like to any other database:
 
     sqlplus sys/<your password>@//localhost:1521/<your service name> as sysdba
@@ -465,9 +476,9 @@ The ORACLE_SID for Oracle Database 26ai Free is always `FREE` and cannot be chan
 | `-p` | Map listener `1521`, OEM Express `5500`, and TCPS `2484` when TCPS is enabled | Map listener `1521`; OEM Express `5500` is exposed by the image | Maps host ports to container ports. | Optional, required for host access |
 | `--ulimit` | Recommended for Enterprise/SE2 database containers | Not shown in the Free example | Resource limits. Set according to Oracle Database documentation and host policy. | Recommended for Enterprise/SE2 |
 | `ORACLE_SID` | Supported; default is `ORCLCDB` | Do not set; Free always uses `FREE` | Oracle Database SID. | Optional for Enterprise/SE2, not used for Free |
-| `ORACLE_PDB` | Supported; default is `ORCLPDB1` | Do not set; Free uses `FREEPDB1` | Oracle Database PDB name. | Optional for Enterprise/SE2, not used for Free |
+| `ORACLE_PDB` | Supported; default is `ORCLPDB1` | Free uses `FREEPDB1`, including Free prebuilt images | Oracle Database PDB name. | Optional for Enterprise/SE2; not used for Free |
 | `ORACLE_PWD` | Supported; auto-generated if omitted | Supported; auto-generated if omitted | SYS, SYSTEM, and PDBADMIN password. Podman secrets can provide this through `oracle_pwd`. | Optional |
-| `ORACLE_CHARACTERSET` | Supported; default is `AL32UTF8` | Supported; default is `AL32UTF8` | Character set used when creating the database. | Optional |
+| `ORACLE_CHARACTERSET` | Supported; creation defaults to `AL32UTF8` | Creation defaults to `AL32UTF8`; Free prebuilt images retain the current character set if omitted | Character set used when creating the database or converting a Free prebuilt PDB. | Optional |
 | `INIT_SGA_SIZE` | Supported from 19.3 onward | Not shown in the Free example | Total SGA memory in MB used during first database creation. | Optional |
 | `INIT_PGA_SIZE` | Supported from 19.3 onward | Not shown in the Free example | Target aggregate PGA memory in MB used during first database creation. | Optional |
 | `INIT_CPU_COUNT` | Supported | Not shown in the Free example | Sets the `CPU_COUNT` initialization parameter. | Optional |
@@ -478,9 +489,10 @@ The ORACLE_SID for Oracle Database 26ai Free is always `FREE` and cannot be chan
 | `ENABLE_FORCE_LOGGING` | Supported from 26ai onward | Not shown in the Free example | Enables force logging during first database creation. | Optional |
 | `ENABLE_TCPS` | Supported from 19.3 onward | Not shown in the Free example | Enables TCPS listener endpoint on container port `2484`. | Optional |
 | `TCPS_CERTS_LOCATION` | Supported from 19.3 onward | Not shown in the Free example | In-container location of user-provided `cert.crt` and `client.key` files for TCPS. | Optional |
+| `TDE_ENABLED` | Supported for TDE wallet configuration | Not shown in the Free example | Enables TDE configuration during Enterprise/SE2 database creation. Set this to `true` together with `TDE_WALLET_PWD` (or the `tde_wallet_pwd` Podman secret). | Conditional for TDE |
 | `CONFIGURE_TDE` | Not shown in the Enterprise/SE2 example | Supported from 26ai onward | Enables TDE configuration for Free image database creation. | Optional |
 | `ENCRYPT_TABLESPACES` | Not shown in the Enterprise/SE2 example | Supported | Tablespace encryption list. Leave empty for user tablespace only, set `ALL`, or use entries such as `SYSTEM:true,SYSAUX:false`. | Optional |
-| `TDE_WALLET_PWD` | Supported for TDE wallet configuration | Not shown in the Free example | Password for TDE wallet configuration. Can also be provided through the `tde_wallet_pwd` Podman secret. | Conditional for TDE |
+| `TDE_WALLET_PWD` | Used when `TDE_ENABLED=true` | Not shown in the Free example | Password for TDE wallet configuration. Can also be provided through the `tde_wallet_pwd` Podman secret. | Conditional for TDE |
 | `TRUE_CACHE` | Supported from 26ai onward when running a True Cache container | Use the True Cache extension image flow for Free True Cache | Marks the container as a True Cache host. For complete primary plus True Cache Podman setup, use `extensions/truecache/README.md`. | Conditional for True Cache |
 | `PRIMARY_DB_CONN_STR` | Required when `TRUE_CACHE=true` | Required in Free True Cache extension flow | Primary database connection string in `<HOST>:<PORT>/<SERVICE_NAME>` format. | Conditional for True Cache |
 | `PRIMARY_DB_NAME` | Optional when the primary DB_NAME differs from the service name | Optional when the primary DB_NAME differs from the service name | Primary source DB_NAME override. | Optional |
@@ -565,7 +577,7 @@ To containerize an on-premise database, please follow the steps mentioned below:
 
         cd $ORACLE_HOME && ./runInstaller -silent -createGoldImage -destinationLocation '<location to store the gold image>'
 
-* The gold image created in the step above will have the name like `db_home_2022-03-25_12-43-21PM.zip`. Copy this gold image to the `OracleDatabase/SingleInstance/dockerfiles/<version>` directory. The **version** would be the base version of the gold image, e.g. 19.3.0.
+* The gold image created in the step above will have the name like `db_home_2022-03-25_12-43-21PM.zip`. Copy this gold image to `OracleDatabase/SingleInstance/containerfiles/<version>` for 19.3.0 and later, or `dockerfiles/<version>` for older releases.
 * Create the container image using this gold image by the following sample command:
 
         ./buildContainerImage.sh -i -e -v 19.3.0 -t oracle/database:19-onprem -o '--build-arg INSTALL_FILE_1=db_home_2022-03-25_12-43-21PM.zip'

@@ -1,12 +1,13 @@
 # syntax=docker/dockerfile:1.7
+# hadolint global ignore=DL4006
 # LICENSE UPL 1.0
 #
 # Copyright (c) 2018, 2026 Oracle and/or its affiliates.
 #
-# ORACLE DOCKERFILES PROJECT
+# ORACLE CONTAINERFILES PROJECT
 # --------------------------
-# This is the Dockerfile for Oracle Database 19c
-# 
+# This is the Containerfile for Oracle Database 19c
+#
 # REQUIRED FILES TO BUILD THIS IMAGE
 # ----------------------------------
 # (1) db_home.zip
@@ -15,15 +16,19 @@
 #
 # HOW TO BUILD THIS IMAGE
 # -----------------------
-# Put all downloaded files in the same directory as this Dockerfile
-# Run: 
-#      $ docker build -t oracle/database:19.3.0-${EDITION} . 
+# Put all downloaded files in the same directory as this Containerfile
+# Run:
+#      $ podman build -t oracle/database:19.3.0-${EDITION} .
 #
 # Pull base image
 # ---------------
 ARG BASE_IMAGE=oraclelinux:9
 # hadolint ignore=DL3006
 FROM ${BASE_IMAGE} as base
+RUN \
+      mkdir -p /usr/share/oracle/image-metadata/rpms && \
+      rpm -qa --qf '%{NAME}-%{VERSION}-%{RELEASE}.%{ARCH}\n' | sort > /usr/share/oracle/image-metadata/rpms/base-image-rpms.txt && \
+      rpm -qa --qf '%{NAME}\n' | sort -u > /usr/share/oracle/image-metadata/rpms/base-image-rpm-names.txt;
 
 # Labels
 # ------
@@ -195,13 +200,28 @@ RUN chmod ug+x "$INSTALL_DIR"/*.sh && \
 #############################################
 
 FROM base
+USER root
+
+RUN \
+      rpm -qa --qf '%{NAME}-%{VERSION}-%{RELEASE}.%{ARCH}\n' | sort > /usr/share/oracle/image-metadata/rpms/image-rpms.txt && \
+      rpm -qa --qf '%{NAME}	%{VERSION}-%{RELEASE}.%{ARCH}\n' | sort > /tmp/image-rpm-details && \
+      if [ -f /usr/share/oracle/image-metadata/rpms/base-image-rpm-names.txt ]; then \
+        awk -F '\t' 'NR==FNR {base[$1]=1; next} !($1 in base) {print $1 "-" $2}' /usr/share/oracle/image-metadata/rpms/base-image-rpm-names.txt /tmp/image-rpm-details > /usr/share/oracle/image-metadata/rpms/image-added-rpms.txt; \
+      else \
+        cp /usr/share/oracle/image-metadata/rpms/image-rpms.txt /usr/share/oracle/image-metadata/rpms/image-added-rpms.txt; \
+      fi && \
+      rm -f /tmp/image-rpm-details;
 
 USER oracle
 COPY --chown=oracle:dba --from=builder $ORACLE_BASE $ORACLE_BASE
 
 USER root
 RUN "$ORACLE_BASE"/oraInventory/orainstRoot.sh && \
-    "$ORACLE_HOME"/root.sh
+    "$ORACLE_HOME"/root.sh && \
+    setpriv --reuid=54321 --regid=54321 --init-groups env HOME=/home/oracle \
+      "$ORACLE_HOME"/oui/bin/runInstaller -silent -ignoreSysPrereqs -attachHome \
+      ORACLE_HOME="$ORACLE_HOME" ORACLE_HOME_NAME=OraDB19Home1 \
+      -invPtrLoc /etc/oraInst.loc
 
 USER oracle
 WORKDIR /home/oracle
@@ -213,5 +233,5 @@ RUN echo 'ORACLE_SID=${ORACLE_SID:-ORCLCDB}; export ORACLE_SID=${ORACLE_SID^^}'
 HEALTHCHECK --interval=1m --start-period=5m --timeout=30s \
    CMD "$SCRIPT_BASE_DIR/$CHECK_DB_FILE" >/dev/null || exit 1
 
-# Define default command to start Oracle Database. 
+# Define default command to start Oracle Database.
 CMD [ "/bin/bash", "-c", "exec $SCRIPT_BASE_DIR/$RUN_FILE" ]
@@ -1,4 +1,5 @@
 #!/bin/bash
+# shellcheck disable=SC2166,SC2164
 # LICENSE UPL 1.0
 #
 # Copyright (c) 1982-2022 Oracle and/or its affiliates. All rights reserved.