Install Hyper-Converged Database (HCD) on RHEL-based systems using Yum

You can install Hyper-Converged Database (HCD) 1.2 on RHEL-based systems using the Yum package manager.

When installed from a package, HCD runs as a service. The service initialization script is located in /etc/init.d/hcd. Run levels are not set by the package.

This procedure installs HCD only. It doesn’t install other tools, such as 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

Access to download the HCD package from IBM Passport Advantage:
- IBMid: An IBMid account with MFA enabled is required. If you don’t have one, create an IBMid account. If your organization uses Enterprise Federation (EF) for authentication with corporate credentials, see the IBMid EF documentation.
- 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.
- Temporary passcode (primary contact, initial setup only): If you are a primary contact, you need a temporary passcode from your welcome letter to initially connect your IBMid to your site number.
An environment where you want to install HCD, including sufficient hardware and root or sudo access.
Yum package manager.
RHEL-compatible platforms require 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.
To run the CQL shell (cqlsh), install a supported Python version: 3.8 to 3.12.
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.

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.

For the best search results, try one of the following:

Search by product name: Include the word Version in your search. For example, Hyper-Converged Database Version.
Search by part number: Find part numbers for each release in the release notes.

If results show only eAssemblies, switch to the Images tab to find HCD under Analytics - Platform.

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:
```
hcd-package-signing.pub.asc
hcd-VERSION_NUMBER-1.noarch.rpm
```

Install HCD using an RPM package

You can use the package signing public key (hcd-rpm-signing.pub.asc) in the file to set up and verify the RPM packages:

Import the package signing public key:

sudo rpm --import hcd-rpm-signing.pub.asc

Validate the RPM package signature:

rpm -Kv hcd-VERSION_NUMBER-1.noarch.rpm

The output should show successful verification:

hcd-1.2.7-1.noarch.rpm:
    Header V4 RSA/SHA256 Signature, key ID 1cab3ea5: OK
    Header SHA256 digest: OK
    Header SHA1 digest: OK
    Payload SHA256 digest: OK
    MD5 digest: OK

Set up a local Yum repository to host the downloaded RPM files:

For more information, see the Red Hat documentation:
- Set up a Yum/DNF repository with Apache
- Set up a Yum/DNF repository with nginx
- Upload content to custom RPM repositories (Red Hat Satellite)
From inside your repository directory, run the following command to generate the metadata index that Yum uses to locate packages:
```
createrepo .
```
If createrepo is not installed, run sudo yum install createrepo first.
Add the local DataStax Yum repository to a file called /etc/yum.repos.d/datastax.repo:
```
[datastax]
name=DataStax Repo for HCD
baseurl=file://REPOSITORY_DIRECTORY_PATH
enabled=1
gpgcheck=0
```
Replace REPOSITORY_DIRECTORY_PATH with the path to your repository directory.
Install the HCD packages:
```
sudo yum install hcd
```

Configure systemd

By default, HCD uses init.d scripts for service management. On RHEL-based systems with systemd, you can optionally switch to systemd units.

On systems that have systemd, you can still manipulate the old init.d services using systemd commands such as systemctl start hcd.

The RPM package installs the following units in /usr/lib/systemd/system:

hcd.target: starts HCD nodes
hcd-shutdown.target: stops HCD nodes

The package also installs a hcd@.service template in /usr/share/hcd/templates. It serves as a template unit for all HCD node instances running on the host OS under the cassandra user. The hcd add-node command and the /usr/share/hcd/tools/hcd-convert-to-systemd helper script use that template.

Once you enable hcd.target, the hcd add-node command creates and enables systemd services for new nodes, and creates init.d scripts to redirect lifecycle commands to systemctl.

Enable HCD systemd units

Stop the HCD init.d service:
```
sudo service hcd stop
```
Enable hcd.target:
```
sudo systemctl enable hcd.target
```
After enabling hcd.target, HCD nodes automatically start as part of the multi-user target on each reboot.

systemd operations

Start all HCD nodes:
```
systemctl start hcd.target
```
Start one HCD node:
```
systemctl start full-node-id
```
Stop one HCD node:
```
systemctl stop full-node-id
```

Use the fully-qualified node ID for the node address, full-node-id, and include the hcd- prefix. The node ID defaults to hcd unless you configure other nodes.

The default start timeout is 10 minutes and the default stop timeout is 30 seconds. Adjust these values by editing the corresponding unit files.

Start HCD

Single-node cluster installations

Start HCD.
```
sudo service hcd start
```

Verify that HCD is running:

nodetool status

Make sure the output shows nodes as UN (Up/Normal).

Result

Datacenter: Cassandra
=====================
Status=Up/Down
|/ State=Normal/Leaving/Joining/Moving
--  Address    Load       Tokens  Owns    Host ID                               Rack
UN  127.0.0.1  82.43 KB   128     ?       40725dc8-7843-43ae-9c98-7c532b1f517e  rack1

Multi-node installations

Repeat the installation steps on all nodes.
Start HCD on each node:
```
sudo service hcd start
```

Verify that HCD is running on each node:

nodetool status

Make sure the output shows nodes as UN (Up/Normal).

Result

Datacenter: Cassandra
=====================
Status=Up/Down
|/ State=Normal/Leaving/Joining/Moving
--  Address    Load       Tokens  Owns    Host ID                               Rack
UN  127.0.0.1  82.43 KB   128     ?       40725dc8-7843-43ae-9c98-7c532b1f517e  rack1

Install Hyper-Converged Database (HCD) on RHEL-based systems using Yum

Prerequisites

Download HCD from IBM Passport Advantage

Install HCD using an RPM package

Configure systemd

Enable HCD systemd units

systemd operations

Start HCD

Next steps

Was this helpful?

Give Feedback