DOCSEARCHbyAlgolia
Submit Docs

Oracle Database Express Edition (XE) Container Images

repository·main·Indexed 43 days ago

https://github.com/gvenzl/oci-oracle-xe

Docker and Podman container images for Oracle Database Express Edition (XE), supporting versions 11g, 18c, and 21c. Includes various image flavors (Slim, Regular, Full, Faststart) and automation for pluggable databases, application users, and initialization scripts via /container-entrypoint-initdb.d.

Tokens
4.8K
Snippets
10
Records
22
Agent score
48%

What's inside Oracle XE

  1. Choose an Oracle Image Flavor

    main

    The project provides different image flavors optimized for various use cases:

    FlavorExtensionDescriptionUse Case
    Slim-slimSmallest possible size; minimal functionality.When image size is critical and advanced features aren't needed.
    Regular(None)Balanced size and functionality.Recommended for most use cases.
    Full-fullContains all Oracle Database installation functionality.Best for extensions or customizations.
    Faststart*-faststartIncludes an already expanded/ready database. Trades disk size for speed.Best for automated tests where containers are frequently created/destroyed.

  2. Upgrade to Oracle Database Free (23ai+)

    main
    The oci-oracle-xe repository is being maintained for a limited time. For newer versions like Oracle Database 23ai and full support for both Intel and ARM (Apple M chips), it is strongly recommended to migrate to the gvenzl/oracle-free images.

  3. Compare Oracle 21c XE image flavors

    main

    The 21c XE images come in three flavors depending on your requirements for functionality versus image size:

    1. Full image (21-full): Provides an Oracle Database XE installation "as is" (from the RPM), with minimal modifications to make it container-ready. It includes all components, including Oracle Text, Spatial, and Java packages.
    2. Regular image (21): A balanced flavor that removes several non-essential components (like Oracle Workspace Manager, Java Packages, and various utilities/drivers) to reduce size while maintaining core functionality.
    3. Slim image (21-slim): The smallest flavor, optimized for strictly relational database needs. It removes all non-relational components, including Oracle Text, Spatial, Locator, and even rman (Oracle Recovery Manager).

  4. Use Fast Start image flavors for quicker startup

    main

    The *-faststart image flavors are designed to provide faster container and database startup times by including already expanded database files within the image.

    Key characteristics:

    • Functionality: Identical to their non-faststart counterparts.
    • Disk Usage: Larger on disk because database files are not compressed.
    • Network Transfer: Since container images are compressed during transit, the download size is not substantially larger than regular images.
    • Layering Efficiency: These images add only one additional layer on top of the standard images. If the standard image is already present on your system, only the additional layer containing the expanded data needs to be pulled. Container runtimes can often pull this layer in parallel with others, minimizing download delays.

  5. Compare 18c XE image flavors

    main

    The 18c XE images come in three flavors depending on your needs for functionality versus image size:

    • Full (18-full): Provides the Oracle Database XE installation as provided by the RPM, with minor modifications for container suitability (e.g., CPU_COUNT=2, specific service names for upward compatibility, and UTF-8 support).
    • Regular (18): Balances functionality and size. It includes all 18-full customizations but removes components like the HR schema, Java packages, JDBC drivers, and various Oracle utilities/binaries (e.g., adrci, proc).
    • Slim (18-slim): Optimized for the smallest possible size. It includes all 18 customizations and further removes non-relational components such as Oracle Text, Oracle Spatial, RMAN, and Perl.

  6. Compare 11g XE image flavors

    main

    The 11g XE images are available in three flavors:

    • Full (11-full): The standard RPM installation with container optimizations like CPU_COUNT=1, disabled MEMORY_TARGET, and UTF-8 support.
    • Regular (11): Includes 11-full customizations but removes Oracle APEX, the HR schema, and JDBC drivers. It also excludes build tools like gcc and make from the OS.
    • Slim (11-slim): The smallest footprint. It includes 11 customizations and removes non-relational components like Oracle Text, XML DB, Oracle Spatial, and various demo/sample directories.

  7. Initialize the database with custom scripts

    main

    To perform additional database initialization (e.g., creating users, tables, or loading data) during the first container startup, place *.sql, *.sql.gz, *.sql.zip, or *.sh files in the /container-entrypoint-initdb.d directory.

    Key behaviors:

    • Execution Order: Files and subdirectories are executed in alphabetical order. Use numeric prefixes (e.g., 001_, 002_) to guarantee order.
    • SQL Files: *.sql files (including compressed versions) are executed via SQL*Plus as the SYS user connected to the XE instance. To initialize an application schema, you must explicitly switch containers or connect to that schema within the script (e.g., using ALTER SESSION SET CONTAINER=XEPDB1;).
    • Shell Files:
      • Executable *.sh files run in a new shell process.
      • Non-executable *.sh files are sourced into the current shell process. Sourcing allows scripts to influence the environment but should be used cautiously.
    • Lifecycle: These scripts run only the first time the database is initialized. Pre-existing databases are untouched.
    • Warning: If a sourced script fails, the container entrypoint will exit, potentially leaving the database in an incomplete state. Do not exit executable scripts with a non-zero value unless you intend to stop the container.
    # Example: Mounting a local directory containing init scripts to the container
