DataStax Enterprise (DSE) 6.8

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 DataStax Enterprise.

If you are a developer who just needs a simple platform to test out ideas, you can:
- For v1, start Stargate as a developer mode with Docker.
- For v2, start Stargate with docker-compose in developer mode with Docker, that will start a Stargate coordinator that runs Cassandra, gRPC and CQL, plus the three APIs, each in its own container.
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.

At this time Stargate does not support advanced workloads such as Graph and Search. If you are using any sort of search index in the keyspace you plan to use with Stargate they will need to be removed before Stargate deployment.

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

Stargate Standalone with Docker

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-dse-68:v2
docker pull stargateio/restapi:v2
docker pull stargateio/docsapi:v2
docker pull stargateio/graphqlapi:v2

This image contains the Cassandra Query Language (CQL), REST, Document, GraphQL APIs, and GraphQL Playground, along with a DataStax Enterprise^™ 6.8 backend.

docker pull stargateio/stargate-dse-68:v1.0.57

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

Start the Stargate container in developer mode. Developer mode removes the need to set up a separate DSE 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=6.8 \
  -e DEVELOPER_MODE=true \
  stargateio/stargate-dse-68: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 DSE and Stargate
add Stargate to a running DSE docker-compose network

New DSE 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 DataStax Enterprise 6.8 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.

./start_cass_68.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.

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

Run the script after downloading the files:

./start_stargate-dse68.sh

When Stargate is launched within a container on Mac OS X as shown above, it will connect only to DSE 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.

Starting Stargate with existing DataStaxEnterprse cluster

To illustrate how a DSE 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 datastax/dse-server:6.8.9

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

Now Stargate can be added to that existing DSE 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=6.8 \
  -e SEED=cass1 \
  -e SIMPLE_SNITCH=true \
  -e ENABLE_AUTH=true \
  -d stargateio/stargate-dse-68:v1.0.57

where

cass-net must be replaced with the existing DSE cluster network name
the port 9042 should be mapped to an alternative port (example shows 9049)
CLUSTER_NAME identifies the DSE cluster name used at cluster creation
CLUSTER_VERSION is set to the version of DSE running in the cluster
SEED is set to the IP address or docker name of a running DSE 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 DSE cluster using a virtual machine or bare metal.

[Optional] Make sure DSE 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 DSE 6.8.

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 DSE 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 6.8 \  
--listen 172.31.29.175 \  
--dc DC1 \  
--rack RACK1 \  
--dse \  
--enable-auth

where

stargate_test_cluster is the name of the DSE cluster
172.31.29.170 is the IP address of the DSE node
172.31.29.175 is the IP address of the Stargate node (Stargate uses this IP address to broadcast itself, to join a DSE cluster as a coordinator node)
DC1 is the name of the data center of the DSE node
RACK1 is the name of the data center of the DSE 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 DSE 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.