A newer version of this documentation is available.

View Latest

Installation and Configuration

A Couchbase-Elasticsearch data-replication system consists of three principal components: a Couchbase Server-cluster of one or more nodes; an Elasticsearch cluster of one or more nodes; and the Elasticsearch Transport Plug-in, installed in the Elasticsearch environment. This section provides a step-by-step procedure, whereby the three components can be installed, configured, and run.

Installation Prerequisites

The installation-procedure provided below involves the creation of a test environment, by means of Oracle VirtualBox; requiring Ubuntu 14 as operating system. For details on setting up VirtualBox on your development-machine, and deploying a Ubuntu 14 image on it, see http://virtualbox.org. The instructions in this section assume that you have completed the necessary procedures, and have supervisor-privileges in the resulting virtual environment. You will install and run Elasticsearch, the Elasticsearch Plug-in, and Couchbase Server in this environment: you should thus ensure that the virtual machine is provisioned with sufficient disk and memory resources; by means of the Settings panel, within the Oracle VM VirtualBox Manager.

Within the Ubuntu 14 environment, you will use both the terminal and the browser to perform installation and configuration. Note that within the terminal window, you may need to use supervisor-privileges, by means of the sudo command: this command, however, is not reproduced in the examples in this document; you must prepend your console-input with it, as appropriate.

Install and Configure Couchbase Server

Within the virtual environment you have created, using the browser, read and follow the installation and configuration instructions provided at Installing On-Premises. During configuration, note that for current test-purposes:

  • You need only activate the Data service. Other services are not required.

  • You require a single bucket: which is the beer-sample bucket. This bucket will be used to provide data to Elasticsearch, during the test.

Start Couchbase Server, using the instructions provided at Couchbase Server Startup and Shutdown.

Install Oracle Java

Oracle java (rather than the standard Ubuntu-available version) is required for both Elasticsearch and the plug-in. Ensure Oracle Java is added to your system, by bringing up a terminal window, and proceeding as follows:

  1. Add the required Oracle Java repository:

    $ apt-add-repository ppa:webupd8team/java
  2. Install Oracle Java, and establish it as the default Java for the virtual machine:

    $ apt-get update
    $ apt-get install oracle-java8-installer
    $ apt install oracle-java8-set-default

    During this process, when requested, accept the license-terms by selecting Ok or Yes.

    Once installation is complete, verify that Java has been successfully installed; by checking its version, with java -version; and its location, with which java.

Install Elasticsearch 2.4.0

  1. Download the Elasticsearch 2.4.0 package for Ubuntu:

    $ wget https://download.elastic.co/elasticsearch/\
    > elasticsearch/elasticsearch-2.4.0.deb
  2. Install the package:

    $ dpkg -i elasticsearch-2.4.0.deb

Install the Elasticsearch Plug-in

  1. Navigate the the Elasticsearch install directory:

    $ cd /usr/share/elasticsearch
  2. Download and install the plug-in package:

    $ bin/plugin install https://github.com/couchbaselabs/\
    > elasticsearch-transport-couchbase/releases/download/\
    > elasticsearch-transport-couchbase-

    Respond to the installation-prompts as appropriate.

    When installation is successful, the message Installed transport-couchbase into /usr/share/elasticsearch/plugins/transport/couchbase is displayed.

Configure and Start Elasticsearch

  1. In preparation for configuration-file editing, install your preferred console-based text-editor into the virtual machine environment.

    For example, download emacs, using the following command; then, as installation proceeds, respond to system-prompts as appropriate.

    $ apt-get install emacs
  2. Using the editor, bring up the configuration file for Elasticsearch:

    emacs /etc/elasticsearch/elasticsearch.yml

    Add the following to the end of the file, specifying an appropriate administrator-username and password for accessing Elasticsearch:

    couchbase.password: [password]
    couchbase.username: [username]
    couchbase.maxConcurrentRequests: 1024

    Then save the file, and exit back to the command-prompt.

  3. Install the Elasticsearch web-based user-interface:

    $ bin/plugin install mobz/elasticsearch-head
  4. Start Elasticsearch:

    $ /etc/init.d/elasticsearch start
  5. Configure an Elasticsearch index-template:

    $ curl -XPUT http://localhost:9200/_template/couchbase -d \
    > @plugins/transport-couchbase/couchbase_template.json

    When successful, the configuration-routine provides the following response: {"acknowledged":true}.

  6. Instantiate an elasticsearch index to be applied by Elasticsearch to data from a particular Couchbase bucket (in this case, beer-sample, which you previously used in your set-up of Couchbase Server):

    $ curl -XPUT http://localhost:9200/beer-sample

    When index-creation is successful, a further {"acknowledged":true} response is provided.

You have now completed all basic installation and configuration requirements for Elasticsearch, the Elasticsearch Plug-in, and Couchbase Server. (Note that more advanced configuration options are described later in this document.)

Installing on Other Platforms

The procedures and code-examples that you will encounter in the next section, Getting Started, all assume that you have installed and configured Elasticsearch, Couchbase Server, and the Elasticsearch Plug-in precisely as described above.

When you have completed Getting Started, and the other sections of this document, and have thus become more familiar with the plug-in and its capability, you will likely wish to perform installation on additional platforms, in preparation for or as part of a production-deployment.

Full details on the installation-procedures for Couchbase Server are described here. Those for Elasticsearch, here. Installing and configuring the plug-in on other platforms is virtually the same as described here, for Ubuntu 14. Note that:

  • The plug-in should be installed in the Elasticsearch install directory, with bin/plugin install ...etc.

  • Certain commands differ across platforms. For example, on CentOS, to install the Elasticsearch package use yum (rather than dpkg, as used on Ubuntu).

  • For MacOS, to use wget: first, install brew; then, install wget with brew install wget.

Elasticsearch 2.1.1

Elasticsearch 2.1.1 requires a special, compatible version of the plug-in. This can be obtained here.

Use of this version of the plug-in requires that Java security-policy permissions be appropriately set. See Advanced Settings.

Versioning and Compatibility

The following table shows the supported version-combinations for the three principal components:

Table 1. Version Compatibility
Plug-in Couchbase Elasticsearch


2.5.x to 4.x


2.5.x to 4.x



2.5.x to 4.x



2.5.x to 4.x

1.3.0 to 1.7.x


3.x, 2.5.x