HADOOP-1835 Updated Documentation for HBase setup/installation

M    hbase/conf/hbase-env.sh
    Removed JAVA_HOME references.
M    hbase/src/java/org/apache/hadoop/hbase/package.html
    Improved setup instruction


git-svn-id: https://svn.apache.org/repos/asf/lucene/hadoop/trunk/src/contrib/hbase@572983 13f79535-47bb-0310-9956-ffa450edef68

CHANGES.txt

@@ -40,6 +40,8 @@ Trunk (unreleased changes)
     HADOOP-1760 Use new MapWritable and SortedMapWritable classes from
                 org.apache.hadoop.io
     HADOOP-1802 Startup scripts should wait until hdfs as cleared 'safe mode'
+    HADOOP-1835 Updated Documentation for HBase setup/installation
+           (Izaak Rubin via Stack)
 
 
 Below are the list of changes before 2007-08-18

conf/hbase-env.sh

@@ -21,14 +21,6 @@
 
 # Set HBase-specific environment variables here.
 
-# The only required environment variable is JAVA_HOME.  All others are
-# optional.  When running a distributed configuration it is best to
-# set JAVA_HOME in this file, so that it is correctly defined on
-# remote nodes.
-
-# The java implementation to use.  Required.
-# export JAVA_HOME=/usr/lib/j2sdk1.5-sun
-
 # Extra Java CLASSPATH elements.  Optional.
 # export HBASE_CLASSPATH=
 
@@ -38,5 +30,5 @@
 # Extra Java runtime options.  Empty by default.
 # export HBASE_OPTS=-server
 
-# File naming remote slave hosts.  $HADOOP_HOME/conf/slaves by default.
+# File naming hosts on which HRegionServers will run.  $HBASE_HOME/conf/regionservers by default.
 # export HBASE_REGIONSERVERS=${HBASE_HOME}/conf/regionservers

src/java/org/apache/hadoop/hbase/package.html

@@ -7,46 +7,104 @@ simple database.
 
 <h2>Requirements</h2>
 <ul>
-<li><a href="http://lucene.apache.org/hadoop">Hadoop</a>:  Hadoop has its own set of
+<li>Java 1.5.x, preferably from <a href="http://www.java.com/en/download/">Sun</a>.</li>
-<a href="http://lucene.apache.org/hadoop/api/overview-summary.html">requirements</a>
+<li>HBase runs on top of <a href="http://lucene.apache.org/hadoop">Hadoop</a>.  Hadoop has its own set of
-(Scroll down the page).</li>
+<a href="http://lucene.apache.org/hadoop/api/overview-summary.html#overview_description">
-<li>Java 1.5.x, preferably from <a href="http://lucene.apache.org/hadoop/api/index.html">Sun</a>
+requirements and instructions</a>.  Make sure to set 
-Set <code>JAVA_HOME</code> to the root of your Java installation</li>
+<code>JAVA_HOME</code> to the root of your Java installation when configuring Hadoop.
+</li>
 </ul>
 
 <h2>Getting Started</h2>
-<p>First, you need a working instance of Hadoop.  Download a recent release from
+<p>
-<a href="http://www.apache.org/dyn/closer.cgi/lucene/hadoop/">Hadoop downloads</a>. 
+Start by defining the following directory variables for your convenience:
-Unpack the release and connect to its top-level directory.  Let this be
-<code>${HADOOP_HOME}</code>.  Edit the file <code>${HADOOP_HOME}/conf/hadoop-env.sh</code>
-to define at least <code>JAVA_HOME</code>.  Also, add site-particular
-customizations to the file <code>${HADOOP_HOME}/conf/hadoop-site.xml</code>.
-Try the following command: <pre>bin/hadoop
-</pre>
 </p>
-<p>Next, change to the hbase root.  Let this be <code>${HBASE_HOME}</code>  It is
+<ul>
-usually located at <code>${HADOOP_HOME}/src/contrib/hbase</code>.  Configure hbase.
+<li><code>${HADOOP_HOME}</code>: The root directory of your Hadoop installation.</li>
-Edit <code>${HBASE_HOME}/conf/hbase-env.sh</code> and 
+<li><code>${HBASE_HOME}</code>: The HBase root, located at 
-<code>${HBASE_HOME}/conf/hbase-site.xml</code> to make site particular settings.
+<code>${HADOOP_HOME}/src/contrib/hbase</code>.</li>
-List the hosts running regionservers in <code>${HBASE_HOME}/conf/regionservers</code>.
+</ul>
+<p>
+If you are running a standalone operation, proceed to <a href=#runandconfirm>Running 
+and Confirming Your Installation</a>.  If you are running a distributed operation, continue below.
+</p>
+
+<h2>Distributed Operation</h2>
+<p>
+Make sure you have followed
+<a href="http://lucene.apache.org/hadoop/api/overview-summary.html#overview_description">
+Hadoop's instructions</a> for running a distributed operation.  
+Configuring HBase for a distributed operation requires modification of the following two 
+files: <code>${HBASE_HOME}/conf/hbase-site.xml</code> and 
+<code>${HBASE_HOME}/conf/regionservers</code>.  
 </p>
 <p>
