Installing Stargate with an existing Cassandra cluster

Stargate can be installed alongside an existing Cassandra cluster.

Using Stargate with Cassandra 3.11

If you are looking to just get started, DataStax Astra Database-as-a-Service can get you started with no install steps.

Pull the Docker image

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

Starting Stargate with existing Cassandra cluster

To illustrate how a Cassandra cluster can be started, and thus exist before a Stargate node is added, a single node could be started with:

docker network create cass-net --driver bridge

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

Here, a network is created with docker. Then a Cassandra node is started on that network, specifying a cluster name. Additional Cassandra nodes could be added to the cluster, if desired.

Now Stargate can be added to that existing Cassandra cluster operating in a containerized environment 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.0

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.

The ports align to the following services and interfaces:

Table 1. Default Port assignments for Stargate
Port Service/Interface

Port 8080

GraphQL interface for CRUD

Port 8081

REST authorization service for generating tokens

Port 8082

REST interface for CRUD

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

The full set of options are described in the starctl documentation.

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 starctl documentation.