Install Hyper-Converged Database (HCD) on Debian-based systems using APT

You can install Hyper-Converged Database (HCD) 1.2 on Debian-based systems using APT.

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

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

  • Aptitude Package Management (APT) application. 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:

  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-VERSION_NUMBER_all.deb

Install HCD using APT

  1. Install the libaio package. For example:

    • Debian platforms:

      sudo apt-get install libaio1

    • Ubuntu 24.04 and later platforms:

      sudo apt-get install libaio1t64

  2. Extract the DEB files from the zip file:

    sudo unzip hcd-1.2.7_all-deb.zip

  3. Optional: Validate the Debian package signature.

    Debian/Ubuntu packages are signed with debsigs and validated with debsig-verify tools. These packages are only available in Ubuntu versions 22.04 or higher.

    To install the required packages:

    sudo apt-get update ; sudo apt install -y debsig-verify

    Validating packages requires configuring a policy file and adding the GPG public key (hcd-package-signing.pub.asc):

    sudo mkdir -p /etc/debsig/policies/9F0E3F501CAB3EA5
cat << EOF | sudo tee /etc/debsig/policies/9F0E3F501CAB3EA5/hcd-package-signature-policy.pol
<?xml version="1.0"?>
<!DOCTYPE Policy SYSTEM "https://www.debian.org/debsig/1.0/policy.dtd">
<Policy xmlns="https://www.debian.org/debsig/1.0/">
  <Origin Name="DataStax Hyper-Converged Database" id="9F0E3F501CAB3EA5" Description="Trusted Package Signer"/>
  <Selection>
    <Required Type="origin" File="signer-key.gpg" id="9F0E3F501CAB3EA5"/>
  </Selection>
  <Verification MinOptional="0">
    <Required Type="origin" File="signer-key.gpg" id="9F0E3F501CAB3EA5"/>
  </Verification>
</Policy>
EOF
sudo mkdir -p /usr/share/debsig/keyrings/9F0E3F501CAB3EA5
gpg --dearmor < hcd-package-signing.pub.asc > signer-key.gpg
sudo cp signer-key.gpg /usr/share/debsig/keyrings/9F0E3F501CAB3EA5/

    Then, packages can be validated:

    debsig-verify -d ./signed/debsigs/hcd_1.2.7_all.deb

    You can monitor the validation process in the terminal while it runs:

    debsig: Starting verification for: hcd_1.2.7_all.deb
debsig:         getSigKeyID: got 4065A3A1F9C1AC54A06FCA8C9F0E3F501CAB3EA5 for origin key
debsig: getDbPathname: using /etc/debsig/policies/9F0E3F501CAB3EA5 keyring
debsig: Using policy directory: /etc/debsig/policies/9F0E3F501CAB3EA5
debsig:   Parsing policy file: /etc/debsig/policies/9F0E3F501CAB3EA5/hcd-package-signature-policy.pol
debsig:     parsePolicyFile: parsing '/etc/debsig/policies/9F0E3F501CAB3EA5/hcd-package-signature-policy.pol'
debsig:     parsePolicyFile: completed
debsig:     Checking Selection group(s).
debsig:       Processing 'origin' key...
debsig: getDbPathname: using /usr/share/debsig/keyrings/9F0E3F501CAB3EA5/signer-key.gpg keyring
debsig:         getKeyID: mapped 9F0E3F501CAB3EA5 -> 4065A3A1F9C1AC54A06FCA8C9F0E3F501CAB3EA5
debsig:         getSigKeyID: got 4065A3A1F9C1AC54A06FCA8C9F0E3F501CAB3EA5 for origin key
debsig:     Selection group(s) passed, policy is usable.
debsig: Using policy file: /etc/debsig/policies/9F0E3F501CAB3EA5/hcd-package-signature-policy.pol
debsig:     Checking Verification group(s).
debsig:       Processing 'origin' key...
debsig: getDbPathname: using /usr/share/debsig/keyrings/9F0E3F501CAB3EA5/signer-key.gpg keyring
debsig:         getKeyID: mapped 9F0E3F501CAB3EA5 -> 4065A3A1F9C1AC54A06FCA8C9F0E3F501CAB3EA5
debsig:         getSigKeyID: got 4065A3A1F9C1AC54A06FCA8C9F0E3F501CAB3EA5 for origin key
gpg: Signature made Tue Jun 23 08:18:57 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
debsig:     Verification group(s) passed, deb is validated.
debsig: Verified package from 'Trusted Package Signer' (DataStax Hyper-Converged Database)

    A warning message like This key is not certified with a trusted signature! means GPG validated an untrusted key.

  4. Set up a local APT repository to host the downloaded HCD Debian package.

    For more information, see Setting up a Debian repository.

  5. From inside your repository directory, run the following command to generate the package index that APT uses to locate packages:

    dpkg-scanpackages . /dev/null | gzip -9c | sudo tee Packages.gz > /dev/null

    If dpkg-scanpackages is not installed, run sudo apt-get install dpkg-dev first.

  6. Add a DataStax repository file called /etc/apt/sources.list.d/datastax.sources.list:

    echo "deb [trusted=yes] file:REPOSITORY_DIRECTORY_PATH ./" | sudo tee -a /etc/apt/sources.list.d/datastax.sources.list

    Replace REPOSITORY_DIRECTORY_PATH with the path to your repository directory.

    The [trusted=yes] option allows APT to use the repository without GPG key verification.

  7. Update the packages:

    sudo apt-get update

  8. Install the HCD packages:

    sudo apt-get install hcd

Start HCD

Single-node cluster installations

  1. Start HCD:

    sudo service hcd start

  2. Verify that HCD is running:

    nodetool status
    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

  1. Repeat the installation steps on all nodes.

  2. Start HCD on each node:

    sudo service hcd start

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

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