Skip to content

Latest commit

 

History

History
 
 

OracleUnifiedDirectory

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 

Oracle Unified Directory on Docker

Docker build files to facilitate installation, configuration, and environment setup for Docker DevOps users. For more information about Oracle Unified Directory please see the Oracle Unified Directory 12.2.1.3.0 Online Documentation.

Just to clarify these Docker build scripts are unofficial Oracle Build scripts.

Docker Images Content

The resulting Docker images are based on the official Oracle Java image for Java 8 u172 (oracle/serverjre:8). It has either be build manually using the official or my unofficial Oracle Docker build scripts or pulled from Docker Store. See Building the Oracle JDK base image

They base image will be extended to provide some additional Linux packages and configuration:

  • Install the following additional packages including there dependencies:
    • libaio Linux-native asynchronous I/O access library
    • tar A GNU file archiving program
    • gzip The GNU data compression program
  • Operating system user oracle (uid 1000)
  • Dedicated groups for user oracle, oracle (gid 1000), oinstall (gid 1010)
  • OUD Base environment developed by ORAdba
  • Oracle OFA Directories see below
  • Install Oracle Unified Directory 12c 12.2.1.3.0 (standalone) or Oracle Unified Directory 11g 11.1.2.3.0

Environment Variable and Directories

Based on the idea of OFA (Oracle Flexible Architecture) we try to separate the data from the binaries. This means that the OUD instance as well as configuration files are explicitly stored in a separate directory. Ideally, a volume is assigned to this directory when a container is created. This ensures data persistence over the lifetime of a container. OUD Base supports the setup and operation of the environment based on OFA. See also OraDBA.

The following environment variables have been used for the installation. In particular it is possible to modify the variables ORACLE_ROOT, ORACLE_DATA and ORACLE_BASE via build-arg during image build to have a different directory structure. All other parameters are only relevant for the creation of the container. They may be modify via docker run environment variables.

Environment variable Value / Directories Modifiable Comment
ORACLE_ROOT /u00 docker build Root directory for all the Oracle software
ORACLE_BASE $ORACLE_ROOT/app/oracle docker build Oracle base directory
n/a $ORACLE_BASE/product no Oracle product base directory
ORACLE_HOME_NAME fmw12.2.1.3.0 no Name of the Oracle Home, used to create to PATH to ORACLE_HOME eg. $ORACLE_BASE/product/$ORACLE_HOME_NAME
ORACLE_DATA /u01 docker build Root directory for the persistent data eg. OUD instances, etc. A docker volumes must be defined for /u01
INSTANCE_BASE $ORACLE_DATA/instances no Base directory for OUD instances
OUD_INSTANCE oud_docker docker run Default name for OUD instance
OUD_INSTANCE_HOME $INSTANCE_BASE/$OUD_INSTANCE docker run
OUD_INSTANCE_ADMIN $ORACLE_DATA/admin/$OUD_INSTANCE no Instance admin directory for custom scripts, config and logs
CREATE_INSTANCE TRUE docker run Flag to create OUD instance on first start of the container
OUD_PROXY FALSE docker run Flag to create proxy instance. Not yet implemented.
OUD_INSTANCE_INIT $ORACLE_DATA/scripts docker run Directory for the instance configuration scripts
PORT 1389 docker run Default LDAP port for the OUD instance
PORT_SSL 1636 docker run Default LDAPS port for the OUD instance
PORT_REP 8989 docker run Default replication port for the OUD instance
PORT_ADMIN 4444 docker run Default admin port for the OUD instance (4444)
ADMIN_USER cn=Directory Manager docker run Default admin user for OUD instance
ADMIN_PASSWORD n/a docker run No default password. Password will be autogenerated when not defined.
BASEDN dc=example,dc=com docker run Default directory base DN
SAMPLE_DATA TRUE docker run Flag to load sample data. Not yet implemented.
ETC_BASE $ORACLE_DATA/etc no Oracle etc directory with configuration files
LOG_BASE $ORACLE_DATA/log no Oracle log directory with log files
DOWNLOAD /tmp/download no Temporary download directory, will be removed after build
DOCKER_BIN /opt/docker/bin no Docker build and setup scripts
JAVA_DIR /usr/java no Base directory for java home location
JAVA_HOME $JAVA_DIR/jdk1.8.0_162 no Java home directory when build manually. The official docker image may have an other minor release.

