From 4caea7702448af68cec8efc90fccc9e13e176408 Mon Sep 17 00:00:00 2001 From: Stephen Balousek Date: Fri, 20 Oct 2017 10:21:17 -0700 Subject: [PATCH] Oracle GoldenGate (#608) - Add Contents section to README Signed-off-by: Stephen Balousek --- OracleGoldenGate/README.md | 58 ++++++++++++++++++++++++++------------ 1 file changed, 40 insertions(+), 18 deletions(-) diff --git a/OracleGoldenGate/README.md b/OracleGoldenGate/README.md index d1b2d263ed..74b856665b 100644 --- a/OracleGoldenGate/README.md +++ b/OracleGoldenGate/README.md @@ -1,10 +1,28 @@ Oracle GoldenGate on Docker =============== -Sample Docker build files to provide an installation of Oracle GoldenGate for DevOps users. For more information about Oracle GoldenGate please see the [Oracle GoldenGate 12c On-line Documentation](https://docs.oracle.com/goldengate/c1230/gg-winux/index.html). - -**IMPORTANT:** To create images for Oracle GoldenGate on Docker, you must use Docker version 17.05.0 or later. You can check the version of Docker on your system with the `docker version` command. - -## Usage +Sample Docker build files to provide an installation of Oracle GoldenGate for DevOps users. + +## Contents + +* [Before You Start](#before-you-start) +* [Option 1 - Using `dockerBuild.sh` to Build Oracle GoldenGate Docker Images](#option-1---using-dockerbuildsh-to-build-oracle-goldengate-docker-images) + * [Docker Build Options](#docker-build-options) +* [Option 2 - Manually Building Oracle GoldenGate Docker Images](#option-2---manually-building-oracle-goldengate-docker-images) + * [Extracting *Oracle GoldenGate for Oracle* Installation Media](#extracting-oracle-goldengate-for-oracle-installation-media) + * [Extracting *Oracle GoldenGate* Installation Media for non-Oracle Databases](#extracting-oracle-goldengate-installation-media-for-non-oracle-databases) + * [Building the Docker image](#building-the-docker-image) +* [Changing the Base Image](#changing-the-base-image) +* [Running a Command from the Base Image](#running-a-command-from-the-base-image) +* [Running Oracle GoldenGate in a Docker container](#running-oracle-goldengate-in-a-docker-container) + * [SSL Certificate for Microservices Architecture](#ssl-certificate-for-microservices-architecture) + * [Administrative Account Password for Microservices Architecture](#administrative-account-password-for-microservices-architecture) + * [Running GGSCI in an OGG Standard Edition Docker container](#running-ggsci-in-an-ogg-standard-edition-docker-container) + * [Running Admin Client in an OGG Microservices Architecture Docker container](#running-admin-client-in-an-ogg-microservices-architecture-docker-container) +* [Known issues](#known-issues) +* [License](#license) +* [Copyright](#copyright) + +## Before You Start This project provides a Dockerfile tested with: - Oracle GoldenGate 12.2.0.1.1 for Oracle @@ -13,9 +31,13 @@ This project provides a Dockerfile tested with: To build the images, use the [dockerBuild.sh](dockerBuild.sh) script or follow the instructions for manually building an image. +**IMPORTANT:** To create images for Oracle GoldenGate on Docker, you must use Docker version 17.05.0 or later. You can check the version of Docker on your system with the `docker version` command. + **IMPORTANT:** You must download the installation binaries of Oracle GoldenGate. You only need to provide the binaries for the version you plan to install. The binaries can be downloaded from the [Oracle Technology Network](http://www.oracle.com/technetwork/middleware/goldengate/downloads/index.html). Do not uncompress the Oracle GoldenGate ZIP file. The `dockerBuild.sh` script will handle that for you. You also must have Internet connectivity when building the Docker image for the package manager to perform additional software installations. -### Option 1 - Using `dockerBuild.sh` to Build Oracle GoldenGate Docker Images +For more information about Oracle GoldenGate please see the [Oracle GoldenGate 12c On-line Documentation](https://docs.oracle.com/goldengate/c1230/gg-winux/index.html). + +## Option 1 - Using `dockerBuild.sh` to Build Oracle GoldenGate Docker Images Once you have downloaded the Oracle GoldenGate software, run the `dockerBuild.sh` script without command line options to view usage instructions: $ ./dockerBuild.sh @@ -39,19 +61,19 @@ The `dockerBuild.sh` script determines the version and edition of Oracle GoldenG **IMPORTANT:** When creating Docker images for *Oracle GoldenGate for Oracle*, the `dockerBuild.sh` script automatically selects the Oracle GoldenGate software for Oracle RDBMS 12c. To create Docker images for a different version of Oracle RDBMS, follow the instructions for **Option 2**. -#### Docker Build Options +### Docker Build Options When using `dockerBuild.sh`, all command line options after the name of the Oracle GoldenGate ZIP file are passed directly to the `docker build` command. This allows you to modify the behavior of `docker build`. For example, adding `--no-cache` to the `dockerBuild.sh` command line instructs Docker to not use cached images when building the Oracle GoldenGate Docker image. The `--tag` option can be used to give the new Docker image a custom tag. The following example creates a Oracle GoldenGate Docker image and names it `devops/goldengate-microservices:production`. Output from `docker build` is not shown unless an error occurs. $ ./dockerBuild.sh ~/Downloads/123010_fbo_ggs_Linux_x64_services_shiphome.zip --tag devops/goldengate-microservices:production --quiet -### Option 2 - Manually Building Oracle GoldenGate Docker Images +## Option 2 - Manually Building Oracle GoldenGate Docker Images Building an Oracle GoldenGate Docker image can be done manually, without using the **`dockerBuild.sh`** script, by following the steps in this section. First, the installation media must be extracted from the downloaded ZIP file and converted to a TAR file for the Docker build process. The extraction process depends on the version of Oracle GoldenGate downloaded. -#### Extracting *Oracle GoldenGate for Oracle* Installation Media +### Extracting *Oracle GoldenGate for Oracle* Installation Media The *Oracle GoldenGate for Oracle* software is packaged differently than for other databases. If *Oracle GoldenGate for Oracle* was downloaded, locate the appropriate `filegroup1.jar` file and extract it. For example, *Oracle GoldenGate 12.3.0.1.0 Microservices for Oracle* contains two candidates: $ unzip -l ~/Downloads/123010_fbo_ggs_Linux_x64_services_shiphome.zip | grep 'oracle.oggcore.*.ora.*filegroup1.jar' @@ -73,7 +95,7 @@ Then, conversion of `filegroup1.jar` to `123010_fbo_ggs_Linux_x64_services_shiph When the above commands are executed successfully, the resulting TAR file, `123010_fbo_ggs_Linux_x64_services_shiphome.tar`, will be used by the Dockerfile to create the Oracle GoldenGate image. Pass the filename to the Docker build command with the `OGG_TARFILE` build argument. This is covered in greater detail in a later section. -#### Extracting *Oracle GoldenGate* Installation Media for non-Oracle Databases +### Extracting *Oracle GoldenGate* Installation Media for non-Oracle Databases For non-Oracle databases, the installation software is packaged as a TAR file in a ZIP file, along with release notes. $ unzip -lv ~/Downloads/123011_ggs_Linux_x64_MySQL_64bit.zip @@ -103,7 +125,7 @@ Optionally, rebuild the TAR file using the group and user identifiers 54321:5432 When the above commands are executed successfully, the resulting TAR file, `ggs_Linux_x64_MySQL_64bit.tar`, can be used by the Dockerfile to create the Oracle GoldenGate image. Pass the filename to the Docker build command with the `OGG_TARFILE` build argument. This is described in the next section. -#### Building the Docker image +### Building the Docker image Once the TAR file is created, the Docker image can be built. The Dockerfile requires three build arguments be defined for the `docker build` command. - `OGG_VERSION` - The Oracle GoldenGate version used for the Docker image. "12.3.0.1.0", for example. This value is used to set the `OGG_VERSION` environment variable in the resulting Docker image and is otherwise not used. @@ -117,7 +139,7 @@ An Oracle GoldenGate Docker image is built with a `docker build` command like th --build-arg OGG_TARFILE="123010_fbo_ggs_Linux_x64_services_shiphome.tar" \ --tag oracle/goldengate-microservices:12.3.0.1.0 --no-cache . -### Changing the Base Image +## Changing the Base Image By default, the base image used by Docker to build Oracle GoldenGate Docker images is `oracle/instantclient:12.2.0.1`. The Oracle Instant Client image can be built using the files in [OracleInstantClient](../OracleInstantClient). You can change the base image used by the Oracle GoldenGate Docker images if your Oracle GoldenGate software is for a non-Oracle RDBMS or if you have more complex requirements of the Oracle GoldenGate Docker image. The base image is changed by setting the environment variable `BASE_IMAGE` when executing the `dockerBuild.sh` script as described in **Option 1** above. This example uses an Oracle Database 12c Release 2 (12.2.0.1) Enterprise Edition image created using the files in [OracleDatabase](../OracleDatabase): @@ -132,12 +154,12 @@ When manually creating the Docker image (see **Option 2**), the base image is sp --build-arg OGG_TARFILE="123010_fbo_ggs_Linux_x64_services_shiphome.tar" \ --tag oracle/goldengate-microservices:12.3.0.1.0 --no-cache . -### Running a Command from the Base Image +## Running a Command from the Base Image If the base image provides run-time services, they can be specified at Docker image build time with the `BASE_COMMAND` argument. They can also be specified at run time with the `BASE_COMMAND` environment variable. The command specified by `BASE_COMMAND` will be executed in the background, before the Oracle GoldenGate services are run. For example, when the Oracle GoldenGate Docker image is based on `oracle/database:12.2.0.1-ee`, the RDBMS services can be specified with this command: $ BASE_IMAGE="oracle/database:12.2.0.1-ee" ./dockerBuild.sh ~/Downloads/123010_fbo_ggs_Linux_x64_services_shiphome.zip --build-arg BASE_COMMAND="runuser -u oracle -- /opt/oracle/runOracle.sh" -### Running Oracle GoldenGate in a Docker container +## Running Oracle GoldenGate in a Docker container To run your Oracle GoldenGate Docker image use a **docker run** command like this: $ docker run --name \ @@ -169,7 +191,7 @@ For the Microservices Architecture, Oracle GoldenGate data is located under the - `/u02/ogg/Local/etc/conf` - Configuration files for the 'Local' deployment - `/u02/ogg/Local/var/lib/data` - Trail files for the 'Local' deployment -#### SSL Certificate for Microservices Architecture +### SSL Certificate for Microservices Architecture When the Oracle GoldenGate Docker image is created for Microservices Architecture, a dummy SSL certificate is generated for the OGG Web UI. Your own SSL certificate can be used instead of the dummy certificate like this: docker run --name ogg-test \ @@ -202,7 +224,7 @@ The certificate file, `/path/to/certificate.pem`, needs to contain a full certif KOqkqm57TH2H3eDJAkSnh6/DNFu0Qg== -----END CERTIFICATE----- -#### Administrative Account Password for Microservices Architecture +### Administrative Account Password for Microservices Architecture On the first startup of a Microservices Architecture container, a random password will be generated for the Oracle GoldenGate administrative user if not provided by the `OGG_ADMIN_PWD` environment variable. You can find this password at the start of the Docker container log: $ docker logs 2>/dev/null | head -3 @@ -210,14 +232,14 @@ On the first startup of a Microservices Architecture container, a random passwor -- Password for administrative user 'oggadmin' is 'qVc3bqNlwijk' ---------------------------------------------------------------------------------- -#### Running GGSCI in an OGG Standard Edition Docker container +### Running GGSCI in an OGG Standard Edition Docker container The **GGSCI** utility can be run in the OGG container with this command: $ docker exec -ti --user oracle ggsci **GGSCI** is not installed for containers created with the Microservices Architecture. -#### Running Admin Client in an OGG Microservices Architecture Docker container +### Running Admin Client in an OGG Microservices Architecture Docker container The **Admin Client** utility can be run in the OGG container with this command: $ docker exec -ti --user oracle adminclient