Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 36 ยท Getting Started

Installing HBase and Standalone Mode

Install Apache HBase on Linux, macOS or Windows with WSL, understand standalone, pseudo-distributed and fully distributed modes, and check that it runs.

You can learn nearly all of HBase on a single machine. HBase ships with a standalone mode that starts everything (Master, RegionServer and an embedded ZooKeeper) in one Java process and stores files on the local disk. It is perfect for learning and tests, and it takes five minutes to set up.

This lesson shows the real installation steps as read-only listings, because the site cannot start an HBase server for you. At the end there is a runnable Java stand-in that models the configuration rules you need to remember.

Requirements

  • Java. HBase 2.x runs on Java 8, 11 and (in newer 2.x releases) 17. Check the "Java support" table of the release you download. java -version must work and JAVA_HOME should be set.
  • A Unix-like system. Linux and macOS are the supported platforms. On Windows use WSL 2 or a Docker container; native Windows is not supported for running HBase.
  • Disk and memory. A few hundred MB of disk and 1 to 2 GB of free RAM are enough for standalone mode.
  • Hadoop is not required for standalone mode, because the local file system is used.

Download and unpack

Get the binary release (the file ending in -bin.tar.gz) from the Apache HBase download page, then unpack it.

Terminal
tar xzf hbase-2.6.1-bin.tar.gz
cd hbase-2.6.1

The version number above is an example. Pick a current stable 2.x release; the commands do not change between 2.x releases.

The folder contains:

  • bin/: scripts such as hbase, start-hbase.sh, stop-hbase.sh, hbase-daemon.sh.
  • conf/: configuration files hbase-site.xml, hbase-env.sh, regionservers, log4j2.properties.
  • lib/: all the jars.
  • docs/ and logs/.

Tell HBase where Java is

Edit conf/hbase-env.sh and set JAVA_HOME (uncomment the line that already exists):

Terminal
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64

Choose where data goes

By default, standalone HBase writes under /tmp, which many systems clear on reboot. For anything you want to keep, configure conf/hbase-site.xml:

XML
<configuration>
  <property>
    <name>hbase.rootdir</name>
    <value>file:///home/you/hbase-data/hbase</value>
  </property>
  <property>
    <name>hbase.zookeeper.property.dataDir</name>
    <value>/home/you/hbase-data/zookeeper</value>
  </property>
</configuration>

hbase.rootdir is the directory where HBase stores tables. With a file:// URL it uses the local disk. In a real cluster it is an hdfs:// URL. hbase.zookeeper.property.dataDir is where the embedded ZooKeeper keeps its snapshots.

Start it, check it, stop it

Terminal
./bin/start-hbase.sh

When it starts, jps (a JDK tool that lists Java processes) shows one process named HMaster; in standalone mode this single process also contains the RegionServer and ZooKeeper. The Master has a web page at http://localhost:16010 that lists tables, region servers, tasks and logs. The RegionServer's page is on port 16030.

Open the shell with ./bin/hbase shell and type status. It prints a short summary of servers; the exact wording varies by version. To stop everything cleanly:

Terminal
./bin/stop-hbase.sh

Always use the stop script. Killing the process can leave the write-ahead log needing replay (HBase recovers, but you lose time).

The three run modes

Mode Processes Storage Use
Standalone One JVM runs Master, RegionServer and ZooKeeper Local file system Learning, unit tests
Pseudo-distributed Separate daemons, all on one machine HDFS (single node) Practising real deployment steps
Fully distributed Daemons across many machines HDFS cluster plus a ZooKeeper quorum Production

For pseudo-distributed and distributed modes you set hbase.cluster.distributed to true, point hbase.rootdir at HDFS (for example hdfs://namenode:8020/hbase) and list the ZooKeeper hosts in hbase.zookeeper.quorum. The list of RegionServer hosts goes in conf/regionservers, one per line.

Docker, the lazy option

If you do not want to install anything, you can run a ready-made image. Image names and tags change often, so look up a current Apache HBase or community standalone image and check its README for ports. The pattern is always the same: publish port 16010 for the Master page and 2181 for ZooKeeper if clients need it.

Terminal
docker run -d --name hbase -p 16010:16010 -p 2181:2181 <hbase-standalone-image>
docker exec -it hbase hbase shell

Configuration is layered

HBase reads hbase-default.xml (inside the jar, never edit it) and then overrides it with conf/hbase-site.xml. Your Java client has its own copy of hbase-site.xml on its classpath, or you set properties in code. The stand-in below mimics this layering: defaults first, then your overrides.

Java Stand-in: layered configuration

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Typical problems

  • JAVA_HOME is not set. Set it in conf/hbase-env.sh.
  • Data disappeared after a reboot. You used the default /tmp rootdir. Set hbase.rootdir.
  • Master web page does not open. Check logs/hbase-*-master-*.log; a port may already be in use.
  • Hostname resolution errors. HBase is sensitive to /etc/hosts. Make sure your machine name resolves to a normal address, not only to 127.0.1.1 on some Linux distributions.
  • Client cannot connect from another machine. Standalone binds to localhost; use a distributed setup for remote clients.

A second stand-in: a startup checker that validates the things people forget, as a checklist you can adapt for your own setup scripts.

Java Stand-in: pre-flight checklist

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The second check fails on purpose, because the example rootdir sits under /tmp: that is the mistake the checklist exists to catch.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which process list entry shows standalone HBase running?

    In standalone mode a single JVM named HMaster runs everything.
  2. 2. What does hbase.rootdir control?

    It is the storage root: a file:// path in standalone mode, an hdfs:// URL in a cluster.
  3. 3. Why should you avoid the default storage location for anything you want to keep?

    The default points into the temporary directory, so data can vanish.
  4. 4. Where is the list of RegionServer hosts configured for start scripts?

    The start scripts read conf/regionservers, one hostname per line.

Summary

  • Standalone mode runs everything in one JVM on the local file system: ideal for learning.
  • You need Java and a Unix-like OS (use WSL or Docker on Windows).
  • Set JAVA_HOME in hbase-env.sh and hbase.rootdir in hbase-site.xml.
  • Use start-hbase.sh and stop-hbase.sh; check the Master page on port 16010.
  • Pseudo-distributed and distributed modes need HDFS and a ZooKeeper quorum.

Next: HBase and the Hadoop Ecosystem