Building Apache Cassandra 5.x

Building Apache Cassandra

The instructions provided below specify the steps to build Apache Cassandra version 5.0.2 on Linux on IBM Z for the following distributions:

• RHEL (8.8, 8.10, 9.2, 9.4, 9.5)
• SLES 15 SP6
• Ubuntu (20.04, 22.04, 24.04, 24.10)

The binary for Apache Cassandra version 5.0.2 can be downloaded from here. Binary works for basic operations however it might not work for some functionality like auditlogging as it uses chronicle packages which needs s390x support. Please note that starting of server as mentioned in Step 3 below is the only verification performed on the binary.

General Notes:

• When following the steps below please use a standard permission user unless otherwise specified.
• A directory /<source_root>/ will be referred to in these instructions, this is a temporary writable directory anywhere you'd like to place it.

1. Build and Install Apache Cassandra

1.1. Build using script

If you want to build Cassandra using manual steps, go to STEP 1.2.

Use the following commands to build Cassandra using the build script. Please make sure you have wget installed.

wget -q https://raw.githubusercontent.com/linux-on-ibm-z/scripts/master/ApacheCassandra/5.0.2/build_cassandra.sh

# Build Cassandra
bash build_cassandra.sh   [Provide -j for java to use [OpenJDK11, Temurin11, OpenJDK17, Temurin17], -t for executing build with tests]

If the build completes successfully, go to STEP 3. In case of error, check logs for more details or go to STEP 1.2 to follow manual build steps.

1.2. Install dependencies

export SOURCE_ROOT=/<source_root>/

• RHEL (8.8, 8.10)

  sudo yum install -y curl git which gcc-c++ make automake autoconf libtool libstdc++ tar wget patch words libXt-devel libX11-devel unzip python39-devel procps gawk maven

• RHEL (9.2, 9.4, 9.5)

  sudo yum install -y curl ant junit ant-junit git which gcc-c++ make automake autoconf libtool libstdc++ tar wget patch words libXt-devel libX11-devel texinfo unzip python3-devel maven procps gawk

• SLES 15 SP6

  sudo zypper install -y gzip curl git which make wget tar zip unzip gcc-c++ patch libtool automake autoconf ccache xorg-x11-proto-devel xorg-x11-devel alsa-devel cups-devel libstdc++6-locale glibc-locale libstdc++-devel libXt-devel libX11-devel texinfo python3-devel maven

• Ubuntu (20.04, 22.04, 24.04, 24.10)

  sudo apt-get install -y curl ant ant-optional junit git tar g++ make automake autoconf libtool wget patch libx11-dev libxt-dev pkg-config texinfo locales-all unzip python3-dev maven

1.3. Install python (Only for RHEL, SLES and Ubuntu (24.04, 24.10))

wget -q https://raw.githubusercontent.com/linux-on-ibm-z/scripts/master/Python3/3.11.0/build_python3.sh
bash build_python3.sh -y

1.4. Install netty-tcnative

cd $SOURCE_ROOT
wget -q https://raw.githubusercontent.com/linux-on-ibm-z/scripts/master/ApacheCassandra/5.0.2/patch/build_netty.sh
bash build_netty.sh -y  # Provide -j for java to use [OpenJDK11, Temurin11, OpenJDK17, Temurin17]

1.5. Install Java

• With Eclipse Adoptium Temurin Runtime

  • Download and install Eclipse Adoptium Temurin Runtime (Java 11 or 17) from here.

• With OpenJDK 11

  • RHEL

    sudo yum install -y java-11-openjdk-devel

  • SLES

    sudo zypper install -y java-11-openjdk-devel

  • Ubuntu

    sudo apt-get install -y openjdk-11-jdk

• With OpenJDK 17

  • RHEL

    sudo yum install -y java-17-openjdk-devel

  • SLES

    sudo zypper install -y java-17-openjdk-devel

  • Ubuntu

    sudo apt-get install -y openjdk-17-jdk

Note: Version jdk-11.0.20.1+1 and jdk-17.0.13+11 was used for Eclipse Adoptium Temurin Runtime while verifying these instructions.

1.6. Set JAVA_HOME

export JAVA_HOME=/<path to java>/
export PATH=$JAVA_HOME/bin:$PATH

1.7. Build netty

cd $SOURCE_ROOT
git clone -b netty-4.1.68.Final  https://github.com/netty/netty.git
cd netty
curl -sSL https://raw.githubusercontent.com/linux-on-ibm-z/scripts/master/ApacheCassandra/5.0.2/patch/netty.patch | git apply
mvn install -DskipTests -Dmaven.javadoc.skip=true -Dos.detected.classifier=linux-s390_64-fedora #only for RHEL
mvn install -DskipTests -Dmaven.javadoc.skip=true -Dos.detected.classifier=linux-s390_64-suse #only for sles
mvn install -DskipTests -Dmaven.javadoc.skip=true -Dshow.os.detection=true #only for ubuntu

