meshIQ Kafka Console Implementation: readme.txt
================================================================================================================
Follow below steps to get started with the meshIQ Kafka Console setup.

NOTE: Before running this procedure, please verify: 
------------------------------------------------------------------------------------------------------------------------------------------
Prerequisites:
 Linux System:
-	Operating System:  Linux 64 bit OS
-	CPU:  Minimum 4 virtual CPUs
-	Memory:  Minimum 8GB RAM 
-	File System:  Minimum 1 GB free space
-	Recommended: Install folder /opt
-	Recommended: Dedicated Server Instance
	
	NETWORK:
		Node Exporter: PORT=9100(TCP)
		JMX Java Agent: PORT=9404(TCP)
		zookeeper jmx: PORT=7000(TCP)
		Web HTTP Server: PORT=8080(TCP)

==========================================================================================================================================
The machine on which the install will be done respects all prerequisites for installation described above.
For more information and the web version of same instructions below please visit this link:
	https://customers.meshiq.com/hc/en-us/categories/30093024041363 

MKC SETUP STEPS:
	These steps assume local installation for all related components.
ON CLIENT MKC SERVER SIDE:
NOTE: Please make sure to install meshiq Kafka Conslole (MKC) on a separate server, not on the same server as your kafka installation. 
      MKC uses its own Kafka installation for internal services.

	1.  Untar/unzip the mkc_v2.7.2_dpack_v3.2.tar.Z package to the installation path of your choice ... 
		This package contains the directory "mkc" as a root directory.
			
			SHELL COMMAND: tar -zxvf mkc_v2.7.2_dpack_v4.0.tar.Z

	2.  TO START THE MKC SERVICES, AND FOR INITIAL SETUP:
		Run below command from "your_installation_path/sbin/" directory and follow on screen instructions.
			
			SHELL COMMAND: cd sbin
			SHELL COMMAND: ./start.sh all
			Press "enter" key to set the install path automatically. 

		Note: First time command run will ask you to specify untared/unzipped directory location, after which you will need to re-run command ./start.sh all.
		
	3. CONNECT MKC TO YOUR EXISTING KAFKA INSTALLATION:	
		Access the MKC UI from a web browser, use the following address: 
		http://<mkc_server_ip>:8080
		
		NOTE: IF YOU TRY TO GET TO THE WEB UI IMMEDIATELY AFTER ALL OF THE PROCESS HAVE BEEN SUCCESSFULLY STARTED, 
			  IT IS EXPECTED TO SEE AN 'OWL' ON THE WEB UI, IT WILL MAY TAKE UP-TO 30 SEC FOR THE LOGIN SCREEN TO APPEAR.
		
		User Name: user1 (case sensitive)
		Password: pass (case sensitive)
		
		Once logged in, select either explore Kafka or 'Kafka link' from Quick Access menu then register Kafka and connect to your existing installation.
		follow instructions on the screen and to enable Enable JMX and Node statistics, click "Metrics Settings" and select "Use JMX and NODE metric"
		
		NOTE: Ensure below steps for "KAKFA SERVER SIDE" have been completed in order for JMX and NODE Metrics to work.
		
------------------------------------------------------------------------------------------------------------------------------
NOTE: To connect MKC to Kafka statistics you would need to run MKC Kafka components on Kafka and zookeeper servers.

ON KAFKA SERVER SIDE:
	1. On each Kafka Server:
		Untar/unzip the mkc_ServerComponents_dpack_v1.0.tar.Z package to the installation path of your choice ... 
		This package contains the directory "mkc" as a root directory.
		
		SHELL COMMAND: tar -zxvf mkc_ServerComponents_dpack_v1.0.tar.Z
	
	2. ON Kafka server to enable MKC to get the kafka metrics.
		set KAFKA_OPT environment variable.
		EX: 
		export KAFKA_OPTS="-javaagent:/opt/mkc/jmx_agent/jmx_prometheus_javaagent-0.20.0.jar=9404:/opt/mkc/jmx_agent/metric_rules.yml"
		
		NOTE: If "/opt" is not your install path then replace /opt in above string with your installation path in both locations.
	
		-Restart kafka server.
		NOTE: jmx agent listens on 9404 port.
	
	3. Start Node Exporter:
		Run below command from "your_installation_path/sbin" directory and follow on screen instructions.
		SHELL COMMAND: ./start.sh all
		Press "enter" key to set the install path automatically. 
		NOTE: node exporter listens on 9100 port.
		
------------------------------------------------------------------------------------------------------------------------------
NOTE: FOLLOW ZOOKEEPER STEPS BELOW ONLY WHEN YOUR KAFKA IS CONFIGURED TO USE ZOOKEEPER.

ON ZOOKEEPER SERVER SIDE: 
 (If you kafka is set to use kraft instead of zookeeper then skip these 3 setup steps below.)
 
	1. On each zookeeper Server:
		Untar/unzip the mkc_ServerComponents_dpack_v1.0.tar.Z package to the installation path of your choice ... 
		This package contains the directory "mkc" as a root directory.
		
		SHELL COMMAND: tar -zxvf mkc_ServerComponents_dpack_v1.0.tar.Z
		
	2. Ensure zookeeper jmx is enabled.
		edit: YOUR_ZOOKEEPER_INSTALL_PATH/config/zoo.cfg and verify below variables are set.
		
		metricsProvider.className=org.apache.zookeeper.metrics.prometheus.PrometheusMetricsProvider
		metricsProvider.httpPort=7000
		metricsProvider.exportJvmInfo=true
		
	3. Start Node Exporter.
		Run below command from "your_installation_path/sbin" directory and follow on screen instructions.
		SHELL COMMAND: ./start.sh all
		Press "enter" key to set the install path automatically. 

------------------------------------------------------------------------------------------------------------------------------
Firewall ports consideration for MKC connections.
	Ensure java jmx agent 9404 port is open from mkc to kafka.
	Ensure node exporter 9100 port is open from mkc to kafka.
	
	On zookeeper node:
	Ensure zookeeper jmx port 7000 is open for communication going from mkc to zookeeper.

YOU HAVE COMPLETED MKC IMPLEMENTATION.

==========================================================================================================================================
ADDITIONAL INFORMATION:
Files in sbin folder:
Note: By running start.sh and stop.sh without any options will produce the usage with all available options.
	
	start.sh all   (to start all mkc processes)
	stop.sh all    (to stop all mkc processes)
	show.sh        (to get status of all mkc processes)
	cleanup.sh     (will clean all log files and produce a backup of all the logs)
	mkin_env.sh    (file contains all necessary environment variable to run mkc)

==========================================================================================================================================

 	OPTIONAL: To run startup scripts from anywhere, it is recommended to set MKIN_HOME and PATH environmental verifiables to mkc/sbin directory in user profile.
	copy and paste these two lines towards the end of the user profile file.
    	
	export MKIN_HOME=/opt/mkc
	export PATH=$PATH:$MKIN_HOME/sbin
	
	change /opt/mkc to the path of root directory of mkc installation.
    
    ----------------------------------------------------------------------
    OPTIONAL: To set working path manually, Edit MKIN_HOME/sbin/mkin_env.sh 
    Change line: export MKIN_HOME=ExistingPath and replace it with NewPath.

==========================================================================================================================================