In general it does not make sense to change all possible variables. Although BASEDN and ADMIN_PASSWORD are good candidates for customization. all other variables can generally easily be ignored.

Scripts to Build and Setup

The following scripts are used either during Docker image build or while setting up and starting the container.

Script Purpose
check_oud_instance.sh Check the status of the OUD instance for Docker HEALTHCHECK
config_oud_instance.sh Configure OUD instance using custom scripts
create_oud_instance.sh Script to create the OUD instance
start_oud_instance.sh Script to start the OUD instance
setup_oud.sh Script to install OUD binaries and patch
setup_oudbase.sh Script to install OUD base

Installation and Build

The required software has to be downloaded prior image build and must be part of the build context or made available in a local HTTP server. See Build with local HTTP server below. Providing a local HTTP server to download the required software during image build will lead into smaller images, since the software will not be part of an intermediate intermediate container. The docker build parameter --squash is not required. The procedure was briefly described in the blog post Smaller Oracle Docker images.

Obtaining Product Distributions

The Oracle Software required to setup an Oracle Unified Directory Docker image is basically not public available. It is subject to Oracle's license terms. For this reason a valid license is required (eg. OTN Developer License Terms). In addition, Oracle's license terms and conditions must be accepted before downloading.

The following software is required for the Oracle Unified Directory Docker image:

  • Oracle Unified Directory 12.2.1.3.0

The software can either be downloaded from My Oracle Support (MOS), Oracle Technology Network (OTN) or Oracle Software Delivery Cloud (OSDC). The following links refer to the MOS software download to simplify the build process.

The corresponding links and checksum can be found in *.download files. Alternatively the Oracle Support Download Links:

Building-the-Oracle-JDK-base-image

You must first download the Oracle Server JRE binary, locate it in the folder, ../OracleJava/java-8, and build that image. For more information, see the OracleJava folder's README file.

    $ cd ../OracleJava/java-8
    $ sh build.sh

You can also pull the Oracle Server JRE 8 image from the Oracle Container Registry or the Docker Store. When pulling the Server JRE 8 image, re-tag the image so that it works with the existing Dockerfiles.

    $ docker tag container-registry.oracle.com/java/serverjre:8 oracle/serverjre:8
    $ docker tag store/oracle/serverjre:8 oracle/serverjre:8

Build using COPY

Simplest method to build the OUD image is to manually download the required software and put it into the build folder respectively context. However this will lead to bigger Docker images, since the software is copied during build, which temporary blow up the container file-system.

Copy all files to the OracleUnifiedDirectory/12.2.1.3 folder.

cp p26270957_122130_Generic.zip OracleUnifiedDirectory/12.2.1.3

Build the docker image using docker build.

cd OracleUnifiedDirectory/dockerfiles/12.2.1.3
docker build -t oracle/oud:12.2.1.3 .

Build with local HTTP server

Alternatively the software can also be downloaded from a local HTTP server during build. For this a Docker image for an HTTP server is required eg. official Apache HTTP server Docker image based on alpine. See also Smaller Oracle Docker images.

Start a local HTTP server. httpd:alpine will be pulled from Docker Hub:

docker pull httpd:alpine
docker run -dit --hostname orarepo --name orarepo \
    -p 8080:80 \
    -v /Volumes/orarepo:/usr/local/apache2/htdocs/ \
    httpd:alpine

Make sure, that the software is know copied to the volume folder not part of the build context any more:

