Bonsai Elasticsearch

This add-on is operated by Onemorecloud, LLC

Fast, scalable and reliable full-text search, powered by Elasticsearch.

Bonsai Elasticsearch

Last Updated: 14 August 2014

Table of Contents

Bonsai offers a Heroku add-on for ElasticSearch.

ElasticSearch is the latest generation search engine built on the powerful Lucene library. Its API is freshly designed around modern RESTful JSON conventions, making it easy to learn and understand. ElasticSearch will automatically index your JSON data with sensible defaults, which means that you can get started without writing a single line of configuration. ElasticSearch is the perfect place to start for anyone new to full-text search engine concepts, or for anyone who is looking for more clarity and less ceremony in their search engine.

The ElasticSearch internals are designed from the ground up with data distribution in mind. This means you get greater scalability, performance and reliability in a cloud hosted environment. An ElasticSearch index can automatically shard your data, to scale to the largest indexes and support high volumes of write traffic. All of our plans also offer replication by default, with transparent hot failover, and the ability to scale your replicas for high volumes of read traffic.

You have more important things to work on than managing and scaling another set of servers. With Bonsai, you get solid, scalable technology that is easy to use and understand, and managed by experts. All you have to worry about is putting it to use to build great features for your customers.

The Bonsai add-on provides an ElasticSearch index to your application, which is available to any language and platform that can send JSON to its RESTful HTTP API. You may also opt to use one of the many open source ElasticSearch clients for tighter integration with languages and frameworks such as, in no particular order, Ruby, Ruby on Rails, Python, Django, PHP, Erlang, Clojure, Java, Play! and Perl.

Installing the add-on

Bonsai ElasticSearch can be installed to a Heroku application via the heroku CLI:

Our free plan for development and testing allows a single index with one shard, and no replication. When you are ready for production, a list of all available plans and capacities can be found at

$ heroku addons:add bonsai
-----> Adding bonsai to sharp-mountain-4005... done, v18 (free)

Once Bonsai ElasticSearch has been added, the BONSAI_URL environment variable will be available in your app’s configuration. This will contain the canonical URL and credentials to your ElasticSearch Cluster. You can check the value of this variable with the heroku config comand:

$ heroku config | grep BONSAI

After installing Bonsai ElasticSearch, your application may create an index and start using it right away.

Creating your first index

Many ElasticSearch clients will take care of creating an index for you. You should review your client’s documentation for more information on its index usage conventions. If you don’t know how many indexes your application needs, we recommend creating one index per application per environment, to correspond with your database.

Let’s create an example index called acme-production from the command line with curl. Note that your application’s BONSAI_URL will contain a username and a password which is used to authenticate index creation, modification and deletion.

You may want to check out httpie as a nice alternative to curl that provides syntax highlighting.

$ curl -X POST

Using your new index

Let’s insert a “Hello, world” test document to verify that your new index is available, and to highlight some basic ElasticSearch concepts.

First and foremost, ElasticSearch is a JSON document store. You can use HTTP REST methods to create, update, fetch and destroy JSON documents. Every JSON document should specify an id and a type. You you may specify these values with the _id and the _type keys, or ElasticSearch will infer them from the URL of its API endpoints.

In the following example, we HTTP POST a simple JSON document to a URL which specifies a _type of test and an _id of hello. You should replace the sample URL in this document with your own index URL to follow along.

$ curl -XPOST -d '{"title":"Hello world"}'
  "ok" : true,
  "_index" : "acme-production",
  "_type" : "test",
  "_id" : "hello",
  "_version" : 1

ElasticSearch will index the document you provide based on sensible defaults for later searching. You can also see some of the values you provided echoed back in the output, along with a few other default fields, which will be explained elsewhere.

Next, you may view this document by issuing a HTTP GET request to its URL.

Note the _source key, which contains a copy of your original document. ElasticSearch makes an excellent general-purpose document store!

$ curl -XGET ''
  "_index" : "acme-production",
  "_type" : "test",
  "_id" : "hello",
  "_version" : 1,
  "exists" : true,
  "_source" : { "title":"hello world" }

To learn more about about the operations supported by your index, you should read the ElasticSearch Index API documentation. Note that some operations mentioned in the documentation (such as “Automatic Index Creation”) are for administrative purposes, and will be restricted in our environment.

Local workstation setup

ElasticSearch is open source software, and you can download and install your own instance for a local development and testing environment.

OS X and Homebrew

$ brew install elasticsearch


You may download the latest ElasticSearch release from The downloaded package will contain a standalone elasticsearch executable.

