We offer a free Hobby plan for development and testing on Heroku. A list of all available plans and capacities can be found at https://elements.heroku.com/addons/bonsai.
There are two ways to add Bonsai to your Heroku app:
1. Through the Heroku CLI tool
2. Through the Heroku app dashboard
You can add Bonsai to your app with this command:
<div class="code-snippet-container">
<a fs-copyclip-element="click-2" href="#" class="btn w-button code-copy-button" title="Copy">
<img class="copy-image" src="https://global-uploads.webflow.com/63c81e4decde60c281417feb/6483934eeefb356710a1d2e9_icon-copy.svg" loading="lazy" alt="">
<img class="copied-image" src="https://assets-global.website-files.com/63c81e4decde60c281417feb/64839e207c2860eb9e6aa572_icon-copied.svg" loading="lazy" alt="">
</a>
<div class="code-snippet">
<pre><code fs-codehighlight-element="code" fs-copyclip-element="copy-this-2" class="hljs language-javascript">$ heroku addons:add bonsai
----- Adding bonsai to some-appname-4005... done, v18 (free)</code></pre>
</div>
</div>
You can verify that the operation was successful by running <span class="inline-code"><pre><code>heroku config:get BONSAI_URL</code></pre></span>:
<div class="code-snippet-container">
<a fs-copyclip-element="click-3" href="#" class="btn w-button code-copy-button" title="Copy">
<img class="copy-image" src="https://global-uploads.webflow.com/63c81e4decde60c281417feb/6483934eeefb356710a1d2e9_icon-copy.svg" loading="lazy" alt="">
<img class="copied-image" src="https://assets-global.website-files.com/63c81e4decde60c281417feb/64839e207c2860eb9e6aa572_icon-copied.svg" loading="lazy" alt="">
</a>
<div class="code-snippet">
<pre><code fs-codehighlight-element="code" fs-copyclip-element="copy-this-3" class="hljs language-javascript">$ heroku config:get BONSAI_URL
----- http://username:password@redwood-12345.us-east-1.bonsai.io/</code></pre>
</div>
</div>
If this value is null, then Bonsai was not properly added to your account. Try again and look for error messages. If you still have problems, give us a shout.
Once the Add-on has been successfully added, you can check on the status of your cluster by running <span class="inline-code"><pre><code>$ heroku addons:open bonsai -a</code></pre></span>
Bonsai supports multiple search engines. The default is Elasticsearch, which will be used if nothing is specified on creation. Users can specify which search engine to use with the <span class="inline-code"><pre><code>--engine</code></pre></span> parameter. To use it on the command line, you would use something like this:
<div class="code-snippet-container">
<a fs-copyclip-element="click-4" href="#" class="btn w-button code-copy-button" title="Copy">
<img class="copy-image" src="https://global-uploads.webflow.com/63c81e4decde60c281417feb/6483934eeefb356710a1d2e9_icon-copy.svg" loading="lazy" alt="">
<img class="copied-image" src="https://assets-global.website-files.com/63c81e4decde60c281417feb/64839e207c2860eb9e6aa572_icon-copied.svg" loading="lazy" alt="">
</a>
<div class="code-snippet">
<pre><code fs-codehighlight-element="code" fs-copyclip-element="copy-this-4" class="hljs language-javascript">heroku addons:create bonsai:[plan] [-a APP_NAME] [--engine=elasticsearch]</code></pre>
</div>
</div>
Allowed values are: "elasticsearch" and "opensearch".
You have a fair amount of flexibility to choose the search engine version your cluster can run. There is a command line flag for specifying which version to use. This flag is called <span class="inline-code"><pre><code>--version</code></pre></span>, and it can be invoked in a couple different ways. To use it on the command line, you would use something like this:
<div class="code-snippet-container">
<a fs-copyclip-element="click-5" href="#" class="btn w-button code-copy-button" title="Copy">
<img class="copy-image" src="https://global-uploads.webflow.com/63c81e4decde60c281417feb/6483934eeefb356710a1d2e9_icon-copy.svg" loading="lazy" alt="">
<img class="copied-image" src="https://assets-global.website-files.com/63c81e4decde60c281417feb/64839e207c2860eb9e6aa572_icon-copied.svg" loading="lazy" alt="">
</a>
<div class="code-snippet">
<pre><code fs-codehighlight-element="code" fs-copyclip-element="copy-this-5" class="hljs language-javascript">heroku addons:create bonsai:[plan] [-a APP_NAME] [--version=X.Y]</code></pre>
</div>
</div>
Bonsai only supports certain versions of a given search engine, so users cannot provision any version. If you request a version that is not available, Bonsai will default to the latest available version.
There is a list of available versions documented here: Supported Elasticsearch Versions. In short, the options available will be determined by three factors:
The <span class="inline-code"><pre><code>version</code></pre></span> and <span class="inline-code"><pre><code>engine</code></pre></span> parameters also work in your app.json, if you use PR apps and Heroku pipelines:
<div class="code-snippet-container">
<a fs-copyclip-element="click-6" href="#" class="btn w-button code-copy-button" title="Copy">
<img class="copy-image" src="https://global-uploads.webflow.com/63c81e4decde60c281417feb/6483934eeefb356710a1d2e9_icon-copy.svg" loading="lazy" alt="">
<img class="copied-image" src="https://assets-global.website-files.com/63c81e4decde60c281417feb/64839e207c2860eb9e6aa572_icon-copied.svg" loading="lazy" alt="">
</a>
<div class="code-snippet">
<pre><code fs-codehighlight-element="code" fs-copyclip-element="copy-this-6" class="hljs language-javascript">{
"name": "Small Sharp Tool",
"description": "This app does one little thing, and does it well.",
"keywords": [
"productivity",
"HTML5",
"scalpel" ],
"addons" : [
{
"plan": "bonsai:hobby",
"options": {
"version": "6.5.4",
"engine": "elasticsearch"
}
}
]
}</code></pre>
</div>
</div>
To view a list of our current supported regions, see our documentation here:
For further help with your app.json and addons, see Heroku’s documentation here:
To add Bonsai through the Heroku UI, open up your application in the Heroku dashboard
Click on either the Resources tab, or the “Configure Add-ons” link. This menu will have a search bar for various Add-ons. Begin typing “bonsai,” and the autocomplete will find the Bonsai Elasticsearch Add-on:
Click on the Add-on to add it to your application. This will bring up a new screen where you will be able to select a payment plan for your new cluster. See the Bonsai Heroku Add-ons page for details about what each plan offers.
When you are ready, click on “Provision.” Your new cluster will be instantly created. Your dashboard will now show this:
When Bonsai is added to your application, a new environment variable called BONSAI_URL is created and initialized with the URL to your cluster. This is the URL that you will need in order to interact with your cluster.
Your application should be configured to read this URL directly from the environment, and should not be hard-coded or shared with others. If you would like to confirm that Elasticsearch is up and running, you can retrieve the URL by clicking no the Settings tab in the Heroku Dashboard.
There will be a section called “Config Vars”:
Click on “Reveal Config Vars” to see your environment variables. This will reveal the value of each variable like so:
You can copy the contents of the BONSAI_URL to your clipboard and paste it into a browser or curl command to see the response from Elasticsearch:
<div class="code-snippet-container">
<a fs-copyclip-element="click-7" href="#" class="btn w-button code-copy-button" title="Copy">
<img class="copy-image" src="https://global-uploads.webflow.com/63c81e4decde60c281417feb/6483934eeefb356710a1d2e9_icon-copy.svg" loading="lazy" alt="">
<img class="copied-image" src="https://assets-global.website-files.com/63c81e4decde60c281417feb/64839e207c2860eb9e6aa572_icon-copied.svg" loading="lazy" alt="">
</a>
<div class="code-snippet">
<pre><code fs-codehighlight-element="code" fs-copyclip-element="copy-this-7" class="hljs language-javascript">$ curl https://username:password@somehost-1234567.us-east-1.bonsai.io
{
"name" : "PvRcoFq",
"cluster_name" : "elasticsearch",
"cluster_uuid" : "DNlbVYS0TIGYwbQ6CUNwTw",
"version" : {
"number" : "5.4.3",
"build_hash" : "eed30a8",
"build_date" : "2017-06-22T00:34:03.743Z",
"build_snapshot" : false,
"lucene_version" : "6.5.1"
},
"tagline" : "You Know, for Search"
}</code></pre>
</div>
</div>
If you’re seeing this message, then you’re not including the correct authentication credentials in your request. Double check that the request includes the credentials shown in your dashboard and try again.
Because the URL includes authentication information, anyone with the fully-qualified URL can access your cluster. Treat the URL like a password: don’t hard-code it into applications, don’t check it into source control, and for Pete’s sake, never ever paste it into a StackOverflow question. If you need to share your cluster URL with us for support purposes, the auth-less host name is all you need:
Bad: “My cluster is https://username:password@somehost-1234567.us-east-1.bonsaisearch.net”
Good: “My cluster is somehost-1234567”
If your URL is leaked somehow, you can regenerate the credentials.
Adding Bonsai to your app automatically creates a cluster for you. It also adds a variable called <span class="inline-code"><pre><code>BONSAI_URL</code></pre></span> to your application’s environment, which will contain the canonical URL and credentials to your cluster. This automation makes it fast and easy to get started with your new cluster.