cd OracleUnifiedDirectory/dockerfiles/12.2.1.3
cp p26270957_122130_Generic.zip /Volumes/orarepo
rm p26270957_122130_Generic.zip

Get the IP address of the local HTTP server:

orarepo_ip=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' orarepo)

Build the docker image using docker build and provide the HTTP server.

cd OracleUnifiedDirectory/dockerfiles/12.2.1.3
docker build --add-host=orarepo:${orarepo_ip} -t oracle/oud:12.2.1.3.0 .

The RUN command in the Dockerfile will check if the software is part of the build context. If not, it will use the host orarepo to download the software. This way the OUD Docker image will be about 400MB smaller.

Running the Docker Images

Setup an Oracle Unified Directory Container

Creating a OUD container is straight forward with docker run command. The script start_oud_instance.sh will make sure, that a new OUD instance is created, when the container is started the first time. The instance is created using predefined values. (see below). If an OUD instance already exists, the script simply starts it.

The creation of the OUD instance can be influenced by the following environment variables. You only have to set them with option -e when executing "docker run".

  • ADMIN_PASSWORD OUD admin password (default autogenerated)
  • ADMIN_USER OUD admin user name (default cn=Directory Manager)
  • BASEDN Directory base DN (default dc=example,dc=com)
  • CREATE_DOMAIN Flag to create OUDS instance on first startup (default TRUE)
  • PORT Regular LDAP port (default 1389). Will also require to update the Dockerfile to expose a different port.
  • PORT_SSL SSL LDAP port (default 1636). Will also require to update the Dockerfile to expose a different port.
  • PORT_ADMIN OUD admin port (default 4444). Will also require to update the Dockerfile to expose a different port.
  • PORT_REP OUD replication port (default 8989). Will also require to update the Dockerfile to expose a different port.
  • OUD_INSTANCE OUD instance name (default oud_docker)
  • OUD_INSTANCE_HOME OUD home path (default /u01/instances/oud_docker)
  • OUD_INSTANCE_INIT default folder for OUD instance init scripts. These scripts are used to modify and adjust the new OUD instance.
  • OUD_PROXY Flag to create proxy instance (default FALSE) Not yet implemented.
  • SAMPLE_DATA Flag to load sample data (default TRUE) Not yet implemented.

Run your Oracle Unified Directory Docker image use the docker run command as follows:

docker run --name <container name> \
--hostname <container hostname> \
-p 1389:1389 -p 1636:1636 -p 4444:4444 \
-e OUD_INSTANCE=<your oud instance name> \
--volume [<host mount point>:]/u01 \
--volume [<host mount point>:]/u01/scripts \
oracle/oud:12.2.1.3.0

Parameters:
--name:           The name of the container (default: auto generated)
-p:               The port mapping of the host port to the container port.
                  for ports are exposed: 1389 (LDAP), 1636 (LDAPS), 4444 (Admin Port), 8989 (Replication Port)
-e OUD_INSTANCE:  The Oracle Database SYS, SYSTEM and PDB_ADMIN password (default: auto generated)
-e <Variables>    Other environment variable according "Environment Variable and Directories"
-v /u01
                  The data volume to use for the OUD instance.
                  Has to be writable by the Unix "oracle" (uid: 1000) user inside the container!
                  If omitted the OUD instance will not be persisted over container recreation.
-v /u01/app/oracle/scripts | /docker-entrypoint-initdb.d
                  Optional: A volume with custom scripts to be run after OUD instance setup.
                  For further details see the "Running scripts after setup" section below.

There are four ports that are exposed in this image:

  • 1389 which is the regular LDAP port to connect to the OUD instance.
  • 1636 which is the SSL LDAP port to connect to the OUD instance.
  • 4444 which is the admin port to connect and configure the OUD instance using dsconfig.
  • 8989 which is the replication port of the OUD instance.

