site-content/source/modules/ROOT/pages/development/ci.adoc

:page-layout: basic

== CI Environments

=== About CI testing and Apache Cassandra

Cassandra can be automatically tested using various test suites, that
are either implemented based on JUnit or the
https://github.com/apache/cassandra-dtest[dtest] scripts written in
Python. As outlined in `testing`, each kind of test suite addresses a
different way to test Cassandra. Eventually, all of the tests will be
executed together on the CI platform at
https://builds.apache.org[builds.apache.org], running
http://jenkins-ci.org[Jenkins].

=== Setting up your own Jenkins server

Jenkins is an open source solution that can be installed on a large
number of platforms. Setting up a custom Jenkins instance for Cassandra
may be desirable for users who have hardware to spare, or organizations
that want to run Cassandra tests for custom patches before contribution.

Please refer to the Jenkins download and documentation pages for details
on how to get Jenkins running, possibly also including slave build
executor instances. The rest of the document will focus on how to setup
Cassandra jobs in your Jenkins environment.

==== Required plugins

In addition, the following plugins need to be installed along with the standard
plugins (git, ant, ..).

You can install any missing plugins using the install manager.

Go to `Manage Jenkins -> Manage Plugins -> Available` and install the
following plugins and respective dependencies:

* Job DSL
* Javadoc Plugin
* description setter plugin
* Throttle Concurrent Builds Plug-in
* Test stability history
* Post Build Script

==== Setup seed job

. Config `New Item`

* Name it `Cassandra-Job-DSL`
* Select `Freestyle project`

. Under `Source Code Management` select Git using the repository:
`https://github.com/apache/cassandra-builds`

. Under `Build`, confirm `Add build step` -> `Process Job DSLs` and enter
at `Look on Filesystem`: `jenkins-dsl/cassandra_job_dsl_seed.groovy`

Generated jobs will be created based on the Groovy script's default
settings. You may want to override settings by checking
`This project is parameterized` and add `String Parameter` for on the
variables that can be found in the top of the script. This will allow
you to setup jobs for your own repository and branches (e.g. working
branches).

[arabic, start=4]
. When done, confirm "Save".

You should now find a new entry with the given name in your project
list. However, building the project will still fail and abort with an
error message "Processing DSL script
cassandra_job_dsl_seed.groovy ERROR: script not yet approved for use".
Go to `Manage Jenkins` -> `In-process Script Approval` to fix this issue.
Afterwards you should be able to run the script and have it generate
numerous new jobs based on the found branches and configured templates.

Jobs are triggered by either changes in Git or are scheduled to execute
periodically, e.g. on daily basis.
Jenkins will use any available executor with the label "cassandra", once the job
is to be run.
Please make sure to make any executors available by selecting
`Build Executor Status` -> `Configure` -> Add "`cassandra`" as label and
save.

Executors need to have "JDK 1.8 (latest)" installed. This is done under
`Manage Jenkins -> Global Tool Configuration -> JDK Installations…`.
Executors also need to have the `virtualenv` package installed on their
system.

=== CircleCI

Cassandra ships with a default https://circleci.com[CircleCI]
configuration to enable running tests on your branches.
Go to the CircleCI website, click "Login" and log in with your github account.
Then give CircleCI permission to watch your repositories.

Once you have done that, you can optionally configure CircleCI to run
tests in parallel if you wish:

[arabic,start=1]
. Click `Projects` and select your github account, and then click the settings for your project.
. Set the parallelism setting. If you leave the default value of 1
for Cassandra, only `ant eclipse-warnings` and `ant test` will be run.
If you change the value to 4, Circle CI also runs `ant long-test`,
`ant test-compression` and `ant stress-test`.