stargateio/stargate-4_0

By stargateio

Updated about 1 month ago

(Stargate v1) Docker image for Stargate and a Cassandra 4.0 backend

Image
5

1M+

Stargate with Apache Cassandra 4.0

Warning: This image is for Stargate v1. For Stargate v2, see the stargateio/coordinator-4_0)image.

An open source API framework for data.

Stargate is a data gateway deployed between client applications and a database. It's built with extensibility as a first-class citizen and makes it easy to use a database for any application workload by adding plugin support for new APIs, data types, and access methods.

Introduction

We created Stargate because we got tired of using different databases and different APIs depending on the work that we were trying to get done. With "read the manual" fatigue and lengthy selection processes wearing on us every time we started a new project, we thought - why not create a framework that can serve many APIs for a range of workloads?

This project enables customization of all aspects of data access and has modules for authentication, APIs, request handling / routing, and persistence backends. The current form is specific to the Apache Cassandra (C*) backend but there's no bounds to the databases or APIs that this framework can support.

Stargate contains the following components:

  • API Services: Responsible for defining the API, handling and converting requests to db queries, dispatching to persistence, returning and serving response

    • cql: API implementation for the Cassandra Query Language
    • restapi: API implementation for exposing Cassandra data over REST
  • Persistence Services: Responsible for implementing the coordination layer to execute requests passed by API services to underlying data storage instances.

    • persistence-api: Interface for working with persistence services
    • persistence-common: Utilities shared by the persistence services
    • persistence-cassandra-3.11: Joins C* ring as coordinator only node (does not store data), mocks C* system tables for native driver integration, executes requests with C* storage nodes using C* QueryHandler/QueryProcessor, converts internal C* objects and ResultSets to Stargate Datastore objects.
  • Authentication Services: Responsible for authentication to Stargate

    • auth-api: REST service for generating auth tokens
    • auth-table-based-service: Service to store tokens in the database
    • authentication: Interface for working with auth providers

Getting started

Developer Mode

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 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-4_0:{stargate-docker-tag}

By default, Stargate starts a CQL service on port 9042, a REST auth service for generating tokens on 8081, and a REST interface for CRUD on port 8082.

Docker Compose

Examples directory contains some docker compose files for stargate with different backends (3 nodes):

Configuration

Correct settings in the environment section are essential for successful Stargate configuration.

    environment:
      # cluster name must match backend cluster name
      # version must match backend version, e.g. 3.11 / 4.0
      - CLUSTER_NAME=backend
      - CLUSTER_VERSION=4.0
      # at least one seed node
      - SEED=backend-1
      # rack and datacenter names must match backend rack name, 
      # please notice that Apache Cassandra defaults differs from DSE defaults
      - RACK_NAME=rack1
      - DATACENTER_NAME=dc1

Starting

Backend (C* or DSE) will not start immediately after container is up. This can lead to some potential issue with backend not being ready during stargate start.

docker-compose --file <compose-file.yml> up

For this reason we recommend using the wrapper script, which enforces a safe run order with backend seed nodes first and then continuing with stargate / rest of backend nodes.

Docker Pull Command

docker pull stargateio/stargate-4_0