Installation¶
There are a number of ways to install Elassandra: from the tarball, with the deb package 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/v2.4.2-10/elassandra-2.4.2.tar.gz
Then extract its content:
tar -xzf elassandra-2.4.2.tar.gz
Go to the extracted directory:
cd elassandra-2.4.2
If you need, configure conf/cassandra.yaml
(cluster name, listen address, snitch, ...), then start elassandra:
bin/cassandra -f -e
This starts an Elassandra instance in foreground, with ElasticSearch enabled. Afterwards your node is reachable on localhost on port 9042 (CQL) and 9200 (HTTP). Keep this terminal open and launch a new one.
To use cqlsh, we first need to install the Cassandra driver for python. Ensure python and pip are installed, then:
sudo pip install cassandra-driver
Now connect to the node with cqlsh:
bin/cqlsh
Then you must be able to type CQL commands. See the CQL reference.
Also, we started Elassandra with ElasticSearch enabled (according to the -e
option), so let’s request the REST 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" : "2.4.2", "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 ready for playing with Elassandra. For instance, try to index a document with the ElasticSearch API, then from cqlsh look for the keyspace/table/row automatically created. Cassandra now benefits from dynamic mapping !
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 package¶
Our packages are hosted on packagecloud.io. Elassandra can be downloaded using an APT repository.
Note
Elassandra requires Java 8 to be installed.
Import the GPG Key¶
Download and install the public signing key:
curl -L https://packagecloud.io/elassandra/latest/gpgkey | sudo apt-key add -
Install Elassandra from the APT repository¶
Ensure apt is able to use https:
sudo apt-get install apt-transport-https
Add the Elassandra repository to your source list:
echo "deb https://packagecloud.io/elassandra/latest/debian jessie main" | sudo tee -a /etc/apt/sources.list.d/elassandra.list
Update apt cache and install Elassandra:
sudo apt-get update
sudo apt-get install elassandra
Warning
You should uninstall Cassandra prior to install Elassandra cause the two packages conflict.
Install extra tools¶
Also install Python, pip, and cassandra-driver:
sudo apt-get update && sudo apt-get install python python-pip
sudo pip install cassandra-driver
Usage¶
This package installs a systemd service named cassandra, but do not start nor enable it. For those who don’t have systemd, a init.d script is also provided.
To start elassandra using systemd, run:
sudo systemctl start cassandra
Files locations:
/etc/cassandra
: configurations/var/lib/cassandra
: database storage/var/log/cassandra
: logs/usr/share/cassandra
: plugins, modules,cassandra.in.sh
, lib...
RPM package¶
Our packages are hosted on packagecloud.io. Elassandra can be downloaded using a RPM repository.
Note
Elassandra requires Java 8 to be installed.
Setup the RPM repository¶
Create a file called elassandra.repo
in the directory /etc/yum.repos.d/
(redhat) or /etc/zypp/repos.d/
(opensuse), containing:
[elassandra_latest]
name=Elassandra repository
baseurl=https://packagecloud.io/elassandra/latest/el/7/$basearch
type=rpm-md
repo_gpgcheck=1
gpgcheck=0
enabled=1
gpgkey=https://packagecloud.io/elassandra/latest/gpgkey
autorefresh=1
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt
Install Elassandra¶
Using yum:
sudo yum install elassandra
Warning
You should uninstall Cassandra prior to install Elassandra cause the two packages conflict.
Install extra tools¶
Also install Python, pip, and cassandra-driver:
sudo yum install python python-pip
sudo pip install cassandra-driver
Usage¶
This package installs a systemd service named cassandra, but do not start nor enable it. For those who don’t have systemd, a init.d script is also provided.
To start elassandra using systemd, run:
sudo systemctl start cassandra
Files locations:
/etc/cassandra
: configurations/var/lib/cassandra
: database storage/var/log/cassandra
: logs/usr/share/cassandra
: plugins, modules,cassandra.in.sh
, lib...
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.
Start an elassandra server instance¶
Starting an Elassandra instance is simple:
docker run --name some-elassandra -d strapdata/elassandra
...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
.
Connect to Cassandra from an application in another Docker container¶
This image exposes the standard Cassandra ports and the HTTP ElasticSearch port (9200), 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
Make a cluster¶
Using the environment variables documented below, there are two cluster scenarios: instances on the same machine and instances on separate machines. For the same machine, start the instance as described above. To start other instances, just tell each new node where the first is.
docker run --name some-elassandra2 -d -e CASSANDRA_SEEDS="$(docker inspect --format='{{ .NetworkSettings.IPAddress }}' some-elassandra)" elassandra
... where some-elassandra
is the name of your original Elassandra container,
taking advantage of docker inspect
to get the IP address of the other container.
Or you may use the docker run --link
option to tell the new node where
the first is:
docker run --name some-elassandra2 -d --link some-elassandra:elassandra elassandra
For separate machines (ie, two VMs on a cloud provider), you need to tell Elassandra what IP address to advertise to the other nodes (since the address of the container is behind the docker bridge).
Assuming the first machine’s IP address is 10.42.42.42
and the
second’s is 10.43.43.43
, start the first with exposed gossip port:
docker run --name some-elassandra -d -e CASSANDRA_BROADCAST_ADDRESS=10.42.42.42 -p 7000:7000 elassandra
Then start an Elassandra container on the second machine, with the exposed gossip port and seed pointing to the first machine:
docker run --name some-elassandra -d -e CASSANDRA_BROADCAST_ADDRESS=10.43.43.43 -p 7000:7000 -e CASSANDRA_SEEDS=10.42.42.42 elassandra
Container shell access and viewing Cassandra logs¶
The docker exec
command allows you to run commands inside a Docker
container. The following command line will give you a bash shell inside
your elassandra
container:
$ docker exec -it some-elassandra bash
The Cassandra Server log is available through Docker’s container log:
$ docker logs some-elassandra
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. We already have seen some of them.
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. |
Build from source¶
- Requirements:
- Oracle JDK 1.8 or OpenJDK 8
- maven >= 3.5
Clone Elassandra repository and Cassandra sub-module:
git clone --recursive git@github.com:strapdata/elassandra.git
cd elassandra
Elassandra uses Maven for its build system. Simply run:
mvn clean package -DskipTests
It’s gonna take a while, you might go for a cup of tea.
If everything succeed, tarballs will be built in:
distribution/tar/target/release/elasandra-2.4.2-SNAPSHOT.tar.gz distribution/zip/target/release/elasandra-2.4.2-SNAPSHOT.zip
Then follow the instructions for tarball installation.