Cassandra 3.x
If you are looking to just get started, DataStax Astra Database-as-a-Service can get you started with no install steps. |
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, starting Stargate as a standalone container with Docker is a good choice.
-
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.
Once you have installed Stargate, you are ready to try one of the Stargate QuickStarts.
Stargate Standalone with Docker
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.7
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.7
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) |
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
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)
-
1 Stargate node (stargate)
The Stargate image contains the Cassandra Query Language (CQL), REST, Document, GraphQL APIs, and GraphQL Playground.
Two companion files are helpful: a script to run the docker-compose file with
delays between node startup that prevents timing issues, and a text file that
has the docker run
commands for running a CQLSH Docker container to query against
either one of the Cassandra nodes or the Stargate node, respectively.
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.7
where
-
cass-net
must be replaced with the existing Cassandra cluster network name -
the port
9042
should be mapped to an alternative port (example shows9049
) -
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
enablesPasswordAuthenticator
in the cluster
Use the |
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) |
9042 |
CQL service |
Specifying the |
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.7/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 thestarctl
documentation.
If you are unsure of the datacenter and rack, run |
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.