src/main/docbkx/getting_started.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xml:id="getting_started"
         xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:svg="http://www.w3.org/2000/svg"
         xmlns:m="http://www.w3.org/1998/Math/MathML"
         xmlns:html="http://www.w3.org/1999/xhtml"
         xmlns:db="http://docbook.org/ns/docbook">
<!--
/**
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
-->
  <title>Getting Started</title>

  <section>
    <title>Introduction</title>

    <para><xref linkend="quickstart" /> will get you up and
    running on a single-node, standalone instance of HBase.
    </para>
  </section>

  <section xml:id="quickstart">
    <title>Quick Start</title>

    <para>This guide describes setup of a standalone HBase instance. It will
        run against the local filesystem.  In later sections we will take you through
        how to run HBase on Apache Hadoop's HDFS, a distributed filesystem.  This section
        shows you how to create a table in HBase, inserting
    rows into your new HBase table via the HBase <command>shell</command>, and then cleaning
    up and shutting down your standalone, local filesystem-based  HBase instance. The below exercise
    should take no more than ten minutes (not including download time).
    </para>
    <note xml:id="local.fs.durability"><title>Local Filesystem and Durability</title>
        <para>Using HBase with a LocalFileSystem does not currently guarantee durability.
        The HDFS local filesystem implementation will lose edits if files are not properly
        closed -- which is very likely to happen when experimenting with a new download.
            You need to run HBase on HDFS to ensure all writes are preserved.  Running
            against the local filesystem though will get you off the ground quickly and get you
            familiar with how the general system works so lets run with it for now. See
            <link xlink:href="https://issues.apache.org/jira/browse/HBASE-3696"/> and its associated issues for more details.</para></note>
    <note xml:id="loopback.ip.getting.started">
        <title>Loopback IP</title>
        <note>
        <para><emphasis>The below advice is for hbase-0.94.x and older versions only. We believe this fixed in hbase-0.96.0 and beyond
(let us know if we have it wrong).</emphasis>  There should be no need of the below modification to <filename>/etc/hosts</filename> in
later versions of HBase.</para>
       </note>
        <para>HBase expects the loopback IP address to be 127.0.0.1.  Ubuntu and some other distributions,
            for example, will default to 127.0.1.1 and this will cause problems for you
            <footnote><para>See <link xlink:href="http://blog.devving.com/why-does-hbase-care-about-etchosts/">Why does HBase care about /etc/hosts?</link> for detail.</para></footnote>.
        </para>
        <para><filename>/etc/hosts</filename> should look something like this:
<programlisting>
            127.0.0.1 localhost
            127.0.0.1 ubuntu.ubuntu-domain ubuntu
</programlisting>
        </para>
       </note>


    <section>
      <title>Download and unpack the latest stable release.</title>

      <para>Choose a download site from this list of <link
      xlink:href="http://www.apache.org/dyn/closer.cgi/hbase/">Apache Download
      Mirrors</link>. Click on the suggested top link. This will take you to a
      mirror of <emphasis>HBase Releases</emphasis>. Click on the folder named
      <filename>stable</filename> and then download the file that ends in
      <filename>.tar.gz</filename> to your local filesystem; e.g.
      <filename>hbase-0.94.2.tar.gz</filename>.</para>

      <para>Decompress and untar your download and then change into the
      unpacked directory.</para>

      <para><programlisting>$ tar xfz hbase-<?eval ${project.version}?>.tar.gz
$ cd hbase-<?eval ${project.version}?>
</programlisting></para>

      <para>At this point, you are ready to start HBase. But before starting
      it, edit <filename>conf/hbase-site.xml</filename>, the file you write
      your site-specific configurations into. Set
      <varname>hbase.rootdir</varname>, the directory HBase writes data to,
      and <varname>hbase.zookeeper.property.dataDir</varname>, the directory
      ZooKeeper writes its data too:
<programlisting>&lt;?xml version="1.0"?&gt;
&lt;?xml-stylesheet type="text/xsl" href="configuration.xsl"?&gt;
&lt;configuration&gt;
  &lt;property&gt;
    &lt;name&gt;hbase.rootdir&lt;/name&gt;
    &lt;value&gt;file:///DIRECTORY/hbase&lt;/value&gt;
  &lt;/property&gt;
  &lt;property&gt;
    &lt;name&gt;hbase.zookeeper.property.dataDir&lt;/name&gt;
    &lt;value&gt;/DIRECTORY/zookeeper&lt;/value&gt;
  &lt;/property&gt;
&lt;/configuration&gt;</programlisting> Replace <varname>DIRECTORY</varname> in the above with the
      path to the directory you would have HBase and ZooKeeper write their data. By default,
      <varname>hbase.rootdir</varname> is set to <filename>/tmp/hbase-${user.name}</filename>
      and similarly so for the default ZooKeeper data location which means you'll lose all
      your data whenever your server reboots unless you change it (Most operating systems clear
      <filename>/tmp</filename> on restart).</para>
    </section>

    <section xml:id="start_hbase">
      <title>Start HBase</title>

      <para>Now start HBase:<programlisting>$ ./bin/start-hbase.sh
starting Master, logging to logs/hbase-user-master-example.org.out</programlisting></para>

      <para>You should now have a running standalone HBase instance. In
      standalone mode, HBase runs all daemons in the the one JVM; i.e. both
      the HBase and ZooKeeper daemons. HBase logs can be found in the
      <filename>logs</filename> subdirectory. Check them out especially if
      it seems HBase had trouble starting.</para>

      <note>
        <title>Is <application>java</application> installed?</title>

        <para>All of the above presumes a 1.6 version of Oracle
        <application>java</application> is installed on your machine and
        available on your path (See <xref linkend="java" />); i.e. when you type
        <application>java</application>, you see output that describes the
        options the java program takes (HBase requires java 6). If this is not
        the case, HBase will not start. Install java, edit
        <filename>conf/hbase-env.sh</filename>, uncommenting the
        <envar>JAVA_HOME</envar> line pointing it to your java install, then,
        retry the steps above.</para>
      </note>
    </section>

    <section xml:id="shell_exercises">
      <title>Shell Exercises</title>

      <para>Connect to your running HBase via the <command>shell</command>.</para>

      <para><programlisting>$ ./bin/hbase shell
HBase Shell; enter 'help&lt;RETURN&gt;' for list of supported commands.
Type "exit&lt;RETURN&gt;" to leave the HBase Shell
Version: 0.90.0, r1001068, Fri Sep 24 13:55:42 PDT 2010

hbase(main):001:0&gt; </programlisting></para>

      <para>Type <command>help</command> and then
      <command>&lt;RETURN&gt;</command> to see a listing of shell commands and
      options. Browse at least the paragraphs at the end of the help emission
      for the gist of how variables and command arguments are entered into the
      HBase shell; in particular note how table names, rows, and columns,
      etc., must be quoted.</para>

  <para>Create a table named <varname>test</varname> with a single column family named <varname>cf</varname>.
      Verify its creation by listing all tables and then insert some
      values.</para>

      <para><programlisting>hbase(main):003:0&gt; create 'test', 'cf'
0 row(s) in 1.2200 seconds
hbase(main):003:0&gt; list 'test'
..
1 row(s) in 0.0550 seconds
hbase(main):004:0&gt; put 'test', 'row1', 'cf:a', 'value1'
0 row(s) in 0.0560 seconds
hbase(main):005:0&gt; put 'test', 'row2', 'cf:b', 'value2'
0 row(s) in 0.0370 seconds
hbase(main):006:0&gt; put 'test', 'row3', 'cf:c', 'value3'
0 row(s) in 0.0450 seconds</programlisting></para>

      <para>Above we inserted 3 values, one at a time. The first insert is at
      <varname>row1</varname>, column <varname>cf:a</varname> with a value of
      <varname>value1</varname>. Columns in HBase are comprised of a column family prefix --
      <varname>cf</varname> in this example -- followed by a colon and then a
      column qualifier suffix (<varname>a</varname> in this case).</para>

      <para>Verify the data insert by running a scan of the table as follows</para>

      <para><programlisting>hbase(main):007:0&gt; scan 'test'
ROW        COLUMN+CELL
row1       column=cf:a, timestamp=1288380727188, value=value1
row2       column=cf:b, timestamp=1288380738440, value=value2
row3       column=cf:c, timestamp=1288380747365, value=value3
3 row(s) in 0.0590 seconds</programlisting></para>

      <para>Get a single row</para>

      <para><programlisting>hbase(main):008:0&gt; get 'test', 'row1'
COLUMN      CELL
cf:a        timestamp=1288380727188, value=value1
1 row(s) in 0.0400 seconds</programlisting></para>

      <para>Now, disable and drop your table. This will clean up all done
      above.</para>

      <para><programlisting>hbase(main):012:0&gt; disable 'test'
0 row(s) in 1.0930 seconds
hbase(main):013:0&gt; drop 'test'
0 row(s) in 0.0770 seconds </programlisting></para>

      <para>Exit the shell by typing exit.</para>

      <para><programlisting>hbase(main):014:0&gt; exit</programlisting></para>
    </section>

    <section xml:id="stopping">
      <title>Stopping HBase</title>

      <para>Stop your hbase instance by running the stop script.</para>

      <para><programlisting>$ ./bin/stop-hbase.sh
stopping hbase...............</programlisting></para>
    </section>

    <section>
      <title>Where to go next</title>

      <para>The above described standalone setup is good for testing and
          experiments only. In the next chapter, <xref linkend="configuration" />,
      we'll go into depth on the different HBase run modes, system requirements
      running HBase, and critical configurations setting up a distributed HBase deploy.</para>
    </section>
  </section>

</chapter>