1.8. Install Ant (Only for RHEL 8.x and SLES 15.x)

cd $SOURCE_ROOT
export ANT_HOME=/opt/ant
sudo mkdir -p "$ANT_HOME"
curl -SL -o ant.tar.gz https://archive.apache.org/dist/ant/binaries/apache-ant-1.10.4-bin.tar.gz
sudo tar -xvf ant.tar.gz -C "$ANT_HOME" --strip-components=1
export PATH=$ANT_HOME/bin:$PATH

1.9. Set environment variables

export LANG="en_US.UTF-8"
export JAVA_TOOL_OPTIONS="-Dfile.encoding=UTF8"
export CASSANDRA_USE_JDK11=true
export LD_LIBRARY_PATH=$SOURCE_ROOT/netty-tcnative/boringssl-static/target/native-jar-work/META-INF/native/:$SOURCE_ROOT/netty/transport-native-epoll/target/classes/META-INF/native/

Create the necessary links

sudo ldconfig
sudo ldconfig /usr/local/lib64

1.10. Download Apache Cassandra source code

cd $SOURCE_ROOT/
git clone -b cassandra-5.0.2 https://github.com/apache/cassandra.git
cd cassandra
curl -sSL https://raw.githubusercontent.com/linux-on-ibm-z/scripts/master/ApacheCassandra/5.0.2/patch/cassandra.patch | git apply

1.11. Build

cd $SOURCE_ROOT/cassandra
ant

Copy cassandra to /usr/local/

sudo cp -r "$SOURCE_ROOT/cassandra" "/usr/local/"
export PATH=/usr/local/cassandra/bin:$PATH

2. Run test suite (Optional)

cd $SOURCE_ROOT/cassandra/
ant test

Note:
1: If build fails with JavaHeap size issue then set ANT_OPTS="-Xms4G -Xmx4G"

2: In case AuditLoggerTest test fails , delete file ./audit/metadata.cq4t and re-run the test.

3: Several timeout tests and related failures can be addressed by re-running tests after changing the timeout and key_cache_size_in_mb value as follows:

echo "key_cache_size_in_mb: 12" >> "${SOURCE_ROOT}/cassandra/test/conf/cassandra.yaml"
sed -i '/name="test.timeout"/ s/value.*/value="900000" \/>/' "${SOURCE_ROOT}/cassandra/build.xml"

4: To run individual test, use following command:

ant test -Dtest.name=xxx

For example, if org.apache.cassandra.io.sstable.IndexSummaryManagerTest fails, you can execute the individual test by:

ant test -Dtest.name=IndexSummaryManagerTest

3. Start Cassandra Server (Optional)

cassandra -f

Note: In case of an error no permission to create directory /usr/local/cassandra/bin/../data/data, modify the ownership as follows:

   sudo chown -R "$USER" "/usr/local/cassandra"

Start an interactive client as follows in another session after the server is ready

cqlsh
Connected to Test Cluster at 127.0.0.1:9042
[cqlsh 6.2.0 | Cassandra 5.0.2-SNAPSHOT | CQL spec 3.4.7 | Native protocol v5]
Use HELP for help.

Type in the following commands:

cqlsh> SELECT cluster_name, listen_address FROM system.local;

 cluster_name | listen_address
--------------+----------------
 Test Cluster |     127.0.0.1

(1 rows)

cqlsh> -- Create a keyspace
cqlsh> CREATE KEYSPACE IF NOT EXISTS store WITH REPLICATION = { 'class' : 'SimpleStrategy', 'replication_factor' : '1' };

cqlsh> -- Create a table
cqlsh> CREATE TABLE IF NOT EXISTS store.shopping_cart (
     userid text PRIMARY KEY,
     item_count int,
     last_update_timestamp timestamp
     );

cqlsh> -- Insert some data
cqlsh> INSERT INTO store.shopping_cart
     (userid, item_count, last_update_timestamp)
     VALUES ('9876', 2, toTimeStamp(now()));
cqlsh> INSERT INTO store.shopping_cart
     (userid, item_count, last_update_timestamp)
     VALUES ('1234', 5, toTimeStamp(now()));

cqlsh> SELECT * FROM store.shopping_cart;

 userid | item_count | last_update_timestamp
--------+------------+---------------------------------
   1234 |          5 | 2024-04-02 08:01:10.009000+0000
   9876 |          2 | 2024-04-02 08:01:02.315000+0000

(2 rows)
cqlsh>

If your session looks similar to what's above, your single node cluster is operational!

References:

• http://cassandra.apache.org/
• https://cassandra.apache.org/doc/latest/cassandra/getting_started/index.html
• https://cassandra.apache.org/doc/latest/cassandra/getting_started/querying.html