

 Copyright (c) 2020, 2021, Oracle and/or its affiliates. 

   NAME
     README - Oracle SQL Access to Kafka Distro Installer 

     Release 1.2 
  Contents
  ========
    Introduction 
    Supported Software Versions
    Installing Oracle SQL Access to Kafka Distro


  Introduction 
  ===========================
  Oracle SQL Access to Kafka enables an Oracle Database to read from Kafka 
  sources where the Oracle Database acts as a Kafka consumer.

  The ORA_KAFKA PL/SQL package provides procedures to register a Kafka cluster,
  load Kafka data into Oracle tables and create Oracle views on Kafka topics 
  and partitions.
 
  Supported Software Versions
  ===========================
  Oracle Database 12.2 or higher with compatible parameter >= 12.2.
  Apache Kafka 0.10.2.0 or higher.

  Distro Install Instructions
  ===========================
  1.1 Unzip the Oracle SQL Access to Kafka distribution into a directory on  
      the Database system. This directory will be referred to 
      as <orakafka_distro_home> 

      For example:
      $ unzip orakafka-<ver>.zip

      The distribution has the following structure
      $ ls -1 <orakafka_distro_home> 
        README
        kit_version.txt
        orakafka.zip
        orakafka_distro_install.sh
     
      NOTE: For RAC Databases
      This step must be repeated on all RAC nodes and
      <orakafka_distro_home> must be identical on all RAC nodes.


1.2   Run the installer script to lay down the kit binaries and create 
      app_data/ directories on the Oracle Database system

      The <orakafka_distro_home>/orakafka_distro_install.sh installs 
      Oracle SQL Access to Kafka distribution into <ora_kafka_home> directory on the 
      Oracle Database system.
      
      Usage: 
      ./orakafka_distro_install.sh -p <ora-kafka-home> [-a <app-data-home>] [-h]
      where options are:
      -p <ora-kafka-home> - absolute path of ora_kafka_home/ directory
                            where the product is to be installed
                            The ora_kafka_home/ directory is created if 
                            it does not exist.
                                 
                            By default
                             <ora_kafka_home>/orakafka contains kit binaries
                             and
                             <ora_kafka_home>/app_data contains data such as
                             cluster conf,scripts and logs
                                 
      -a <app-data-home>  - absolute path of app_data/ directory
                            default: <ora-kafka-home>/app_data
                                 
                            Specify this option to override the default location
                            of app_data/ directory. This is required for RAC
                            databases or to separate the app_data/ from the 
                            binaries if orakafka is installed in a Read Only 
                            Oracle Home.

                            For RAC databases, this must be a cluster 
                            filesystem path.
                                 
                            The app_data/ directory and subdirectories 
                            are created if they do not exist but are
                            never overwritten.

                            To reinstall the app_data/ directory in the 
                            same location, you must first manually move the 
                            app_data/ directory to a different location and 
                            then run this script again.

                            Note For RAC Databases:
                              The 'grid' user must also have read and execute 
                              permissions on the <ora-kafka-home>
                              and <app-data-home> directories.

                              To test, login as 'grid' user and execute
                              the following commands

                              $ cd <app-data-home>; ls -R 
                              This will show the directory listing of 
                              <app-data-home>.

                              $ cd <ora-kafka-home>; ls -R 
                              This will show the directory listing of 
                              <ora-kafka-home>.
                                 
      -h                  - Display usage

      To get usage information run orakafka_distro_install.sh
      without parameters or with -h
      Example:
          cd <ora_kafka_distro_home>; ./orakafka_distro_install.sh 
          cd <ora_kafka_distro_home>; ./orakafka_distro_install.sh -h


      Examples:   
      
       A) Simple Install 
          To install kit binaries and app_data/ under ora_kafka_home/
          run the following commands

          cd <ora_kafka_distro_home> 
          ./orakafka_distro_install.sh -p  /opt/oracle/ora_kafka_home 
        
          The installer creates the following files/directories in
          in the specified path.

          ls -1 /opt/oracle/ora_kafka_home 
             app_data/
             configure_app_data_home.sh
             orakafka/
               
       

       B) Custom Install (for example, a Read Only Oracle Home)
          To install kit binaries and app_data/ in different directories,
          run the following commands

          cd <ora_kafka_distro_home> 
          ./orakafka_distro_install.sh -p  /opt/oracle/ora_kafka_home -a /u01/orakafka/app_data 

          The installer creates the following files/directories in
          the specified paths.

          ls -1 /opt/oracle/ora_kafka_home
             configure_app_data_home.sh
             orakafka/

          ls -1 /opt/oracle/app_data
            clusters/
            logs/
            scratch/
            scripts/



      C) RAC Database Install 
         Run the following commands on every RAC node to install the kit 
         in the specified paths
       
         cd <ora_kafka_distro_home> 
         ./orakafka_distro_install.sh -p  /opt/oracle/ora_kafka_home -a  /<cluster_fs_dir>/app_data 

         where  
          <cluster_fs_dir> -  absolute path on the cluster filesystem
                              The app_data/ directory is created once
                              if it does not exist.

          The installer creates the following files/directories in
          the specified paths.

          ls -1 /opt/oracle/ora_kafka_home
             configure_app_data_home.sh
             orakafka/

          ls -1 /<cluster_fs_dir>/app_data
            clusters/
            logs/
            scratch/
            scripts/


          
  1.3  Product configuration and release information 

       Run <ora_kafka_home>/orakafka/bin/orakafka.sh to configure 
       Oracle SQL Access to Kafka.

       See ora_kafka_home/README for release information. 

       See doc/README_INSTALL for product configuration instructions.

