Chapter 2
Installing HyperDex

HyperDex provides multiple installation methods that provide easy access to HyperDex in a variety of environments. For Linux users, the easiest and most convenient way to install HyperDex is to use pre-compiled binary packages. Users of OS X have the option to install using Homebrew packages. Finally, HyperDex is also distributed as a set of tarballs so that power users may install HyperDex in a custom manner on their platform of choice.

2.1 Installing on CentOS/RedHat Using Binary Packages

The following code snippet will install HyperDex on any 64-bit CentOS 6 or 7 system. The script configures the HyperDex repository, imports the HyperDex signing key, and installs the hyperdex package. This script is available in the HyperDex tarball or repository at doc/install/centos-packages.sh.

  cat >> /etc/yum.conf << EOF
  [hyperdex]
  name=hyperdex

  baseurl=http://centos.hyperdex.org/base/\$basearch/\$releasever
  enabled=1
  gpgcheck=1
  EOF

  rpm --import http://centos.hyperdex.org/hyperdex.gpg.key
  yum install -y epel-release
  yum install -y hyperdex

Note: Users installing on Red Hat Enterprise Linux may have to follow the instructions to install Extra Packages for Enterprise Linux 1 prior to running the above code.

2.2 Installing on Debian Using Binary Packages

The following code snippet will install HyperDex on any 64-bit Debian 7 (Wheezy) system. The script configures the HyperDex repository, imports the HyperDex signing key, and installs the HyperDex package. This script is available in the HyperDex tarball or repository at doc/install/debian7-packages.sh.

  wget -O - http://debian.hyperdex.org/hyperdex.gpg.key | apt-key add -
  cat >> /etc/apt/sources.list.d/hyperdex.list << EOF

  deb [arch=amd64] http://debian.hyperdex.org wheezy main
  EOF
  apt-get update
  apt-get install -y hyperdex

2.3 Installing on Ubuntu Using Binary Packages

The following code snippets will install HyperDex on 64-bit Ubuntu systems. Pick the script that corresponds to the distribution you are running. Each script configures the HyperDex repository, imports the HyperDex signing key, and installs the HyperDex package. To figure out which version of Ubuntu you are using, cat /etc/os-release and look for the corresponding version and codename.

2.3.1 Ubuntu 12.04 Precise Pangolin

This script is available in the HyperDex tarball or repository at doc/install/ubuntu12.04-packages.sh.

  wget -O - http://ubuntu.hyperdex.org/hyperdex.gpg.key | apt-key add -
  cat >> /etc/apt/sources.list.d/hyperdex.list << EOF

  deb [arch=amd64] http://ubuntu.hyperdex.org precise main
  EOF
  apt-get update
  apt-get install -y hyperdex

2.3.2 Ubuntu 14.04 Trusty Tahr

This script is available in the HyperDex tarball or repository at doc/install/ubuntu14.04-packages.sh.

  wget -O - http://ubuntu.hyperdex.org/hyperdex.gpg.key | apt-key add -
  cat >> /etc/apt/sources.list.d/hyperdex.list << EOF

  deb [arch=amd64] http://ubuntu.hyperdex.org trusty main
  EOF
  apt-get update
  apt-get install -y hyperdex

2.4 Installing on Fedora Using Binary Packages

The following code snippet will install HyperDex on any 64-bit Fedora 20 system. The script configures the HyperDex repository, imports the HyperDex signing key, and installs the hyperdex package. This script is available in the HyperDex tarball or repository at doc/install/fedora-packages.sh.

  cat >> /etc/yum.conf << EOF
  [hyperdex]
  name=hyperdex
  baseurl=http://fedora.hyperdex.org/base/\$basearch/\$releasever

  enabled=1
  gpgcheck=1
  EOF
  rpm --import http://fedora.hyperdex.org/hyperdex.gpg.key
  yum install -y hyperdex

2.5 Installing on Linux Using Universal Binaries

HyperDex is also available as a self-contained universal binary that works on most glibc-based Linux distributions. To use this installation, first download the requisite tarball, and then you can install HyperDex like this:

  tar xzvf hyperdex-1.5.0-linux-amd64.tar.gz -C /usr/local
  export PATH=/usr/local/hyperdex/bin:${PATH}

  hyperdex --version

2.6 Installing on OS X Using Homebrew

XXX

2.7 Installing From Source

An alternative to installing a prepackaged binary is to install from source tarballs. This is a straightforward process that should work on most any recent Linux distribution for which there isn’t a prepackaged binary. We’ll first list the prerequisites to installing HyperDex from a source tarball. Then, we’ll describe how to configure HyperDex. Finally, we’ll describe the installation step.

2.7.1 Prerequisites

HyperDex has a minimal number of prerequisites for installation from source. Although we list all prerequisites in this section for completeness, the HyperDex configuration step will automatically warn about any missing dependencies.

Required Dependencies:

Dependencies for Python Bindings:

Dependencies for Java Bindings:

Dependencies for Yahoo! Cloud Serving Benchmark (YCSB):

2.7.2 Configuring

