This add-on is operated by One More Cloud, Inc.
Heroku’s first Elasticsearch and OpenSearch addon, from $0/mo to Private Spaces
Bonsai Elasticsearch
Last updated August 13, 2024
Table of Contents
Bonsai provides high-performance Elasticsearch clusters on demand.
Elasticsearch is a search engine that enables users to build and ship great search experiences. With Bonsai, customers get a robust, opinionated cluster that scales elastically to your usage. We manage and maintain the servers for you, because you have more important things to be working on than deciding how many nodes to use, and how much memory to allocate to each.
We’re a bootstrapped, independent business with one mission: high-quality hosted search at all scales. Since launching in 2012 as the world-first hosted Elasticsearch service, Bonsai has grown to manage the search for over 5,000 businesses. Use-cases range from simple back-office search tools to enterprise e-commerce at scale.
Every production Bonsai cluster is monitored 24/7, replicated for high availability, and automatically backed up hourly. We support the native HTTP Elasticsearch API, so you can take advantage of an entire ecosystem of open source clients and tools built for Elasticsearch. Popular tools include Kibana for time-series analytics and data visualization, or SearchKit for reusable React components.
Installing the add-on
Bonsai Elasticsearch can be added to a Heroku application via the Elements page or Heroku CLI:
We offer a low cost staging plan for development and testing, which allows a limited number of shards. When you are ready for production, see our list of available plans.
$ heroku addons:create bonsai
Adding bonsai-rugged-29310 to sharp-mountain-4005... done
Setting BONSAI_URL and restarting sharp-mountain-4005... done, v18
Thanks for adding Bonsai! Please log in to the Bonsai dashboard to finalize your account setup.
Use `heroku addons:open bonsai` to view the dashboard.
Use `heroku addons:docs bonsai` to view documentation.
Once Bonsai has been added, a BONSAI_URL environment variable will be available in your app’s configuration. This will contain the hostname and credentials for your app’s Elasticsearch cluster. You can check the value of this variable with the heroku config command:
$ heroku config:get BONSAI_URL
http://username123:password123@my-awesome-cluster-94865.us-east-1.bonsai.io/
We recommend treating this URL as sensitive information akin to a password, as anyone with this information can access your data. For more information, see the post on our standard security features.
The best practice is to keep this information safely contained in the Heroku environment and not hard code it into your app. We maintain a series of quickstart guides with examples for various languages/frameworks at docs.bonsai.io, and for Rails users, we offer the bonsai-elasticsearch-rails gem.
Protip: Bonsai supports a command line flag for specifying which version of Elasticsearch you want to use. Note that we only support specific versions of Elasticsearch, so you can’t provision an arbitrary one. We have a list of available versions documented here. The engine parameter allows “elasticsearch” or “opensearch”.
heroku addons:create bonsai:[plan] [-a APP_NAME] [--engine=elasticsearch] [--version=X.Y]
The version parameter also works in your app.json, if you use PR apps and Heroku pipelines.
The Bonsai Dashboard
The Bonsai Elasticsearch dashboard shows you detailed information about your cluster, as well as offering a host of management and debugging tools. The dashboard can be accessed via the CLI with heroku addons:open bonsai. For more information on using the Bonsai dashboard, check out our detailed documentation.
Non-production tier clusters
Sandbox
Sandbox clusters are limited to one per user, plus one per production Bonsai cluster. They are intended to help introduce Elasticsearch into your app, and complement production environments with testing and CI environments.
Bonsai offers free Sandbox clusters for users who would like to experiment with Elasticsearch. These are provisioned with just enough resources to get some research and development time with Elasticsearch.
For more details on Heroku plans and pricing, please see the Bonsai Heroku Addon Elements page.
Staging
As a step up from the sandbox plan, Bonsai offers low-cost staging clusters for users who need a cluster for development and testing purposes with more capacity, available 24/7. When you are ready for production, a list of all available plans and capacities can be found at https://elements.heroku.com/addons/bonsai.
Migrating between plans
Application owners should carefully manage the migration timing to ensure proper application function during the migration process.
Eventually many users grow to a point where the limitations of their current plan no longer meet the needs of the application. Perhaps they need more data capacity, or perhaps they need more concurrency to handle the demands of traffic.
Whatever the case, changing your cluster plan through Bonsai is easy. Users can change their plan via the Heroku dashboard or with the heroku addons:upgrade command:
$ heroku addons:upgrade bonsai bonsai:newplan [ -a APP_NAME ]
Changing bonsai plan to bonsai:newplan... done, ($XX.00/month)
Thanks for adding Bonsai! Please log in to the Bonsai dashboard to finalize your account setup.
Use `heroku addons:open bonsai` to view the dashboard.
Upgrading and downgrading plans will not affect existing data. Note that downgrading to a plan with less capacity than your current usage may subject your cluster to overage limits.
Removing the add-on
Bonsai Elasticsearch can be removed via the CLI.
This will destroy all associated data and cannot be undone!
$ heroku addons:destroy bonsai [ -a APP_NAME ]
! WARNING: Destructive Action
! This command will affect the app: APP_NAME
! To proceed, type "APP_NAME" or re-run this command with --confirm APP_NAME
> APP_NAME
Destroying bonsai-rugged-29310 on APP_NAME... done, ($XX.00/month)
Removing vars for BONSAI from APP_NAME and restarting... done, v37
Learn more
We maintain a robust set of documentation on Bonsai’s service, Elasticsearch, best practices, quick-start guides and more at docs.bonsai.io. That is an excellent resource for users whose question is not answered here. Some articles dealing with common Heroku issues:
Terms of Service
By installing the Bonsai Elasticsearch Addon, you agree to Bonsai’s Terms of Service Agreement.
Support
All Bonsai Elasticsearch support and runtime issues should be logged with Heroku Support at https://support.heroku.com. Please include your app name and cluster hostname (from BONSAI_URL). If practical, a reproduction of the issue using curl is always helpful.
Just want to share your thoughts or say hello? You can follow us on Twitter at https://twitter.com/bonsaisearch.