-Here is how to start and then stop hbase:
+<code>hbase-site.xml</code> allows the user to override the properties defined in 
-<pre>${HBASE_HOME}/bin/start-hbase.sh
+<code>${HBASE_HOME}/conf/hbase-default.xml</code>.  <code>hbase-default.xml</code> itself 
+should never be modified.  At a minimum the <code>hbase.master</code> property should be redefined 
+in <code>hbase-site.xml</code> to define the <code>host:port</code> pair on which to run the 
+HMaster (<a href="http://wiki.apache.org/lucene-hadoop/Hbase/HbaseArchitecture">read about the 
+HBase master, regionservers, etc</a>):
+</p>
+<pre>
+&lt;configuration&gt;
+
+  &lt;property&gt;
+    &lt;name&gt;hbase.master&lt;/name&gt;
+    &lt;value&gt;[YOUR_HOST]:[PORT]&lt;/value&gt;
+    &lt;description&gt;The host and port that the HBase master runs at.
+    &lt;/description&gt;
+  &lt;/property&gt;
+
+&lt;/configuration&gt;
+</pre>
+<p>
+The <code>regionserver</code> file lists all the hosts running HRegionServers, one 
+host per line  (This file is synonymous to the slaves file at 
+<code>${HADOOP_HOME}/conf/slaves</code>).
+</p>
+<h3>Additional Notes on Distributed Operation</h3>
+<ul>
+<li>Hadoop and HBase must be set up on each host you plan to use.</li>
+<li>Additional (optional) HBase-specific variables such as HBASE_HEAPSIZE and HBASE_CLASSPATH 
+can be set in <code>${HBASE_HOME}/conf/hbase-env.sh</code>.</li>
+</ul>
+
+<h2><a name="runandconfirm"/>Running and Confirming Your Installation</h2>
+<p>
+If you are running a distributed operation you will need to start the Hadoop daemons 
+before starting HBase and stop the daemons after HBase has shut down.  Start and 
+stop the Hadoop daemons as per the Hadoop 
+<a href="http://lucene.apache.org/hadoop/api/overview-summary.html">instructions</a>.  Afterwards, 
+or if running a standalone operation, start HBase with the following command:
+</p>
+<pre>
+${HBASE_HOME}/bin/start-hbase.sh
+</pre>
+<p>
+Once HBase has started, enter <code>${HBASE_HOME}/bin/hbase shell</code> to obtain a 
+shell against HBase from which you can execute HBase commands.  In the HBase shell, type 
+<code>help;</code> to see a list of supported commands.  Note that all commands in the HBase 
+shell must end with <code>;</code>.  Test your installation by creating, viewing, and dropping 
+a table, as per the help instructions.  Be patient with the <code>create</code> and 
+<code>drop</code> operations as they may each take 30 seconds or more.  To stop hbase, exit the 
+HBase shell and enter:
+</p>
+<pre>
 ${HBASE_HOME}/bin/stop-hbase.sh
 </pre>
-Logs can be found in ${HADOOP_LOG_DIR}.
+<p>
+If you are running a distributed operation, be sure to wait until HBase has shut down completely 
+before stopping the Hadoop daemons.
 </p>
-<p>To obtain a shell against a running hbase instance, run:
+<p>
-<pre>${HBASE_HOME}/bin/hbase shell</pre>
+The default location for logs is <code>${HADOOP_HOME}/logs</code>.
-Once the shell is up, type <code>help;</code> to see list of supported commands.
 </p>
 
 <h2>Related Documentation</h2>
-
 <ul>
   <li><a href="http://wiki.apache.org/lucene-hadoop/Hbase">HBase Home Page</a>
-  <li><a href="http://wiki.apache.org/lucene-hadoop/Hbase/HbaseArchitecture">Hbase Architecture</a>
+  <li><a href="http://wiki.apache.org/lucene-hadoop/Hbase/HbaseArchitecture">HBase Architecture</a>
 </ul>
 
 </body>