Cassandra 3.x

If you’re looking to just get started, you can try DataStax Astra DB and skip the installation steps.

The base URL will be https://DATABASE_ID-REGION.apps.astra.datastax.com/api/rest/v2. See the FAQ to learn where to find your DATABASE_ID and REGION.

There are several ways that Stargate can be used with Apache Cassandra.

  • If you are a developer who just needs a simple platform to test out ideas, you can:

  • If you already have Cassandra running in a docker-compose application, or want to start Stargate with multiple nodes of Cassandra, installing with docker-compose is a simple method.

  • If you need to install Stargate with a running Cassandra cluster in either virtual machines or bare metal, use the method that downloads a zip file of Stargate jar files and install.

Notification of deprecation and schedule to remove

Cassandra 3.11 Persistence Backend - According to the Cassandra documentation, the 3.11 release is currently the "Previous Stable Version" scheduled for maintenance until 5.0 is released in mid-2023. Since Cassandra 3.11 has a dependency on Java 8, removal of the 3.11 persistence backend would allow the build of the coordinator modules to be updated to Java 11 (for Cassandra 4.x) and to use a Java 11 base Docker image. Thus, the Cassandra 3.11 persistence module is being deprecated and scheduled for removal in Stargate v3.

Once you have installed Stargate, you are ready to try one of the Stargate QuickStarts.

Stargate Standalone with Docker

v2

For Stargate v2, you’ll need to pull an image for coordinator, plus an image for each API that you wish to run: restapi, graphql, and docsapi. The coordinator image contains a Apache Cassandra™ backend, the Cassandra Query Language (CQL), and the gRPC API.

The following are the commands for each of those images using the tag v2:

docker pull stargateio/coordinator-3_11:v2
docker pull stargateio/restapi:v2
docker pull stargateio/docsapi:v2
docker pull stargateio/graphqlapi:v2
v1

This image contains the Cassandra Query Language (CQL), REST, Document, GraphQL APIs, and GraphQL Playground, along with an Apache Cassandra™ 3.11 backend.

docker pull stargateio/stargate-3_11:v1.0.57
v2

Use this docker-compose shell script to start the coordinator and APIs in developer mode. The easiest way to do that is to navigate to the <install_location>/stargate/docker-compose directory, and run the script. You will want to run, for example:

./start_cass_3_11_dev_mode.sh

This command will start using the latest available coordinator and API images with the v2 tag.

You may also select a specific image tag using the -t <image_tag> option. A list of the available tags for the coordinator can be found here.

v1

Start the Stargate container in developer mode. Developer mode removes the need to set up a separate Cassandra instance and is meant for development and testing only.

docker run --name stargate \
  -p 8080:8080 \
  -p 8081:8081 \
  -p 8082:8082 \
  -p 127.0.0.1:9042:9042 \
  -d \
  -e CLUSTER_NAME=stargate \
  -e CLUSTER_VERSION=3.11 \
  -e DEVELOPER_MODE=true \
  stargateio/stargate-3_11:v1.0.57

Ports for using Stargate

Stargate uses a number of ports, to allow users to interact with the APIs.

Stargate v2.0

Stargate v2.0 ports

The default ports assignments align to the following services and interfaces:

Port

Service/Interface

8080

GraphQL interface for CRUD

8081

REST authorization service for generating authorization tokens

8082

REST interface for CRUD

8084

Health check (/healthcheck, /checker/liveness, /checker/readiness) and metrics (/metrics)

8180

Document API interface for CRUD

8090

gRPC interface for CRUD

9042

CQL service
The port for the Document API has changed.

Stargate v1.0

Stargate v1.0 ports

The default ports assignments align to the following services and interfaces:

Port

Service/Interface

8080

GraphQL interface for CRUD

8081

REST authorization service for generating tokens

8082

REST interface for CRUD and Document API

8084

Health check (/healthcheck, /checker/liveness, /checker/readiness) and metrics (/metrics)

8090

gRPC interface for CRUD

9042

CQL service

Stargate with Docker compose

This installation method can be used to either:

  • new installation of both Cassandra and Stargate

  • add Stargate to a running Cassandra docker-compose network

New Cassandra and Stargate using docker-compose

Using docker-compose, you can also start an Apache Cassandra™ cluster or use one that is running in Docker already, to create a Cassandra plus Stargate environment. This method is different from the standalone environment, in that a separate Cassandra cluster is used for the backend storage, and is more like a production environment.

The docker-compose YAML file contains the configuration for pulling the required docker images and configuration required for installing:

  • 1-3 Apache Cassandra™ 3.11 nodes as a cluster (backend-1, backend-2, backend-3)

  • v2: 1 Stargate coordinator, plus desired APIs (by default, all are installed)

  • v1: 1 Stargate node (stargate) The Stargate image contains the Cassandra Query Language (CQL), REST, Document, GraphQL APIs, and GraphQL Playground.

There is a shell script to run the docker-compose file with delays between node startup that prevents timing issues.

v2

Use this docker-compose shell script to start the coordinator and APIs in developer mode. The easiest way to do that is to navigate to the <install_location>/stargate/docker-compose directory, and run the script. You will want to run, for example:

./start_cass_3_11.sh

This command will start using the latest available coordinator and API images with the v2 tag.

You may also select a specific image tag using the -t <image_tag> option. A list of the available tags for the coordinator can be found here.

v1

The files are found at the Stargate docker-images repository.

Run the script after downloading the files:

