Installing Apache Cassandra on Debian 11 – Step‑by‑Step
If you want a lightweight NoSQL engine on a fresh Debian 11 box, Cassandra is a solid choice. This guide walks through the exact steps to get it up and running, plus a few quick fixes for common hiccups.
Installing Java – The Foundation
sudo apt update && sudo apt install -y openjdk-11-jdk
Cassandra needs a Java runtime; Debian 11 ships with OpenJDK 11 which is fully compatible. Skipping this step and trying to start Cassandra later will just give you a cryptic “Java not found” error.
Adding the Apache Cassandra Repository
wget -qO - https://www.apache.org/dist/cassandra/KEYS | sudo apt-key add -
echo "deb http://www.apache.org/distro/cassandra/debian 11 main" | \
sudo tee /etc/apt/sources.list.d/cassandra.list
sudo apt update
Using the official repo guarantees you get the latest stable build and the proper package dependencies. If you skip adding the key, Debian’s package manager will refuse to install anything with a warning that the source is untrusted.
Installing Cassandra
sudo apt install -y cassandra
That’s it for the bulk of the work. The installer pulls in cassandra, sets up the service, and creates the default user/group.
Quick sanity check
ps aux | grep cassandra systemctl status cassandra
If you see a process listening on 9042 (the CQL port) or the service reports “active (running)”, you’re good to go. If not, check the logs:
journalctl -u cassandra --since "10 minutes ago"
I’ve seen this happen after a bad driver update that leaves your Java path broken, causing Cassandra to fail at boot. In that case, make sure JAVA_HOME is set correctly or reinstall OpenJDK.
Tweaking the Configuration
The main config lives in /etc/cassandra/conf/cassandra.yaml. Common adjustments include:
- cluster_name – give it a descriptive name so you can tell your cluster apart from a test instance.
- listen_address – change from auto to the server’s IP if you’re running multiple nodes on the same machine or behind NAT.
- endpoint_snitch – set to GossipingPropertyFileSnitch for most setups; it discovers node locations.
After editing, restart:
sudo systemctl restart cassandra
Enabling Cassandra to Start at Boot
Debian installs the service with autostart enabled by default. Double‑check:
sudo systemctl enable cassandra
If you ever need to disable it (say for a temporary test), you can do so without uninstalling.
Using CQL Shell
The bundled cqlsh lets you run commands directly against your cluster:
cqlsh localhost 9042
You can create keyspaces, tables, and insert data right away. If the connection refuses, verify that port 9042 isn’t blocked by a firewall.
Common Pitfalls
- Java version mismatch – Cassandra 4.x won’t run on Java 8. Use java -version to double‑check.
- Wrong cluster name in cassandra.yaml – If you’re joining an existing cluster, the name must match exactly, otherwise nodes will refuse to connect.
- Insufficient heap – The default JVM options set a heap of around 512 MB. For production, tweak MAX_HEAP_SIZE and HEAP_NEWSIZE in /etc/cassandra/conf/jvm.options.
Wrap‑up
You now have a working Cassandra installation on Debian 11, ready to ingest data or experiment with clustering. If you hit snags, the logs are your best friend; they usually point straight at the misconfiguration.
