Install Hyper-Converged Database (HCD) using the binary tarball

You can run Hyper-Converged Database (HCD) on bare metal or a virtual machine (VM) by installing it from a binary tarball. You can run the installation on Linux or Mac. Root access isn’t required.

When you install HCD from a binary tarball, it runs as a standalone process.

This procedure performs a compact installation in a single directory. By default, the installation stores binaries, data, and logs in the installation directory. For production deployments, configure separate locations for data and logs before you start HCD.

This procedure installs HCD only. It doesn’t install other tools like Cassandra drivers or Mission Control.

When you install HCD, it creates a cassandra superuser role in the database, and HCD runs as this user. Don’t use the default cassandra role in production because it is a security risk. Instead, create a new superuser role for running HCD.

Prerequisites

Prepare the environment where you want to install HCD, including sufficient hardware.
For RHEL-compatible platforms, enable Extra Packages for Enterprise Linux (EPEL).
Install a supported Java 11 runtime: OpenJDK 11 (recommended) or Oracle Java SE 11.0.x (JDK).

If you install multiple Java versions, set your $JAVA_HOME environment variable to Java 11.
Install a supported Python version for CQL shell: Python 3.8 to 3.13.
For production installations and simulated production test environments, review the recommended settings.

Some settings can be applied before installing HCD. For settings that require a running HCD instance, plan to apply them after the installation.

Install HCD from a tarball

Contact IBM Support to request a HCD 1.1 tarball download link.
Unpack the tarball into your desired installation directory:
```
tar xvzf hcd-VERSION_NUMBER-bin.tar.gz
```
Replace VERSION_NUMBER with your installation’s version number.

HCD unpacks its files into the hcd-VERSION_NUMBER subdirectory. The installation includes the CQL shell (cqlsh) automatically; you don’t need to unpack the cqlsh tarball.

Set data and log directory locations

You can use the default data and logging directory locations, or you can define your own locations. Configure your preferred locations before you start HCD.

Use default directory locations

To use the default data and logging directory locations, you must create and set ownership for the following:

/var/lib/cassandra
/var/log/cassandra

sudo mkdir -p /var/lib/cassandra; sudo chown -R $USER:$GROUP /var/lib/cassandra &&
sudo mkdir -p /var/log/cassandra; sudo chown -R $USER:$GROUP /var/log/cassandra

Use custom directory locations

In your HCD installation directory, create directories for data and logging:

mkdir hcd-data &&
cd hcd-data &&
mkdir data &&
mkdir commitlog &&
mkdir saved_caches &&
mkdir hints &&
mkdir cdc_raw

Change to your HCD installation directory, and then change to the directory containing the cassandra.yaml file:
```
cd ../resources/cassandra/conf
```

Update the following lines in the cassandra.yaml file to match your custom locations:

data_file_directories:
  - full_path_to_installation_location/hcd-data/data
  commitlog_directory: full_path_to_installation_location/hcd-data/commitlog
  saved_caches_directory: full_path_to_installation_location/hcd-data/saved_caches
  hints_directory: full_path_to_installation_location/hcd-data/hints
  cdc_raw_directory: full_path_to_installation_location/hcd-data/cdc_raw

Optional: To store logs in a custom location, set the CASSANDRA_LOG_DIR environment variable inline at start-up:
```
cd hcd-VERSION_NUMBER
CASSANDRA_LOG_DIR=INSTALLATION_DIRECTORY/logs bin/hcd cassandra
```
Replace the following:
- VERSION_NUMBER: Your installation’s version number
- INSTALLATION_DIRECTORY: The full path to your installation directory
  
  This sets a process-level override for the current invocation only. It does not persist across restarts. To permanently redirect logs, configure the log directory in cassandra.yaml before starting HCD.

Start HCD

Start HCD from the installation directory:
```
cd hcd-VERSION_NUMBER
bin/hcd cassandra
```
Replace VERSION_NUMBER with your installation’s version number. For example, 1.2.7.

If HCD doesn’t start, check your Java version, and make sure that the $JAVA_HOME environment variable is set to the latest HCD supported Java version that you have installed.
For multi-node installations, repeat the install process and start HCD on each node.