Installation¶
There are a number of ways to install Elassandra: from the tarball, with the deb or rpm package, with a docker image, or even from source.
Elassandra is based on Cassandra and ElasticSearch, thus it will be easier if you’re already familiar with one on these technologies.
Tarball¶
Elassandra requires at least Java 8. Oracle JDK is the recommended version, but OpenJDK should work as well. You can check which version is installed on your computer:
$ java -version
java version "1.8.0_121"
Java(TM) SE Runtime Environment (build 1.8.0_121-b13)
Java HotSpot(TM) 64-Bit Server VM (build 25.121-b13, mixed mode)
Once java is correctly installed, download the Elassandra tarball:
wget https://github.com/strapdata/elassandra/releases/download/v6.2.3.8/elassandra-6.2.3.8.tar.gz
Then extract its content:
tar -xzf elassandra-6.2.3.8.tar.gz
Go to the extracted directory:
cd elassandra-6.2.3.8
Configure conf/cassandra.yaml
if necessary, then run:
bin/cassandra -e
This has started cassandra with elasticsearch enabled (according to the -e
option).
Get the node status:
bin/nodetool status
Now connect to the node with cqlsh:
bin/cqlsh
You’re now able to type CQL commands. See the CQL reference.
Check the elasticsearch API:
curl -X GET http://localhost:9200/
You should get something like:
{ "name" : "127.0.0.1", "cluster_name" : "Test Cluster", "cluster_uuid" : "7cb65cea-09c1-4d6a-a17a-24efb9eb7d2b", "version" : { "number" : "6.2.3", "build_hash" : "b0b4cb025cb8aa74538124a30a00b137419983a3", "build_timestamp" : "2017-04-19T13:11:11Z", "build_snapshot" : true, "lucene_version" : "5.5.2" }, "tagline" : "You Know, for Search" }
You’re done !
On a production environment, it’s better to modify some system settings like disabling swap. This guide shows you how to. On linux, consider installing jemalloc.
deb¶
Download the last deb package from github relases page
wget -O elassandra.deb https://github.com/strapdata/elassandra/releases/download/v6.2.3.8/elassandra-6.2.3.8.deb
Install it with dpkg tool:
sudo dpkg -i elassandra.deb
To start elassandra, just run:
sudo systemctl start cassandra
or:
sudo service cassandra start
Files locations:
/usr/bin
: startup script, cqlsh, nodetool, elasticsearch-plugin/etc/cassandra
and/etc/default/cassandra
: configurations/var/lib/cassandra
: data/var/log/cassandra
: logs/usr/share/cassandra
: plugins, modules, libs, …/usr/lib/python2.7/dist-packages/cqlshlib/
: python library for cqlsh
rpm¶
Download the last rpm package from github relases page
wget -O elassandra.rpm https://github.com/strapdata/elassandra/releases/download/v6.2.3.8/elassandra-6.2.3.8.rpm
Install it with yum:
sudo yum install elassandra.rpm
To start elassandra, just run:
sudo systemctl start cassandra
or:
sudo service cassandra start
Files locations:
/usr/bin
: startup script, cqlsh, nodetool, elasticsearch-plugin/etc/cassandra
and/etc/sysconfig/cassandra
: configurations/var/lib/cassandra
: data/var/log/cassandra
: logs/usr/share/cassandra
: plugins, modules, libs, …/usr/lib/python2.7/site-packages/cqlshlib/
: python library for cqlsh
Docker image¶
We provide an image on docker hub:
docker pull strapdata/elassandra
This image is based on the official Cassandra image whose the documentation is valid as well for Elassandra.
The source code is on github at strapdata/docker-elassandra.
Start an elassandra server instance¶
Starting an Elassandra instance is simple:
docker run --name some-elassandra -d strapdata/elassandra:tag
…where some-cassandra
is the name you want to assign to your container and tag
is the tag specifying the Elassandra version you want. Default is latest
.
Run nodetool and cqlsh:
docker exec -it some-elassandra nodetool status
docker exec -it some-elassandra cqlsh
Connect to Cassandra from an application in another Docker container¶
This image exposes the standard Cassandra and ElasticSearch ports, so container linking makes the Elassandra instance available to other application containers. Start your application container like this in order to link it to the Elassandra container:
docker run --name some-app --link some-elassandra:elassandra -d app-that-uses-elassandra
For instance, consuming the elasticsearch API from another container can be done like this:
docker run --link some-elassandra:elassandra -it strapdata/elassandra curl http//elassandra:9200
… where strapdata/elassandra
could be any image with curl
installed.
Environment Variables¶
When you start the Elassandra image, you can adjust the configuration of the Elassandra instance by passing one or more environment variables on the docker run command line.
Variable Name | Description |
---|---|
CASSANDRA_LISTEN_ADDRESS | This variable is for controlling which IP address to listen for incoming connections on. The default value is auto, which will set the listen_address option in cassandra.yaml to the IP address of the container as it starts. This default should work in most use cases. |
CASSANDRA_BROADCAST_ADDRESS | This variable is for controlling which IP address to advertise to other nodes. The default value is the value of CASSANDRA_LISTEN_ADDRESS. It will set the broadcast_address and broadcast_rpc_address options in cassandra.yaml. |
CASSANDRA_RPC_ADDRESS | This variable is for controlling which address to bind the thrift rpc server to. If you do not specify an address, the wildcard address (0.0.0.0) will be used. It will set the rpc_address option in cassandra.yaml. |
CASSANDRA_START_RPC | This variable is for controlling if the thrift rpc server is started. It will set the start_rpc option in cassandra.yaml. As Elastic search used this port in Elassandra, it will be set ON by default. |
CASSANDRA_SEEDS | This variable is the comma-separated list of IP addresses used by gossip for bootstrapping new nodes joining a cluster. It will set the seeds value of the seed_provider option in cassandra.yaml. The CASSANDRA_BROADCAST_ADDRESS will be added the the seeds passed in so that the sever will talk to itself as well. |
CASSANDRA_CLUSTER_NAME | This variable sets the name of the cluster and must be the same for all nodes in the cluster. It will set the cluster_name option of cassandra.yaml. |
CASSANDRA_NUM_TOKENS | This variable sets number of tokens for this node. It will set the num_tokens option of cassandra.yaml. |
CASSANDRA_DC | This variable sets the datacenter name of this node. It will set the dc option of cassandra-rackdc.properties. |
CASSANDRA_RACK | This variable sets the rack name of this node. It will set the rack option of cassandra-rackdc.properties. |
CASSANDRA_ENDPOINT_SNITCH | This variable sets the snitch implementation this node will use. It will set the endpoint_snitch option of cassandra.yml. |
CASSANDRA_DAEMON | The Cassandra entry-point class: org.apache.cassandra.service.ElassandraDaemon to start
with ElasticSearch enabled (default), org.apache.cassandra.service.ElassandraDaemon otherwise. |
Files locations¶
Docker elassanra image is based on the debian package installation:
/etc/cassandra
: elassandra configuration/usr/share/cassandra
: elassandra installation/var/lib/cassandra
: data (sstables, lucene segment, commitlogs, …)/var/log/cassandra
: logs files.
/var/lib/cassandra
is automatically managed as a docker volume. But it’s a good target to bind mount from the host filesystem.
Exposed ports¶
- 7000: intra-node communication
- 7001: TLS intra-node communication
- 7199: JMX
- 9042: CQL
- 9160: thrift service
- 9200: ElasticSearch HTTP
- 9300: ElasticSearch transport
Make a cluster¶
In case there is only one elassandra instance per docker host, the easiest way is to start the container with --net=host
.
When using the host network is not an option, you could just map the necessary ports with -p 9042:9042
, -p 9200:9200
and so on… but you should be aware
that docker default network will considerably slow down performances.
Also, elassandra cluster can be fully managed over a swarm cluster. But this will basically require some more customization. Feel free to open an issue on our github repository to discuss about this.
Build from source¶
- Requirements:
- Oracle JDK 1.8 or OpenJDK 8
- gradle >= 3.5
Clone Elassandra repository and Cassandra sub-module:
git clone --recursive git@github.com:strapdata/elassandra.git
cd elassandra
Elassandra 5.5+ uses Gradle for its build system. Simply run:
gradle assemble
or to build only the tgz tarball for a release version :
gradle assemble distribution:tar:assemble -Dbuild.snapshot=false
It’s gonna take a while, you might go for a cup of tea. If everything succeed, tarballs will be built in:
distribution/(tar|zip|rpm|deb)/build/distributions/
Then follow the instructions for tarball installation.