|
| 1 | +# Oracle GoldenGate 23 Microservices Edition Container Images |
| 2 | + |
| 3 | +Sample container image build files to provide an installation of Oracle GoldenGate for DevOps users. |
| 4 | +These instructions apply to building container images for Oracle GoldenGate version 23. |
| 5 | + |
| 6 | +## Contents |
| 7 | + |
| 8 | +- [Oracle GoldenGate 23 Microservices Edition Container Images](#oracle-goldengate-23-microservices-edition-container-images) |
| 9 | + - [Contents](#contents) |
| 10 | + - [Before You Start](#before-you-start) |
| 11 | + - [Build an Oracle GoldenGate Container Image](#build-an-oracle-goldengate-container-image) |
| 12 | + - [Changing the Base Image](#changing-the-base-image) |
| 13 | + - [Running Oracle GoldenGate in a Container](#running-oracle-goldengate-in-a-container) |
| 14 | + - [Administrative Account Password](#administrative-account-password) |
| 15 | + - [SSL Certificate](#ssl-certificate) |
| 16 | + - [Running the Administration Client](#running-the-administration-client) |
| 17 | + - [Running Scripts Before Setup and on Startup](#running-scripts-before-setup-and-on-startup) |
| 18 | + - [Known Issues](#known-issues) |
| 19 | + - [License](#license) |
| 20 | + - [Copyright](#copyright) |
| 21 | + |
| 22 | +## Before You Start |
| 23 | + |
| 24 | +This project was tested with: |
| 25 | + |
| 26 | +- Oracle GoldenGate 23.4 Microservices for Oracle on Linux x86-64 |
| 27 | + |
| 28 | +**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 decompress the Oracle GoldenGate ZIP file. The container build process will handle that |
| 29 | +for you. You also must have Internet connectivity when building the container image for the package manager to perform additional software installations. |
| 30 | + |
| 31 | +All shell commands in this document assume the usage of Bash shell. |
| 32 | + |
| 33 | +For more information about Oracle GoldenGate please see the [Oracle GoldenGate 23 On-line Documentation](https://docs.oracle.com/en/middleware/goldengate/core/23/index.html). |
| 34 | + |
| 35 | +## Build an Oracle GoldenGate Container Image |
| 36 | + |
| 37 | +Once you have downloaded the Oracle GoldenGate software, a container image can be created using container management command-line applications. |
| 38 | +A single `--build-arg` is needed to indicate the GoldenGate installer that was downloaded. |
| 39 | + |
| 40 | +To create a container image for GoldenGate for Oracle Database, use the following script: |
| 41 | + |
| 42 | +```sh |
| 43 | +$ docker build --tag=oracle/goldengate:23.4 \ |
| 44 | + --build-arg INSTALLER=234000_fbo_ggs_Linux_x64_Oracle_services_shiphome.zip . |
| 45 | +Sending build context to Docker daemon |
| 46 | +... |
| 47 | +Successfully tagged oracle/goldengate:23.4 |
| 48 | +``` |
| 49 | + |
| 50 | +Similarly, for other Databases like BigData, MySQL, PostgreSQL, etc. provide the name of the zip file for the INSTALLER argument. |
| 51 | + |
| 52 | +### Changing the Base Image |
| 53 | + |
| 54 | +By default, the base container image used to create the Oracle GoldenGate container image is `oraclelinux:8`. This can be changed using the `BUILD_IMAGE` build argument. For example: |
| 55 | + |
| 56 | +```sh |
| 57 | +docker build --tag=oracle/goldengate:23.4 \ |
| 58 | + --build-arg BASE_IMAGE="localregistry/oraclelinux:8" \ |
| 59 | + --build-arg INSTALLER=234000_fbo_ggs_Linux_x64_Oracle_services_shiphome.zip . |
| 60 | +``` |
| 61 | + |
| 62 | +Oracle GoldenGate 23 requires a base container image with Oracle Linux 8 or later. |
| 63 | + |
| 64 | +## Running Oracle GoldenGate in a Container |
| 65 | + |
| 66 | +Use the `docker run` command to create and start a container from the Oracle GoldenGate container image. |
| 67 | + |
| 68 | +```sh |
| 69 | +docker run \ |
| 70 | + --name <container name> \ |
| 71 | + -p <host port>:443 \ |
| 72 | + -e OGG_ADMIN=<admin user name> \ |
| 73 | + -e OGG_ADMIN_PWD=<admin password> \ |
| 74 | + -e OGG_DEPLOYMENT=<deployment name> \ |
| 75 | + -v [<host mount point>:]/u01/ogg/scripts \ |
| 76 | + -v [<host mount point>:]/u02 \ |
| 77 | + -v [<host mount point>:]/u03 \ |
| 78 | + -v [<host mount point>:]/etc/nginx/cert \ |
| 79 | + oracle/goldengate:23.4 |
| 80 | +``` |
| 81 | + |
| 82 | +Parameters: |
| 83 | + |
| 84 | +- `<container name>` - A name for the new container (default: auto-generated) |
| 85 | +- `-p <host-port>` - The host port to map to the Oracle GoldenGate HTTPS server (default: no mapping) |
| 86 | +- `-e OGG_ADMIN` - The name of the administrative account to create (default: `oggadmin`) |
| 87 | +- `-e OGG_ADMIN_PWD` - The password for the administrative account (default: auto-generated) |
| 88 | +- `-e OGG_DEPLOYMENT` - The name of the deployment (default: `Local`) |
| 89 | +- `-v /u01/ogg/scripts`- The volume used for executing setup (`${OGG_HOME}/scripts/setup`) and startup (`${OGG_HOME}/scripts/startup`) user scripts (default: none) |
| 90 | +- `-v /u02` - The volume used for persistent GoldenGate data (default: use container storage) |
| 91 | +- `-v /u03` - The volume used for temporary GoldenGate data (default: use container storage) |
| 92 | +- `-v /etc/nginx/cert` - The volume used for storing the SSL certificate for the HTTPS server (default: create a self-signed certificate) |
| 93 | + |
| 94 | +All parameters are optional, so the following command will work, too: |
| 95 | + |
| 96 | +```sh |
| 97 | +$ docker run oracle/goldengate:23.4 |
| 98 | +---------------------------------------------------------------------------------- |
| 99 | +-- Password for OGG administrative user 'oggadmin' is 'XU2k7cMastmt-DJKs' |
| 100 | +---------------------------------------------------------------------------------- |
| 101 | +... |
| 102 | +``` |
| 103 | + |
| 104 | +See the following sections for additional details. |
| 105 | + |
| 106 | +### Administrative Account Password |
| 107 | + |
| 108 | +On the first startup of the 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 container log: |
| 109 | + |
| 110 | +```sh |
| 111 | +$ docker logs <container name> | head -3 |
| 112 | +---------------------------------------------------------------------------------- |
| 113 | +-- Password for OGG administrative user 'oggadmin' is 'ujX7sqQ430G9-xSlr' |
| 114 | +---------------------------------------------------------------------------------- |
| 115 | +``` |
| 116 | + |
| 117 | +### SSL Certificate |
| 118 | + |
| 119 | +When bringing your own SSL certificate to an Oracle GoldenGate container, two files are needed: |
| 120 | + |
| 121 | +1. `ogg.key` - The private key for the SSL certificate. |
| 122 | +1. `ogg.pem` - The SSL leaf certificate, and a full certificate trust chain |
| 123 | + |
| 124 | +If these files are located in a directory called `cert`, they can be used in the GoldenGate container with a volume mount as shown here: |
| 125 | + |
| 126 | +```sh |
| 127 | +$ docker run -v ${PWD}/cert:/etc/nginx/cert:ro -p 8443:443 oracle/goldengate:23.4 |
| 128 | +... |
| 129 | +``` |
| 130 | + |
| 131 | +The certificate file, `ogg.pem`, must contain a full certificate chain starting with the leaf certificate, and followed by all other certificates in the Certificate Authority chain. |
| 132 | + |
| 133 | +```pem |
| 134 | +-----BEGIN CERTIFICATE----- |
| 135 | +MIIFBTCCA+2gAwIBAgISBJSzNXE+Ha5eDw76N5lgHhTpMA0GCSqGSIb3DQEBCwUA |
| 136 | +MEoxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MSMwIQYDVQQD |
| 137 | +... |
| 138 | +dr7wTE+AQwcOLAGjIvFOL7GK8JrhKvuFvnSoys/1O2CK3vVhBgS+mEF6D+QjIGTv |
| 139 | +VC01LCPT51q58INy4RtDBPSqlJwrzz+pOOWd5rBWhu2UPktVHz3AtYE= |
| 140 | +-----END CERTIFICATE----- |
| 141 | +-----BEGIN CERTIFICATE----- |
| 142 | +MIIEkjCCA3qgAwIBAgIQCgFBQgAAAVOFc2oLheynCDANBgkqhkiG9w0BAQsFADA/ |
| 143 | +MSQwIgYDVQQKExtEaWdpdGFsIFNpZ25hdHVyZSBUcnVzdCBDby4xFzAVBgNVBAMT |
| 144 | +... |
| 145 | +PfZ+G6Z6h7mjem0Y+iWlkYcV4PIWL1iwBi8saCbGS5jN2p8M+X+Q7UNKEkROb3N6 |
| 146 | +KOqkqm57TH2H3eDJAkSnh6/DNFu0Qg== |
| 147 | +-----END CERTIFICATE----- |
| 148 | +``` |
| 149 | + |
| 150 | +### Running the Administration Client |
| 151 | + |
| 152 | +The **Administration Client** utility can be run with this command: |
| 153 | + |
| 154 | +```sh |
| 155 | +$ docker exec -ti --user ogg <container name> adminclient |
| 156 | +Oracle GoldenGate Administration Client for Oracle |
| 157 | +Version 23.4 ... |
| 158 | +``` |
| 159 | + |
| 160 | +### Running Scripts Before Setup and on Startup |
| 161 | + |
| 162 | +The container images can be configured to run scripts before setup and on startup. Currently, `.sh` extensions are supported. For setup scripts just mount the volume `/u01/ogg/scripts/setup` or extend the image to include scripts in this directory. For startup scripts just mount the volume `/u01/ogg/scripts/startup` or extend the image to include scripts in this directory. Both of those locations |
| 163 | +are static and the content is controlled by the volume mount. |
| 164 | + |
| 165 | +The example below mounts the local directory `${PWD}/myScripts` to `/u01/ogg/scripts` which is then searched for custom startup scripts: |
| 166 | + |
| 167 | +```sh |
| 168 | +docker run -v "${PWD}/myScripts:/u01/ogg/scripts" oracle/goldengate:23.4 |
| 169 | +``` |
| 170 | + |
| 171 | +## Known Issues |
| 172 | + |
| 173 | +None |
| 174 | + |
| 175 | +## License |
| 176 | + |
| 177 | +All scripts and files hosted in this project and GitHub [docker-images/OracleGoldenGate](../) repository required to build the container images are, unless otherwise noted, released under the Universal Permissive License (UPL), Version 1.0. See [LICENSE](/LICENSE) for details. |
| 178 | + |
| 179 | +To download and run Oracle GoldenGate, regardless of whether inside or outside a container, you must download the binaries from the [Oracle Technology Network](http://www.oracle.com/technetwork/middleware/goldengate/downloads/index.html) and accept the license indicated on that page. |
| 180 | + |
| 181 | +## Copyright |
| 182 | + |
| 183 | +Copyright © 2022, 2024 Oracle and/or its affiliates. |
0 commit comments