= Installing Cassandra

Apache Cassandra can be installed on a number of Linux distributions:

* AlmaLinux
* Amazon Linux Amazon Machine Images (AMIs)
* Debian
* RedHat Enterprise Linux (RHEL)
* SUSE Enterprise Linux
* Ubuntu

This is not an exhaustive list of operating system platforms, nor is it prescriptive.
However, users are well-advised to conduct exhaustive tests if using a less-popular distribution of Linux.
Deploying on older Linux versions is not recommended unless you have previous experience with the older distribution in a production environment.

== Prerequisites

* Install the latest version of Java 11 or Java 17, from one of the following locations:
** https://www.oracle.com/java/technologies/javase/jdk11-archive-downloads.html[Oracle Java Standard Edition 11 Archived Version]
** https://www.oracle.com/java/technologies/downloads/#java17[Oracle Java Standard Edition 17]
** https://jdk.java.net/archive/[OpenJDK 11]
** https://jdk.java.net/archive/[OpenJDK 17]

include::cassandra:partial$java_version.adoc[]

* To use the CQL shell `cqlsh`, install the latest version of Python 3.8-3.11.

To verify that you have the correct version of Python installed, type `python --version`.

[NOTE]
====
Support for Python 2.7 is deprecated.
====

== Choosing an installation method

There are three methods of installing Cassandra that are common:

* Docker image
* Tarball binary file
* Package installation (RPM, YUM)

If you are a current Docker user, installing a Docker image is simple.
You'll need to install Docker Desktop for Mac, Docker Desktop for Windows, or have `docker` installed on Linux.
Pull the appropriate image from the Docker Hub and start Cassandra with a `docker run` command.

For many users, installing the binary tarball is also a simple choice.
The tarball unpacks all its contents into a single location with binaries and configuration files located in their own subdirectories.
The most obvious advantage of a tarball installation is that it does not require `root` permissions and can be installed on any Linux
distribution.

Packaged installations require `root` permissions, and are most appropriate for production installs.
Install the RPM build on CentOS and RHEL-based distributions if you want to install Cassandra using YUM.
Install the Debian build on Ubuntu and other Debian-based distributions if you want to install Cassandra using APT.

[WARNING]
====
Note that both the YUM and APT methods required `root` permissions and will install the binaries and configuration files as the `cassandra` OS user.
====

== Install with Docker

. Pull the docker image. For the latest image, use:
+
[source, shell]
----
include::cassandra:example$BASH/docker_pull.sh[]
----
+
This `docker pull` command will get the latest version of the official Docker
Apache Cassandra image available from the https://hub.docker.com/_/cassandra[Dockerhub].
. Start Cassandra with a `docker run` command:
+
[source, shell]
----
include::cassandra:example$BASH/docker_run.sh[]
----
+
The `--name` option will be the name of the Cassandra cluster created.
This example uses the name `cass_cluster`.
. Start the CQL shell, `cqlsh` to interact with the Cassandra node created:
+
[source, shell]
----
include::cassandra:example$BASH/docker_cqlsh.sh[]
----

== Install tarball file

include::cassandra:partial$java_version.adoc[]

. Download the binary tarball from one of the mirrors on the {cass_url}download/[Apache Cassandra Download] site.
For example, to download Cassandra {40_version}:
+
[source,shell]
----
include::cassandra:example$BASH/curl_install.sh[]
----
+
[NOTE]
====
The mirrors only host the latest versions of each major supported release.
To download an earlier version of Cassandra, visit the https://archive.apache.org/dist/cassandra/[Apache Archives].
====
. OPTIONAL: Verify the integrity of the downloaded tarball using one of the methods https://www.apache.org/dyn/closer.cgi#verify[here].
For example, to verify the hash of the downloaded file using GPG:
+
[tabs]
====
Command::
+
--
[source,shell]
----
include::cassandra:example$BASH/verify_gpg.sh[]
----
--

Result::
+
--
[source,plaintext]
----
include::cassandra:example$RESULTS/verify_gpg.result[]
----
--
====
+
Compare the signature with the SHA256 file from the Downloads site:
+
[tabs]
====
Command::
+
--
[source,shell]
----
include::cassandra:example$BASH/curl_verify_sha.sh[]
----
--

Result::
+
--
[source,console]
----
include::example$RESULTS/curl_verify_sha.result[]
----
--
====
. Unpack the tarball:
+
[source,shell]
----
include::cassandra:example$BASH/tarball.sh[]
----
+
The files will be extracted to the `apache-cassandra-4.0.0/` directory.
This is the tarball installation location.
. Located in the tarball installation location are the directories for the scripts, binaries, utilities, configuration, data and log files:
+
[source,plaintext]
----
include::cassandra:example$TEXT/tarball_install_dirs.txt[]
----
<1> location of the commands to run cassandra, cqlsh, nodetool, and SSTable tools
<2> location of cassandra.yaml and other configuration files
<3> location of the commit logs, hints, and SSTables
<4> location of system and debug logs
<5>location of cassandra-stress tool
+
. Start Cassandra:
+
[source,shell]
----
include::cassandra:example$BASH/start_tarball.sh[]
----
+
[NOTE]
====
This will run Cassandra as the authenticated Linux user.
====
+
include::cassandra:partial$tail_syslog.adoc[]
+
include::cassandra:partial$nodetool_and_cqlsh.adoc[]

== Install as Debian package

include::cassandra:partial$java_version.adoc[]

. Add the Apache repository of Cassandra to the file `cassandra.sources.list`.
+
include::cassandra:partial$package_versions.adoc[]
+
[source,shell]
----
include::cassandra:example$BASH/get_deb_package.sh[]
----
. Add the Apache Cassandra repository keys to the list of trusted keys on the server:
+
[tabs]
====
Command::
+
--
[source,shell]
----
include::cassandra:example$BASH/add_repo_keys.sh[]
----
--

Result::
+
--
[source,plaintext]
----
include::cassandra:example$RESULTS/add_repo_keys.result[]
----
--
====
. Update the package index from sources:
+
[source,shell]
----
include::cassandra:example$BASH/apt-get_update.sh[]
----
. Install Cassandra with APT:
+
[source,shell]
----
include::cassandra:example$BASH/apt-get_cass.sh[]
----
+
include::cassandra:partial$tail_syslog.adoc[]
+
include::cassandra:partial$nodetool_and_cqlsh_nobin.adoc[]

== Install as RPM package

include::cassandra:partial$java_version.adoc[]

. Add the Apache repository of Cassandra to the file `/etc/yum.repos.d/cassandra.repo` (as the `root` user).
+
include::cassandra:partial$package_versions.adoc[]
+
[source,plaintext]
----
include::cassandra:example$RESULTS/add_yum_repo.result[]
----
. Update the package index from sources:
+
[source,shell]
----
include::cassandra:example$BASH/yum_update.sh[]
----
. Install Cassandra with YUM:
+
[source,shell]
----
include::cassandra:example$BASH/yum_cass.sh[]
----
+
[NOTE]
====
A new Linux user `cassandra` will get created as part of the installation.
The Cassandra service will also be run as this user.
====
. Start the Cassandra service:
+
[source,shell]
----
include::cassandra:example$BASH/yum_start.sh[]
----
+
include::cassandra:partial$tail_syslog.adoc[]
+
include::cassandra:partial$nodetool_and_cqlsh_nobin.adoc[]

== Further installation info

For help with installation issues, see the xref:cassandra:troubleshooting/index.adoc[Troubleshooting] section.
