Getting started with Bonsai Elasticsearch and Ruby on Rails is incredibly quick and simple to do. Sign Up for your free account we'll take it from there!
Creating Your First Bonsai Cluster
Once you've signed up for your free account on Bonsai, you'll be prompted to create a free developer cluster. Give your cluster a name and pick a region. The name helps you to distinguish between different applications and the region is how we manage our infrastructure on Amazon Web Services. Click on the "Create Cluster" button and voila, you've created your very first Bonsai cluster!
Our Example Rails App
Our example Rails app will provide you a good outline to follow along. You can access the Github repo here:
In our example app, Bookfaces, we'll have a list of books that are searchable via Book Title, Author, Publisher and Genre. You can see the app in action here:
So now that we have our example code (or a Rails project of your own) let's go ahead and get things ready for Bonsai.
Connecting Your Rails App to Your Bonsai Cluster
Bonsai clusters are created with unique URLs designed for secure, authenticated access to the Elasticsearch API. To avoid security concerns we strongly recommend adding your Bonsai Elasticsearch URL to your environment as a variable, you can do so by running:
export BONSAI_URL="<YOUR BONSAI URL>"
You can learn more about your Bonsai URL here: - https://docs.bonsai.io/docs/managing-your-cluster-url-and-credentials
Now let's add the following gems to your Gemfile:
gem 'elasticsearch-rails' gem 'elasticsearch-model' gem 'bonsai-elasticsearch-rails'
bundle install and we'll move on to the next step.
Deploying to Heroku
As with all things related to the development process, deploy early and often. It’s a good idea to double check that you have completed all the steps above. For our example app we used Heroku to deploy. For step by step instructions as to how you can deploy your rails app with Heroku, please consult their excellent documentation:
Once you have deployed to Heroku you can add the Bonsai add-on from the Overview tab.
Our next step will allow us to add data to the cluster as well as how to do a local database import. Let’s start with populating our local app first. For convenience sake, we will use the Faker gem to help populate db. Here’s a link to the Faker gem documentation:
Let’s add the Faker gem to the gemfile:
and run our
bundle install. Now that we’ve got the Faker gem installed, we can start adding some sample data. Take a look at our
seeds.rb. Files in our sample code if you need some guidance in how to structure those files.
Run the following commands to set up your local db, note that in Rails 5 we can now use the rails command instead of rake.
rails db:create rails db:migrate rails db:seed
rails s and check out all the new books for Bookfaces! Now that we know how to populate our local db, let’s proceed to getting our models ready for indexation.
Get Your App Ready to Index Models You'd Like to be Searchable
We'll want to prepare our models to be indexed and searchable by Bonsai. Take a look at
app/models/book.rb, where we include our
class Book < ApplicationRecord include Elasticsearch::Model belongs_to :author belongs_to :publisher belongs_to :genre ### View the entirety in the GitHub repo: https://github.com/omc/bonsai-rails-example/blob/master/app/models/book.rb end
We'll want to do this for all models that we want indexed. It's also advisable that we create rake tasks to import documents, it will allow you to index searchable records via rake tasks. Plus, it’s important to to have reliable and easily executable indexing scripts should you need to need to duplicate this process or have a backup at hand. You can do this by creating a file
lib/tasks/elasticsearch.rake and including:
Keep in mind you will need to explicitly create your index before you can put documents there, since Bonsai does not support "lazy" index creation. The best way to create your index is using the rake task we set up in the prior step. The first time you index your content, you'll want to set the FORCE parameter:
rake environment elasticsearch:import:all FORCE=y
The FORCE parameter will explicitly delete and recreate indices, so you probably don't want to use it frequently. Subsequent indexing tasks can drop this parameter.
The alternative way to do it would be to create your indices with curl. So in our Book model, use the following command to create the index:
curl -XPUT http://username:firstname.lastname@example.org/books
You have created your Bonsai cluster, added your cluster URL to your App, indexed the models and now can deploy to the service of your choice! For our example we used Heroku, where you can install the Bonsai Addon.