On the first startup of the container a random password will be generated for the OUD instance if not provided. You can find this password in the output line. If you need to find the passwords at a later time, grep for "password" in the Docker logs generated during the startup of the container. To look at the Docker Container logs run:

docker logs --details oud|grep -i password

Alternatively you can check the OUD Base environment for the instance ($OUD_INSTANCE) and look for the password file. It is located under $PWD_FILE respectively _${OUD_INSTANCE_ADMIN}/etc/${OUD_INSTANCE}pwd.txt.

cat $PWD_FILE

cat ${OUD_INSTANCE_ADMIN}/etc/${OUD_INSTANCE}_pwd.txt

Create a simple OUD container with an example instance. Define the ports to expose and a local volume /Data/vm/docker/volumes/oudtest.

docker run --detach --name oudtest \
--hostname oudtest \
-p 1389:1389 -p 1636:1636 -p 4444:4444 \
--volume /Data/vm/docker/volumes/oudtest:/u01 \
oracle/oud:12.2.1.3

Check progress of initial startup and customization.

docker logs -f oudtest

Login using bash to access OUD instance localy via commandline.

user@host:/Data/ [ic12201] docker exec -it oudtest bash --login
Source environment for OUD Instance oud_docker
--------------------------------------------------------------
 Instance Name      : oud_docker
 Instance Home (ok) : /u01/instances/oud_docker
 Oracle Home        : /u00/app/oracle/product/fmw12.2.1.3.0
 Instance Status    : up
 LDAP Port          : 1389
 LDAPS Port         : 1636
 Admin Port         : 4444
 Replication Port   : 8989
--------------------------------------------------------------
oracle@oudtest:/u00/app/oracle/ [oud_docker]  

Running Bash in a Docker container

Access your OUD container via bash.

docker exec -u oracle -it oud bash --login

Running dsconfig in a Docker container

Execute dsconfig within the OUD container.

docker exec -u oracle -it oud dsconfig

Running scripts after setup

The OUD Docker image can be configured to run scripts after setup. Currently sh, ldif and conf extensions are supported. For post-setup scripts just create a folder scripts/setup in generic volume /u01, mount a dedicated volume /u01/scripts/setup or extend the image to include scripts in this directory. The location is also represented under the symbolic link /docker-entrypoint-initdb.d. This is done to provide synergy with other Docker images. The user is free to decide whether to put the setup scripts under /u01/scripts/setup or /docker-entrypoint-initdb.d. Alternatively it is also possible to specify the scripts in the create folder of the instance admin directory /u01/admin/$OUD_INSTANCE/create.

After the OUD instance is created by create_oud_instance.sh the scripts in those folders will be executed against the instance in the container. LDIF files (ldif) will be loaded using ldapmodify as cn=Directory Manager (ADMIN_USER). CONF files ( conf ) are interpreted as dsconfig batch files and will be executed accordingly. Shell scripts will be executed as the current user (oracle). To ensure proper order it is recommended to prefix your scripts with a number. For example 01_instance.conf, 02_schema_extention.ldif, etc. If files with the same name do exits eg. 02_schema_extention.ldif and 02_schema_extention.sh just the .sh file will be executed.

  • Note: The config scripts will only be executed when an instance is created on first startup or when using create_oud_instance.sh.
  • Note: If files with the same name do exits eg. 02_schema_extention.ldif and 02_schema_extention.sh just the .sh file will be executed.
  • Note: If /u01/admin/$OUD_INSTANCE/create folder exists, it is used instead of /u01/scripts/setup.

Frequently asked questions

Please see FAQ.md for frequently asked questions.

License

To download and run Oracle Unified Directory, regardless whether inside or outside a Docker container, you must download the binaries from the Oracle website and accept the license indicated at that page.

All scripts and files hosted in this project and GitHub docker-images/OracleUnifiedDirectory repository required to build the Docker images are, unless otherwise noted, released under UPL 1.0 license.

Copyright

Copyright (c) 2014-2017 Oracle and/or its affiliates. All rights reserved.