HyperDex uses the Autotools to make configuration and installation as straightforward as possible. After extracting the HyperDex tarball, you’ll need to configure HyperDex. The simplest configuration installs HyperDex in its default location (/usr/local) using the C++ compiler found on the system. The configuration is performed in the directory extracted from the tarball and looks like:

  ./configure

This basic configuration will configure the HyperDex daemon and native client library components to be built; however it omits several useful options for configuring HyperDex. The rest of this section will highlight common ways to configure HyperDex. Unless otherwise noted, all options should work well together.

2.7.2.1 Java Bindings

HyperDex does not build Java bindings by default. To enable the Java bindings, you must pass --enable-java-bindings to ./configure like so:

  ./configure --enable-java-bindings

If any of the prerequisites are missing ./configure should fail.

Java bindings are currently unavailable in 1.5.0.

2.7.2.2 Python Bindings

HyperDex does not build Python bindings by default. To enable the Python bindings, you must pass --enable-python-bindings to ./configure like so:

  ./configure --enable-python-bindings

If Python or its headers cannot be found, ./configure will fail.

2.7.2.3 Yahoo! Cloud Serving Benchmark

HyperDex provides all the source code necessary to build a HyperDex driver for the YCSB benchmark. If Java bindings are enabled, then YCSB can be built with --enable-ycsb.

  ./configure --enable-ycsb

Note that YCSB must be in your Java CLASSPATH. Configure cannot detect YCSB by itself.

2.7.2.4 Changing the Installation Directory

By default HyperDex installs files in /usr/local. If you’d like to install HyperDex elsewhere, you can specify the installation prefix at configure time. For example, to install HyperDex in /opt/hyperdex:

  ./configure --prefix=/opt/hyperdex

Check the --help option to configure for more ways to tune where HyperDex places files.

2.7.3 Installing

Once configured, HyperDex is simple to build and install. Keep in mind that the following commands may fail if the installation directory is not writable by the current user.

  make
  make install
  ldconfig

2.8 Installing from Git

Developers wishing to contribute to the development of HyperDex may build HyperDex directly from Git. Building from Git is as straightforward as building from source tarballs, but requires a few extra dependencies and some setup before the ./configure step.

In order to build the HyperDex repository, you’ll need to have the following utilities installed. Most of these utilities are prepacked for Linux distributions. Note that since these dependencies are only required for building from Git, they will not be detected at ./configure time and instead make will fail with an error message.

Required Dependencies:

You’ll need to build po6, e, BusyBee, HyperLevelDB Replicant, and HyperDex from Git, as the development version often introduces across repositories.

For each of these repositories, you may build and install the code with:

  autoreconf -i
  ./configure
  make
  make install
  ldconfig

2.8.1 Troubleshooting

2.8.1.1 Missing libtool

If your system is missing libtool, you’ll see an error message like the following:

  configure.ac:6: installing ‘./install-sh’
  configure.ac:6: installing ‘./missing’
  Makefile.am:48: Libtool library used but ‘LIBTOOL’ is undefined
  Makefile.am:48:   The usual way to define ‘LIBTOOL’ is to add ‘LT_INIT’
  Makefile.am:48:   to ‘configure.ac’ and run ‘aclocal’ and ‘autoconf’ again.
  Makefile.am:48:   If ‘LT_INIT’ is in ‘configure.ac’, make sure
  Makefile.am:48:   its definition is in aclocal’s search path.
  Makefile.am: installing ‘./depcomp’
  autoreconf: automake failed with exit status: 1
2.8.1.2 Missing pkgconfig

If your system is missing pkgconfig, you’ll see an error message like the following:

  ./configure: line 18348: syntax error near unexpected token ‘PO6,’
  ./configure: line 18348: ‘PKG_CHECK_MODULES(PO6, libpo6 >= 0.3.1)’

2.9 Verifying Installation

Once you have HyperDex installed, you should be able to view the built-in help. If the following commands provide meaningful output, then it is very likely that HyperDex is installed correctly and ready for use.

  hyperdex help
  hyperdex daemon --help

2.10 Upgrading to 1.4

Upgrading to 1.4 is a two step process. First, take a full backup of your cluster using the provided backup tools. Start the 1.4 cluster from the backup. This will upgrade the coordinator to 1.4, and the daemons will work with the old data directory.

Alternatively, take a backup, and restart the coordinator from the backed-up coordinator state on the same address. Then do a rolling restart of the daemons.

The 1.4 release’s on-disk format is backwards incompatible with the 1.3 and prior releases. HyperDex daemons will automatically upgrade to the 1.4 format when first launched.

2.11 Upgrading to 1.3

Upgrading to 1.3 is a two step process. First, take a full backup of your cluster using the provided backup tools. Start the 1.3 cluster from the backup. This will upgrade the coordinator to 1.3, and the daemons will work with the old data directory.

Alternatively, take a backup, and restart the coordinator from the backed-up coordinator state on the same address. Then do a rolling restart of the daemons.

2.12 Upgrading to 1.2

The 1.2 release introduces new features that are backwards incompatible with previous releases. Before upgrading to 1.2, backup your data. Once 1.2 is installed, copy your data into a newly-deployed 1.2 cluster.

1https://fedoraproject.org/wiki/EPEL