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

  • Get access to download the HCD tarball 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.

  • 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.

  • 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:

  1. Go to the Passport Advantage Online for Customers website and click Sign in to your PAO site.

  2. Log in with your IBMid.

  3. Select Software download from the top menu or the quick links list.

  4. 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.

  5. Select the version you need.

  6. 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.

  7. Extract the ZIP file to access the installation files.

    The extracted folder contains the following files:

    hcd-package-signing.pub.asc
hcd-package-signing.pem.cer
hcd-package-signing.pem.chain
cqlsh-VERSION_NUMBER-bin.tar.gz
cqlsh-VERSION_NUMBER-bin.tar.gz.asc
cqlsh-VERSION_NUMBER-bin.tar.gz.cosign.sig
hcd-VERSION_NUMBER-bin.tar.gz
hcd-VERSION_NUMBER-bin.tar.gz.asc
hcd-VERSION_NUMBER-bin.tar.gz.cosign.sig

Validate tarball signatures

Two tarball packages are provided in HCD: hcd-VERSION-bin.tar.gz and cqlsh-VERSION-bin.tar.gz.

For each package, there are two signature files:

  • *.asc: GPG signature (ASCII armored files)

  • *.cosign.sig: Cosign signature (binary format)

The process to validate each signature (and the guarantees of each) are different.

Validate GPG signatures

  1. Import the package signature armored public key:

    gpg --import hcd-package-signing.pub.asc
    Result
    gpg: directory '/home/jenkins/.gnupg' created
gpg: keybox '/home/jenkins/.gnupg/pubring.kbx' created
gpg: /home/jenkins/.gnupg/trustdb.gpg: trustdb created
gpg: key 9F0E3F501CAB3EA5: public key "DataStax Hyper-Converged Database <psirt@us.ibm.com>" imported
gpg: Total number processed: 1
gpg:               imported: 1

    Validate that the key information (key: 9F0E3F501CAB3EA5 and name DataStax Hyper-Converged Database (HCD) psirt@us.ibm.com) matches the output above.

  2. Optional: Trust the imported key:

    gpg --edit-key "DataStax Hyper-Converged Database"

    At the prompts enter trust, select a trust level, and then enter quit. Trust levels include:

    • 5: I trust ultimately (use with caution)

    • 4: I trust fully

    • 3: I trust marginally

  3. Validate the packages:

    gpg --verify hcd-1.2.7-bin.tar.gz.asc hcd-1.2.7-bin.tar.gz
    Result
    gpg: Signature made Tue Jun 23 08:19:31 2026 UTC
gpg:                using RSA key 4065A3A1F9C1AC54A06FCA8C9F0E3F501CAB3EA5
gpg: Good signature from "DataStax Hyper-Converged Database <psirt@us.ibm.com>" [ultimate]

    If you didn’t trust the GPG key in step 2, the output displays a warning instead:

    gpg: Signature made Tue Jun 23 08:19:31 2026 UTC
gpg:                using RSA key 4065A3A1F9C1AC54A06FCA8C9F0E3F501CAB3EA5
gpg: Good signature from "DataStax Hyper-Converged Database <psirt@us.ibm.com>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 4065 A3A1 F9C1 AC54 A06F  CA8C 9F0E 3F50 1CAB 3EA5

    This warning is expected when the key has not been validated. Verify that the key matches 9F0E3F501CAB3EA5 with name DataStax Hyper-Converged Database (HCD) psirt@us.ibm.com and, optionally, trust the key using the instructions in step 2.

Validate cosign signatures

Use OpenSSL to validate cosign signatures using the certificate. This method allows you to check both the package signature against the public key inside the certificate and the chain of trust of the certificate.

  1. Validate package signatures:

    openssl dgst -verify <(openssl x509 -in hcd-package-signing.pem.cer -pubkey -noout) \
    -keyform PEM -sha256 -signature hcd-VERSION-bin.tar.gz.cosign.sig -binary hcd-VERSION-bin.tar.gz
    Result
    Verified OK

    Replace VERSION_NUMBER with your installation’s version number. For example, 1.2.7.

  2. Validate the certificate chain:

    openssl verify -CAfile hcd-package-signing.pem.chain hcd-package-signing.pem.cer
    Result
    hcd-package-signing.pem.cer: OK

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

  1. 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

  2. Change to your HCD installation directory, and then change to the directory containing the cassandra.yaml file:

    cd ../resources/cassandra/conf

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

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

Install HCD using a tarball

  1. 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. For example, 1.2.7.

    HCD unpacks its files into the hcd-VERSION_NUMBER subdirectory.

  2. 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.

  3. 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.

  4. For multi-node installations, repeat the install process and start HCD on each node.

Next steps

Was this helpful?

Give Feedback

How can we improve the documentation?

© Copyright IBM Corporation 2026 | Privacy policy | Terms of use |  Manage Privacy Choices

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: Contact IBM