$ curl -k -L -O
$ tar -zxvf elasticsearch-0.19.10.tar.gz
$ ./elasticsearch-0.19.10/bin/elasticsearch -f

Developing with Foreman

We also recommend using Foreman for starting and starting ElasticSearch locally. A sample Procfile may look like this:

elasticsearch: path/to/elasticsearch -f

You should also run heroku ps:scale elasticsearch=0 on your next deploy to avoid attempting to run this command on Heroku.

Using the Elasticsearch-rails client

The current recommended Rails client for Bonsai is the official elasticsearch-rails client. Simply add the following gems to your Gemfile and install via Bundler:

gem 'elasticsearch-model'
gem 'elasticsearch-rails'
gem 'bonsai-elasticsearch-rails'

The first two gems are required to get the client, while the ‘bonsai-elasticsearch-rails’ gem is a bonsai-specific gem to get the client to work on Heroku.

By default, the elasticsearch-rails client attempts to connect to localhost:9200, which results in a Connection refused error on Heroku. The client needs to be initialized with the URL to your specific cluster, which is stored the BONSAI_URL environment variable. Our gem does this automatically, but if you would prefer to minimize the gems in your Gemfile, you can simply add the following to config/initializers/bonsai.rb:

Elasticsearch::Model.client = url: ENV['BONSAI_URL']

Please refer to the elasticsearch-rails README for the most up to date methods of implementing search in your models.


Tire has been deprecated in favor of the official elasticsearch-rails client. Tire is no longer actively maintained and the developer now works on the official Elasticsearch client. Tire will not support Elasticsearch 1.0+, and Bonsai no longer maintains Elasticsearch clusters below v1.0. If you require legacy support, let us know and we'll see what we can do.

Bonsai ElasticSearch Dashboard

The Bonsai ElasticSearch dashboard shows you basic information about your account and. The dashboard can be accessed via the CLI:

$ heroku addons:open bonsai
Opening bonsai for sharp-mountain-4005…

Or by selecting Bonsai ElasticSearch from your application’s page on the the Heroku dashboard.


Connection refused

This error most commonly occurs when your Elasticsearch client has not been properly configured. By default, many clients will try to connect to localhost:9200. Since Heroku is not running Elasticsearch (Bonsai is a third party service that maintains the service outside of the Heroku ecosystem), port 9200 is closed and the client responds with “Connection refused.”

The solution is to ensure that the client is properly configured. If you’re using the elastisearch-rails client, simply add the following gem to your Gemfile and install via Bundler:

gem 'bonsai-elasticsearch-rails'

Alternatively, you can initialize the client yourself using the Heroku environment variable for your cluster URL:

Elasticsearch::Model.client = url: ENV['BONSAI_URL']

If you’re using a different client, consult the documentation and ensure that it is configured to connect to your cluster and not localhost:9200.

HTTP 401 Authorization Required

Some ElasticSearch actions have been limited for administrative use only within our shared cluster. In general, this applies to any action outside of your index, or to updating certain system-level attributes of your index (such as shards or replicas).

Notably, if you receive this error when you try to PUT a new mapping to the root of your index, you should instead use the _mapping action within your index.

“No handler found for uri … and method …”

Note that the provided URL is for an index. Your request should be to a URL in the form of one of the following:


We also provide three Cluster-level actions at this time:

  1. — cluster root URL, for cluster health checks
  2. — cluster root URL, for cluster health checks
  3. — cluster bulk import handler
  4. — scrolling search handler

Migrating between plans

Application owners should carefully manage the migration timing to ensure proper application function during the migration process.

Our plans are primarily metered on replication level, and also on the number of shards allowed to a plan.

Indexes created within our starter-level plans have no replication, and are not intended for production traffic. An index created within our production-level plans will be replicated for higher availability and higher search traffic.

For greater data capacity, an index may be partitioned into many shards. Each shard is distributed to a different server within our cluster to allocate more resources for each search, and help scale to ever increasing quantities of data.

When changing your plan, we will adjust the replication level of any existing indices, as well as add or remove shards as per your new plan. If you have upgraded to a plan with additional shards, you may create a new index and must migrate your data

Removing the add-on

Bonsai ElasticSearch can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:remove bonsai
-----> Removing bonsai from sharp-mountain-4005... done, v20 (free)


All Bonsai ElasticSearch support and runtime issues should be logged with Heroku Support at Please include your app name and index URL, and if possible, a reproduction of the issue with curl.

Any product feedback or non-support related issues is welcome via Twitter at @bonsaisearch or email to

Additional resources

Suggestions for our docs?

Found a typo? Have a client to recommend, or an interesting question? Comment on this gist.