hbase/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>
      <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>

      <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:</para>
      <screen>
127.0.0.1 localhost
127.0.0.1 ubuntu.ubuntu-domain ubuntu
      </screen>

    </note>

    <section>
      <title>JDK Version Requirements</title>
      <para>HBase requires that a JDK be installed. See <xref linkend="java" /> for information
        about supported JDK versions.</para>
    </section>

    <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>

      <screen><![CDATA[$ tar xfz hbase-<?eval ${project.version}?>.tar.gz
$ cd hbase-<?eval ${project.version}?>]]>
      </screen>

      <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:</para>
      <programlisting><![CDATA[<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="configuration.xsl"?>
<configuration>
  <property>
    <name>hbase.rootdir</name>
    <value>file:///DIRECTORY/hbase</value>
  </property>
  <property>
    <name>hbase.zookeeper.property.dataDir</name>
    <value>/DIRECTORY/zookeeper</value>
  </property>
</configuration>]]></programlisting>
      <para> 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:</para>
      <screen>$ ./bin/start-hbase.sh
starting Master, logging to logs/hbase-user-master-example.org.out</screen>

      <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>

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

hbase(main):001:0>]]> </screen>

      <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>

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

      <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>

      <screen><![CDATA[hbase(main):007:0> 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]]></screen>

      <para>Get a single row</para>

      <screen><![CDATA[hbase(main):008:0> get 'test', 'row1'
COLUMN      CELL
cf:a        timestamp=1288380727188, value=value1
1 row(s) in 0.0400 seconds]]></screen>

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

      <screen>h<![CDATA[base(main):012:0> disable 'test'
0 row(s) in 1.0930 seconds
hbase(main):013:0> drop 'test'
0 row(s) in 0.0770 seconds ]]></screen>

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

      <programlisting><![CDATA[hbase(main):014:0> exit]]></programlisting>
    </section>

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

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

      <screen>$ ./bin/stop-hbase.sh
stopping hbase...............</screen>
    </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>