2.2. Installing VoltDB

Documentation

Home » Documentation » Using VoltDB

2.2. Installing VoltDB

VoltDB is distributed as a compressed tar archive for each of the supported platforms. The file name identifies the platform, the edition (community or enterprise) and the version number. The best way to install VoltDB is to unpack the distribution kit as a folder in the home directory of your personal account, like so:

$ tar -zxvf LINUX-voltdb-ent-4.0.2.tar.gz -C $HOME/

Installing into your personal directory gives you full access to the software and is most useful for development.

If you are installing VoltDB on a production server where the database will be run, you may want to install the software into a standard system location so that the database cluster can be started with the same commands on all nodes. The following shell commands install the VoltDB software in the folder /opt/voltdb:

$ sudo tar -zxvf LINUX-voltdb-ent-4.0.2.tar.gz -C /opt
$ cd /opt
$ sudo mv voltdb-ent-4.0.2 voltdb

Note that installing as root using the sudo command makes the installation folders read-only for non-privileged accounts. Which is why installing in $HOME is recommended for running the sample applications and other development activities. Alternately, you can use standard installation packages for Linux systems, as described in Section 2.2.2, “Installing Standard System Packages”.

2.2.1. Upgrading From Older Versions

When upgrading from a previous version of VoltDB — especially with an existing database — there are a few key steps you should take to ensure a smooth migration. The recommended steps for upgrading an existing database are:

  1. Place the database in admin mode (voltadmin pause).

  2. Perform a manual snapshot of the database (voltadmin save).

  3. Shutdown the database (voltadmin shutdown).

  4. Upgrade VoltDB.

  5. Start a new database using the voltdb create option, your existing application catalog, and starting in admin mode (specified in the deployment file).

  6. Restore the snapshot created in Step #2 (voltadmin restore).

  7. Return the database to normal operations (voltadmin resume).

Note that the voltdb create command automatically recompiles your catalog if the catalog was created by an older version. When using the Enterprise Manager, it is also recommended that you delete the Enterprise Manager configuration files (stored by default in the .voltdb subfolder in the home directory of the current account) when performing an upgrade.

2.2.2. Installing Standard System Packages

If you plan on making VoltDB available to all users of the system, you can use a common system package to install the VoltDB files in standard locations. Installation packages are available for both Debian-based (deb) and Red Hat-based (rpm) systems. These packages simplify the installation process by placing the VoltDB files in standard system directories, making VoltDB available to all users of the system without their having to individually configure their PATH variable.

The advantages of using an install package are:

  • The installation is completed in a single command. No additional set up is required.

  • VoltDB becomes available to all system users.

  • Upgrades are written to the same location. You do not need to modify your application scripts or move files after each upgrade.

However, there are a few changes to behavior that you should be aware of if you install VoltDB using a system package manager:

  • The VoltDB libraries are installed in /usr/lib/voltdb. When compiling stored procedures, you must include this location in your Java classpath.

  • The sample applications are installed into the directory /usr/share/voltdb/examples/. Because this is a system directory, users cannot run the samples directly in that location. Instead, first copy the folder containing the sample application you want to run and paste a copy into your home directory structure. Then run the sample from your copy. For example:

    $ cp -r /usr/share/voltdb/examples/voter ~/
    $ cd ~/voter
    $ ./run.sh

2.2.2.1. Installing the Debian Package

To install the Debian package on Ubuntu or other Debian-based systems, download the package from the VoltDB web site. Then, from an account with root access issue the following commands to install Open JDK 7 and VoltDB:

$ sudo apt-get install openjdk-7-jdk
$ sudo dpkg -i voltdb_4.0.2-1_amd64.deb

2.2.2.2. Installing the RPM Package

To install the rpm package on compatible systems such as Red Hat or CentOS, download the package from the VoltDB web site. Then, from an account with root access issue the following command:

$ sudo yum localinstall voltdb-4.0.2-1.x86_64.rpm

2.2.3. Building a New VoltDB Distribution Kit

If you want to build the open source VoltDB software from source (for example, if you want to test recent development changes), you must first fetch the VoltDB source files. The VoltDB sources are stored in a GitHub repository.

The VoltDB sources are designed to build and run on 64-bit Linux-based or 64-bit Macintosh platforms. However, the build process has not been tested on all possible configurations. Attempts to build the sources on other operating systems may require changes to the build files and possibly to the sources as well.

Once you obtain the sources, use Ant 1.7 or later to build a new distribution kit for the current platform:

$ ant dist

The resulting distribution kit is created as obj/release/volt-n.n.nn.tar.gz where n.n.nn identifies the current version and build numbers. Use this file to install VoltDB according to the instructions in Section 2.2, “Installing VoltDB”.