Oracle GoldenGate (oracle#608)

- Add Contents section to README

Signed-off-by: Stephen Balousek <[email protected]>

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 <container 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,22 +224,22 @@ 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 <container name> 2>/dev/null | head -3
     ----------------------------------------------------------------------------------
     --  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 <container name> 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 <container name> adminclient