This project provides the Stargate Docs API - an HTTP service that gives access to data stored in a Cassandra cluster using JSON Document based interface. (As part of Stargate V2, this service was extracted from the monolithic Stargate V1 Coordinator as a separate microservice.)
The project depends on the sgv2-quarkus-common module, which provides common functionality used by all Stargate V2 APIs.
The high-level design of the application is described in the Document API in Stargate V2 discussion.
All issues related to this project are marked with the stargate-v2 and documents API labels.
Please read the Stargate V2 Shared Concepts in order to get basic concepts shared between all V2 API implementations.
The Stargate Docs API V2 supports open-source Cassandra 3.11.x and 4.0.x lines, with a limitation of using the Murmur3Partitioner, ByteOrderedPartitioner or OrderPreservingPartitioner at the data store.
Other partitioners have limited support, and if used, will result in inability to properly search collections using $or conditions.
All other features are supported regardless of the partitioner used.
This limitation will be removed with the release of Cassandra 4.2.0.
The Docs API service is packaged as a Docker image available on Docker Hub. For examples of container-based deployments, see the docker-compose or helm folders.
The Docs API is also packaged as an uber-jar as part of Stargate v2 releases, along with the accompanying start-docsapi.sh script.
The startup script can also be used to start the uber-jar locally, along with other options documented in the Development Guide.
There are two main configuration property prefixes used, stargate. and quarkus..
The quarkus. properties are defined by the Quarkus framework, and the complete list of available properties can be found on the All configuration options page.
In addition, the related guide of each Quarkus extension used in the project provides an overview of the available config options.
The stargate. properties are defined by this project itself and by the sgv2-quarkus-common configuration.
The properties are defined by dedicated config classes annotated with the @ConfigMapping.
The list of currently available properties is documented in the Configuration Guide.
This project uses Quarkus, the Supersonic Subatomic Java Framework. If you want to learn more about Quarkus, please visit its website.
It's recommended that you install Quarkus CLI in order to have a better development experience. See CLI Tooling for more information.
Warning This project uses Java 17, please ensure that you have the target JDK installed on your system.
Before being able to run the application, make sure you install the root ../apis/pom.xml:
cd ../
./mvnw install -DskipTestsTo run your application in dev mode with live coding enabled, use the command:
../mvnw quarkus:devBy default, the application is served on port 8180.
Note
Quarkus now ships with a Dev UI, which is available in dev mode only at http://localhost:8180/stargate/dev/.
In development mode, Quarkus starts by default with debug mode enabled, listening to port 5005 without suspending the JVM.
You can attach the debugger at any point, the simplest option would be from IntelliJ using Run -> Attach to Process.
If you wish to debug from the start of the application, start with -Ddebug=client and create a debug configuration in a Listen to remote JVM mode.
See Debugging for more information.
Warning
You need to build the coordinator docker image(s) first. In the Stargate repo directory/apisrun:../mvnw clean install -P dse -DskipTests && ./build_docker_images.sh
Integration tests are using the Testcontainers library in order to set up all needed dependencies, a Stargate coordinator and a Cassandra data store.
They are separated from the unit tests and are running as part of the integration-test and verify Maven phases:
../mvnw integration-testDepending on the active profile, integration tests will target different Cassandra version as the data store. The available profiles are:
cassandra-40(enabled by default) - runs integration tests with Cassandra 4.0 as the data storecassandra-311- runs integration tests with Cassandra 3.11 as the data storedse-68- runs integration tests with DataStax Enterprise (DSE) 6.8 as the data store
The required profile can be activated using the -P option:
../mvnw integration-test -P cassandra-311Warning
You need to build the coordinator docker image(s) first. In the Stargate repo directory/apisrun:../mvnw clean install -P dse -DskipTests && ./build_docker_images.sh
Running integration tests from an IDE is supported out of the box. The tests will use the Cassandra 4.0 as the data store by default. Running a test with a different version of the data store or the Stargate coordinator requires changing the run configuration and specifying the following system properties:
testing.containers.cassandra-image- version of the Cassandra docker image to use, for example:cassandra:4.0.4testing.containers.stargate-image- version of the Stargate coordinator docker image to use, for example:stargateio/coordinator-4_0:v2.0.0-ALPHA-10-SNAPSHOT(must be V2 coordinator for the target data store)testing.containers.cluster-version- version of the cluster, for example:4.0(should be one of3.11,4.0or6.8)testing.containers.cluster-dse- optional and only needed if DSE is used
The integration tests can also be executed against an already running instance of the application.
This can be achieved by setting the quarkus.http.test-host system property when running the tests.
You'll most likely need to specify the authentication token to use in the tests, by setting the stargate.int-test.auth-token system property.
./mvnw verify -DskipUnitTests -Dquarkus.http.test-host=1.2.3.4 -Dquarkus.http.test-port=4321 -Dstargate.int-test.auth-token=[AUTH_TOKEN]
You can skip the integration tests during the maven build by disabling the int-tests profile using the -DskipITs property:
../mvnw verify -DskipITsAlternatively you may want to run only integration tests but not unit tests (especially when changing integration tests). This can be achieved using the command:
../mvnw verify -DskipUnitTests
If your Integration Test run fails with some generic, non-descriptive error like:
[ERROR] CollectionsResourceIntegrationTest » Runtime java.lang.reflect.InvocationTargetException
here are some things you should try:
- Make sure your Docker Engine has enough resources. For example following have been observed:
- Docker Desktop defaults of 2 gigabytes of memory on Mac are not enough: try at least 4
The application can be packaged using:
../mvnw packageThis command produces the quarkus-run.jar file in the target/quarkus-app/ directory.
Be aware that it’s not an über-jar as the dependencies are copied into the target/quarkus-app/lib/ directory.
The application is now runnable using java -jar target/quarkus-app/quarkus-run.jar.
If you want to build an über-jar, execute the following command:
../mvnw package -Dquarkus.package.type=uber-jarThe application, packaged as an über-jar, is now runnable using java -jar target/*-runner.jar.
You can create a native executable using the command:
../mvnw package -PnativeOr, if you don't have GraalVM installed, you can run the native executable build in a container using the command:
../mvnw package -Pnative -Dquarkus.native.container-build=trueYou can then execute your native executable with the command:
./target/sgv2-docsapi-${project.version}-runner`
To learn more about building native executables, please consult the Maven tooling guide.
You can create a Docker image named io.stargate/docsapi using:
../mvnw clean package -Dquarkus.container-image.build=trueOr, if you want to create a native-runnable Docker image named io.stargate/docsapi-native using:
../mvnw clean package -Pnative -Dquarkus.native.container-build=true -Dquarkus.container-image.build=trueIf you want to learn more about building container images, please consult Container images.
This project uses various Quarkus extensions, modules that run on top of a Quarkus application.
You can list, add and remove the extensions using the quarkus ext command.
Note Please check the shared extensions introduced by the sgv2-quarkus-common project.
The Quarkus DI solution.
The project uses Docker for building the Container images. Properties for Docker image building are defined in the pom.xml file. Note that under the hood, the generated Dockerfiles under src/main/docker are used when building the images. When updating the Quarkus version, the Dockerfiles must be re-generated.
The extension setups the health endpoints under /stargate/health.
The OpenAPI definitions are generated and available under /api/docs/openapi endpoint.
The StargateDocsApi class defines the @OpenAPIDefinition annotation.
This definition defines the default SecurityScheme named Token, which expects the header based authentication with the HTTP Header X-Cassandra-Token.
The info portions of the Open API definitions are set using the quarkus.smallrye-openapi.info- configuration properties.