./start_stargate-cass311.sh
When Stargate is launched within a container on Mac OS X as shown above, it will connect only to Cassandra clusters running within the same Docker environment. To run Stargate so that it can connect to a cluster running outside of a containerized environment, see the Installing on VMs or bare metal documentation.

Adding Stargate to existing Cassandra docker-compose cluster

If a Cassandra cluster already exists that was started with docker-compose, Stargate can be added to the defined network, such as :

docker network create cass-net --driver bridge: value

[Optional] To illustrate, you can start a single Cassandra node using that network:

docker run --name cass1 \
--network cass-net \
-e CASSANDRA_CLUSTER_NAME=stargate-cluster \
-d cassandra:3.11

Note that the Cassandra node is started with a specific cluster name. Additional Cassandra nodes could be added to the cluster, if desired.

Now add Stargate to the existing Cassandra cluster operating on the specified network with the following command:

docker run --name stargate \
  --network cass-net \
  -p 8080:8080 \
  -p 8081:8081 \
  -p 8082:8082 \
  -p 9049:9042 \
  -e CLUSTER_NAME=stargate-cluster \
  -e CLUSTER_VERSION=3.11 \
  -e SEED=cass1 \
  -e SIMPLE_SNITCH=true \
  -e ENABLE_AUTH=true \
  -d stargateio/stargate-3_11:v1.0.57

where

  • cass-net must be replaced with the existing Cassandra cluster network name

  • the port 9042 should be mapped to an alternative port (example shows 9049)

  • CLUSTER_NAME identifies the Cassandra cluster name used at cluster creation

  • CLUSTER_VERSION is set to the version of Cassandra running in the cluster

  • SEED is set to the IP address or docker name of a running Cassandra seed node (cass1)

  • SIMPLE_SNITCH sets the snitch on the Stargate node

  • ENABLE_AUTH enables PasswordAuthenticator in the cluster

Use the SIMPLE_SNITCH option if the endpoint_snitch setting in the cluster is set to SimpleSnitch. If the cluster uses a different endpoint_snitch use the --dc and --rack options to define the topology of the node.

Ports for using Stargate

Stargate uses a number of ports, to allow users to interact with the APIs.

Stargate v2.0
Stargate v2.0 ports

The default ports assignments align to the following services and interfaces:

Port

Service/Interface

8080

GraphQL interface for CRUD

8081

REST authorization service for generating authorization tokens

8082

REST interface for CRUD

8084

Health check (/healthcheck, /checker/liveness, /checker/readiness) and metrics (/metrics)

8180

Document API interface for CRUD

8090

gRPC interface for CRUD

9042

CQL service
The port for the Document API has changed.
Stargate v1.0
Stargate v1.0 ports

The default ports assignments align to the following services and interfaces:

Port

Service/Interface

8080

GraphQL interface for CRUD

8081

REST authorization service for generating tokens

8082

REST interface for CRUD and Document API

8084

Health check (/healthcheck, /checker/liveness, /checker/readiness) and metrics (/metrics)

8090

gRPC interface for CRUD

9042

CQL service

Specifying the LISTEN_ADDRESS is not required in docker, because the starctl script will determine the correct port on which to listen. The ports do not need to be set if standard ports are used.

Stargate on virtual machine or bare metal

Stargate can be installed alongside an existing Cassandra cluster using a virtual machine or bare metal.

[Optional] Make sure Cassandra is up and running. Stargate requires authentication, so be sure to enable it in the cassandra.yaml file. If you don’t have a cluster running, use these instructions to install Cassandra 3.11.

Next, prepare a virtual machine to install Stargate on. You’ll need to be sure Java 8 is installed.

Once you have a machine ready, download the Stargate zip file. This file will provide the jar files that are required to run Stargate. A typical method is using wget:

wget https://github.com/stargate/stargate/releases/download/v1.0.57/stargate-jars.zip


Unzip the files:

unzip stargate-jars.zip


Make sure that port 7000 is open on the Stargate machine. This port is the default inter-node communication port that Cassandra and Stargate use to pass communications.

Now start Stargate using the starctl command, the main command for starting and configuring Stargate:

./starctl --cluster-name <cluster name> \
 
--cluster-seed <seed node to connect to> \
 
--cluster-version <version> \
 
--listen <ip address for stargate to listen on> \
 
--dc <data center name> \
 
--rack <rack name of node to connect to> \
 
--dse #for DSE only, delete for Cassandra \
 
--enable-auth

For example:

./starctl \
--cluster-name stargate_test_cluster \
--cluster-seed 172.31.29.170 \
--cluster-version 3.11 \
--listen 172.31.29.175 \
--dc DC1 \
--rack RACK1 \
--enable-auth

where

  • stargate_test_cluster is the name of the Cassandra cluster

  • 172.31.29.170 is the IP address of the Cassandra node

  • 172.31.29.175 is the IP address of the Stargate node (Stargate uses this IP address to broadcast itself, to join a Cassandra cluster as a coordinator node)

  • DC1 is the name of the data center of the Cassandra node

  • RACK1 is the name of the data center of the Cassandra node The full set of options are described in the starctl documentation.

If you are unsure of the datacenter and rack, run nodetool status on the Cassandra node you are connected to.

After a few seconds, you should see that Stargate has started. You will see log output in your terminal display. If you get a binding error, then you may have tried to start Stargate incorrectly and the process is still running. Terminate that process and start it again.

That’s it! You are ready to try a Stargate QuickStart.