docker run --name test \
         -p 1521:1521 \
         -e ORACLE_RANDOM_PASSWORD="y" \
         -v /home/gvenzl/init_scripts:/container-entrypoint-initdb.d \
     gvenzl/oracle-xe:18.4.0-full

  8. Run scripts on every database startup

    main

    If you need to perform actions every time the database starts (including after a restart of an existing database), place *.sql, *.sql.gz, *.sql.zip, or *.sh files in the /container-entrypoint-startdb.d directory.

    Key behaviors:

    • Execution Order: Files and subdirectories are executed in alphabetical order.
    • Lifecycle: Unlike initialization scripts, these are executed every time the database is started. If it is a fresh installation, these run after the initialization scripts have completed.
    • Warning: Use this mechanism only for tasks that must occur every time the container is up. Avoid using the legacy /docker-entrypoint-startdb.d directory to prevent duplicate execution if you are already using /container-entrypoint-startdb.d.

  9. Run Oracle XE on Apple M chips (ARM)

    main

    Oracle XE images do not have native ARM support and cannot run directly via Docker Desktop on Apple M chips. To run them, you must use colima to emulate an x86_64 environment:

    1. Install colima.
    2. Start colima with the x86_64 architecture and sufficient memory: colima start --arch x86_64 --memory 4
    3. Start your Oracle XE container as usual.
    colima start --arch x86_64 --memory 4

  10. Quick Start: Run Oracle XE with Docker or Podman

    main

    You can run Oracle Database Express Edition (XE) using docker or podman. These commands cover non-persistent (data lost on removal) and persistent (data kept via volumes) setups.

    Important Note on 11g R2: If you are using the 11g R2 version, the volume mount path must be /u01/app/oracle/oradata instead of the standard /opt/oracle/oradata used by newer versions.

    # Run a new non-persistent database container
docker run -d -p 1521:1521 -e ORACLE_PASSWORD=<your password> gvenzl/oracle-xe

# Run a new persistent database container
docker run -d -p 1521:1521 -e ORACLE_PASSWORD=<your password> -v oracle-volume:/opt/oracle/oradata gvenzl/oracle-xe

# Run a new persistent 11g R2 database container
docker run -d -p 1521:1521 -e ORACLE_PASSWORD=<your password> -v oracle-volume:/u01/app/oracle/oradata gvenzl/oracle-xe:11

  11. Use Oracle XE as a GitHub Actions Service Container

    main

    You can use gvenzl/oracle-xe images as service containers in GitHub Actions workflows. This allows you to run integration tests against a real Oracle database during your CI pipeline.

    Connection Details

    Once the service is running, connect using:

    • Hostname: oracle (if connecting from another container in the same job) or localhost/127.0.0.1 (from the host).
    • Port: 1521 (or the dynamic port provided by GitHub Actions).
    • Service Name: FREEPDB1 (Note: check your specific version/flavor as this may vary).
    • Admin User: system with password set via ORACLE_PASSWORD.
    • App User: Defined via APP_USER and APP_USER_PASSWORD.

    Dynamic Port Allocation

    If you use dynamic port mapping (e.g., not specifying - 1521:1521), you can access the assigned port in your workflow using: ${{ job.services.oracle.ports[1521] }}.

    Example JDBC connection string with dynamic port: jdbc:oracle:thin:@localhost:${{ job.services.oracle.ports[1521] }}/XEPDB1

        services:
      # Oracle service
      oracle:
        image: gvenzl/oracle-xe:latest
        env:
          ORACLE_RANDOM_PASSWORD: true
          APP_USER: my_user
          APP_USER_PASSWORD: my_password_which_I_really_should_change
        ports:
          - 1521:1521
        options: >-
          --health-cmd healthcheck.sh
          --health-interval 10s
          --health-timeout 5s
          --health-retries 10

  12. Use Container Secrets for sensitive configuration

    main

    Instead of passing sensitive information like passwords via plain-text environment variables, you can append _FILE to specific environment variable names. This instructs the initialization script to load the value from a file (e.g., a Docker or Kubernetes secret) located at the specified path.

    Supported variables for the _FILE suffix:

    • APP_USER_PASSWORD_FILE
    • ORACLE_PASSWORD_FILE
    • ORACLE_DATABASE_FILE
    docker run --name some-oracle -e ORACLE_PASSWORD_FILE=/run/secrets/oracle-passwd -d gvenzl/oracle-xe