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

Use this installation method to run Hyper-Converged Database (HCD) on bare metal or a virtual machine (VM). The following steps set up HCD in a compact installation in a single directory. By default, the installation stores binaries, data, and logs in the installation directory. For production deployments, you can optionally configure separate locations for data and logs. You can run the installation on Linux or Mac.

An HCD binary tarball enables:

Running HCD as a stand-alone process.
Storing binaries, data, and logs in a single directory.
Installing HCD with or without root permissions.

Important considerations before installation

HCD creates a default cassandra user with administrative privileges. Change or remove this default user before deploying to production to prevent unauthorized access. See Create a superuser account for instructions.

When you install HCD from the binary tarball, it runs as a stand-alone process.
This procedure installs HCD only. It doesn’t install developer-related tools, such as Cassandra drivers or Mission Control.

Prerequisites

An IBMid with MFA enabled.
- If you are an existing IBM customer with an IBMid, you can continue to use your established account.
- If you don’t have an IBMid, you can create one.
- If your company uses Enterprise Federation (EF) for authentication with corporate credentials, see the EF documentation.
Access to download the HCD tarball from IBM Passport Advantage.
- Site Number: You must be authorized by your Site Primary or Secondary Contact.
- Entitlement: You must have an active watsonx.data Premium Software Subscription and an HCD entitlement. If you are a primary contact, you will need a temporary passcode from your welcome letter to initially link your IBMid to your site number.
Install and configure Java 11. If you are running multiple Java runtime environments, set your $JAVA_HOME environment variable to Java 11.
- Recommended: Install a Technology Compatibility Kit (TCK)-certified OpenJDK 11 build
- Supported: Install Oracle Java SE 11.0.x (JDK)
Install a Python version from 3.8 to 3.11, which is required run cqlsh

Download HCD from IBM Passport Advantage

To download HCD from IBM Passport Advantage, do the following:

Go to the Passport Advantage Online for Customers website and click Sign in to your PAO site.
Log in with your IBMid.
Select Software download from the top menu or the quick links list.
Search for the product by name or part number, or use the Find downloads & media tool to view your entitled products.
Select the version you need.
Select the files you need, agree to the terms and conditions, and then click Download now.

The download file is named HCD_VERSION_NUMBER_EN.zip.

Extract the ZIP file to access the installation files.

The extracted folder contains the following files:

cqlsh-**VERSION_NUMBER**-bin.tar.gz.md5
cqlsh-**VERSION_NUMBER**-bin.tar.gz.sha512
cqlsh-**VERSION_NUMBER**-bin.tar.gz
hcd-**VERSION_NUMBER**-bin.tar.gz.md5
hcd-**VERSION_NUMBER**-bin.tar.gz.sha512
hcd-**VERSION_NUMBER**-bin.tar.gz

Install HCD using a tarball

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.
Start HCD from the installation directory:
```
cd hcd-VERSION_NUMBER
bin/hcd cassandra
```
Replace VERSION_NUMBER with your installation’s version number.

If HCD doesn’t start, check your Java version and make sure that the JAVA_HOME environment variable is set correctly.
Optional: To store logs in a custom location, set the CASSANDRA_LOG_DIR environment variable:
```
cd hcd-VERSION_NUMBER
CASSANDRA_LOG_DIR=pwd/logs bin/hcd cassandra
```
Replace VERSION_NUMBER with your installation’s version number.

Data and logging directory locations

You can use the default data and logging directory locations, or you can define your own locations.

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

Connect to HCD

HCD runs as a stand-alone process.

To connect to HCD, you can use the CQL shell (cqlsh). For more information, see Connect to Hyper-Converged Database (HCD) with CQL shell (cqlsh).

Next steps

Create a superuser account to secure your installation.
Create and manage keyspaces to organize your database objects.