Using Bonsai.io

Hold Up!

Bonsai clusters can be provisioned in a couple of different ways. These instructions are for users who want to be billed directly by Bonsai. If you are a Heroku or Manifold customer and are adding Bonsai to your app, then you will not need these instructions. Instead, check out: 

Creating an account on Bonsai is the first step towards provisioning and scaling an Elasticsearch cluster on demand. The following guide has everything you need to know about:

Sign up at bonsai.io/signup

Navigate to the sign up page, where you’ll provide an email address:

Email Validation

We validate emails using RFC 2822 and RFC 3696. If you have a non-conforming email address, let us know at support@bonsai.io.

If everything is good, you should receive an email from us shortly with a confirmation link.

Confirm your email

Navigate to your email client. You should receive the following email from our system:

Click on the button, which will take you to a form to complete your sign up.

Complete your account details

Haven’t We Seen You Before?

If you have signed up for Bonsai in the past using this email address, you will receive an email directing you to log in using it.

After clicking on the Confirm email button from the confirmation email, you will be presented with a simple form to complete your account.

Protip: Use a strong password

We’re a security-conscious bunch, but we don’t have any arcane rules about what kinds of characters you must use for your password. Why? We’ll let xkcd explain it, but the tl;dr is our password policy simply enforces a minimum length of 10 characters. We also reject common passwords that have been pwned. Sadly, correct horse battery staple appears in our blacklist.

We also highly recommend using a password manager like 1Password to generate unique, secure passwords.

Create a Cluster

Once your account has been created, you’ll be able to create your first cluster. You can provision a free starter cluster without entering payment details. If you wish to provision or upgrade to a larger cluster with more resources, you’ll need to add a credit card (see below).

This form will allow you to specify some details about the cluster you want:

The dashboard lets you customize your cluster a bit before it’s provisioned. As you make changes, the summary on the right hand side of the screen will update.

There are several attributes that can be configured, which are discussed in detail below.

Cluster Name

Users are able to manage multiple clusters through their Bonsai dashboard. Not only is the cluster name a label for you to distinguish between different applications and environments, but it’s also used as part of the cluster’s unique hostname.

For example, if you name your cluster “Erin’s Exciting Elasticsearch Experiment,” that will be the name of your cluster. The host name of your cluster URL will be automatically generated into something like erins-exciting-elasticsea-123456.

Cluster names can be changed later, but the host name that is generated when the cluster is first created is immutable.

Cluster Region

We manage our infrastructure on Amazon Web Services, and run clusters in several of their regions. Users are able to provision clusters in the following regions:

  • us-east-1 (Virginia)
  • us-west-2 (Oregon)
  • eu-west-1 (Ireland)
  • ap-southeast-2 (Sydney)
  • eu-central-1 (Frankfurt).

These regions are supported due to broad demand. We can support other regions as well, but pricing will vary. Shoot us an email if you’d like to learn more about getting Bonsai running in a region not listed above.

Also note that you will want to select a region that’s as close to where your application is hosted as possible to minimize latency. Doing so will ensure the fastest search and best user experience for your application.

Elasticsearch Version

We support a number of Elasticsearch versions in different regions, however not all regions will support all versions. The available options will appear in this dashboard, and if a version is not available in the region you have selected, it will be grayed out.

We can accommodate specific versions of Elasticsearch on Enterprise deployments. If you need Bonsai to run a version of Elasticsearch in a particular region not available on the Create a Cluster dashboard, email us to discuss options.

Cluster Plan

The capabilities of your cluster are determined by the plan level. Bonsai meters on a number of different attributes like disk space and concurrency, and these limits scale with plan level. Generally:

  • Free and Staging plans have the lowest limits
  • Production grade plans have limits suitable for production applications
  • Enterprise grade plans have no metering at all

You can upgrade your plan at any time, and your cluster will scale automatically. In some cases, such as upgrading to a single tenant or Enterprise grade plan, we will need to schedule a data migration, which may require a few minutes of read-only mode. If this is a possibility, we will work out the details with you beforehand.

Free to Start!

No credit card is required to spin up a free cluster on Bonsai. Free clusters are designed for small apps with minimal usage, and their limits reflect this. If you decide that you’d like to scale up to something a little beefier, you’ll need to supply a credit card.

Limitations

While the first cluster can be free, customers are limited to a single free cluster for each production-grade (paid) cluster.

When you’re ready to proceed, click on “Create Cluster.”

Congratulations! Your Elasticsearch cluster will instantly be up and running, and you will be automatically routed to your cluster dashboard.

Viewing Your Cluster

When you visit your dashboard, you’ll see your new cluster listed:

At a glance, you will see the cluster, the region in which it’s located, the plan that it has, and some indicators about usage. Initially, these indicators will be empty because you haven’t used the cluster yet.

Click on the new cluster to bring up the cluster dashboard. You’ll be greeted with an overview page that gives you a ton of information about your cluster:

The cluster dashboard is covered in detail in Exploring Your Cluster Dashboard, but for now, just look at the “Full-Access URL.” This URL is a pointer to your Elasticsearch cluster. It has a form like:

https://randomuser:randompass@strickland-propane-3917077713.us-east-1.bonsaisearch.net

Credentials are not your login

The username/password credentials for your Elasticsearch cluster are not the same credentials you use to log in to Bonsai. The cluster credentials are randomly generated pairs, like “pthstckm4:jj5i6zh3j”

Bonsai clusters are configured to support HTTPS and HTTP Basic Auth out of the box for security. The URL contains a randomly-generated username and password combination that must be included in all requests to the cluster in order for Elasticsearch to process a request.

You can test that the cluster is available by using a tool like curl:

$ curl "https://randomuser:randompass@strickland-propane-3917077713.us-east-1.bonsaisearch.net"

{
  "name": "e_dJ9rV",
  "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"
}

HTTP 401: Authentication required

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.

Keep Your URL Secret

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://randomuser:randompass@strickland-propane-3917077713.us-east-1.bonsaisearch.net”

Good: “My cluster is strickland-propane-3917077713”

If your URL is leaked somehow, you can regenerate the credentials. See Exploring Your Cluster Dashboard for more information.

Now that you have created your cluster and verified that it is up and running, you can take a look at your cluster in greater detail.

Managing Your Organization Profile

Need to change your email, password, update a credit card, or provide access to your clusters to a coworker? Use the sections below to manage all things account-related. To access your Account Settings, click on the upper right-hand dropdown and select Account Settings.

Organization Profile

Your profile – both for you and your organization – provides basic details to help us serve you best. Providing some basic contact information also helps to ensure we can reach out in the event that something goes wrong

Account Password

You can change your login password here. You will need your current password in order to create a new password.

Adding Team Members

Bonsai accounts support multiple team members, each with specialized roles. Account owners can invite new users to join the organization. At least one Billing and one Admin role are needed for each account, so the first user in the account defaults to having both the Admin and Billing role.

To add a new team member, check the boxes for the role(s) you would like that user to have, provide their email address and click on “Send Team Invite.”

After sending the invite, you will see the invitee listed along with their roles. You can also remove a team member from your organization by clicking on the Remove button. You will not be able to remove the last Admin or last Billing member on the account, as at least one of those roles is needed.

If there was a mistake, or a role needs to change, you can click on the pencil icon to edit the user’s role. This will allow you to update their role(s), which will take effect immediately.

Update Billing

If you haven’t added a credit card yet, or would like to update your payment profile, you can do so under the Billing tab.

Click on the “Add a credit card” button to add a credit card. That will bring up a new form:

Fill the details out and click Save to proceed.

Your Financial Data, Secured.

When you add a credit card in Bonsai, the information is encrypted and passed to our payment processor. We have verified that this service is Level 1 PCI Compliant. This level of compliance is the highest level of security a business can offer. We do not host or store any financial data, and your credit card details can not be accessed by anyone on our team or within the payment processor.

You can associate multiple credit cards to your account. If you only have one card, it will automatically be the default. If you have multiple cards, you have the option to update the default and remove non-default cards:

To update an existing card, for example, if you have a new expiration date, simply click on “Add a credit card,” and enter the new details. Save it, then set it to be the new default. Then you can delete the older card.

Coupon Codes

If you have a coupon code, you can add it in the Billing section. Simply enter the code and click on “Add coupon code”:

If the code is accepted, it will be listed, along with a description of what it does:

If the code is not valid, there will be an error message:

If you have a code that isn’t working but should, shoot us an email at support@bonsai.io and we’ll check it out.

Sessions

This screen shows all the locations where your account is logged in. If you would like to revoke access to a session, simply click on the “Revoke” button next to the desired section. This will force the browser at that location to require a new login.

The Current session is the one you’re using to view this screen. It can’t be revoked, but you can log out, which will accomplish the same thing.

Managing Your Personal Profile

You can manage your personal profile by clicking on your name in the upper right corner and selecting "Profile" from the dropdown menu:

Updating Your Personal Information

You can edit your name and contact information in the "Profile" tab:

Managing SSO

Single-sign on (SSO) is the ability to have a third party service validate your identity. If you would prefer to use a service like Google, which offers additional security like multi-factor authentication (MFA), then you can set that up by clicking on Profile and selecting the Security tab:

To use this feature, your identity provider must match your Bonsai.io account email address. For example, if your Google email address is "bob.smith@gmail.com," then your Bonsai.io account must use this same email address in order to verify your identity.

Once you have SSO set up, you will no longer be able to log in with your username/password. Logging in will need to be done through the identity provider.

To revert back to username/password authentication, you will need to disable SSO. To do so, simply go to Profile and select the Security tab, then click on Disable SSO

Updating Your Password

If you need to update your password, navigate to Profile and select the Security tab, then scroll down to "Update Password". You will need to enter your old password in order to change it.

Bonsai strongly recommends using a password manager like 1Password or LastPass to keep your passwords secure, and to help randomly generate new passwords. At a minimum, a password needs 10 characters:

Managing Your Personal Sessions

You can view and revoke your active sessions by clicking on Profile and selecting the Security tab, and scrolling down to Active Sessions. If you have a session on another device, you can see its IP address and information about the device.

You can revoke sessions individually, or revoke all. Note that revoking all sessions will require you to log in again.

Managing Your Notification Preferences

Bonsai occasionally sends out updates about new features, and can also send out weekly reports about your cluster's usage and performance. You can manage whether or not you receive these emails by clicking on Profile and selecting the "Notification Preferences" tab:

Create a New Account

You can create a new account from the upper right-hand dropdown by selecting Add Account:

Give your new account a name and click Create Account:

You will then be prompted to create your free sandbox cluster in the new account. You can switch between your accounts from the drop-down menu:

Cancel Account

If you want to cancel your account, you’ll need to first make sure that any active clusters you have are deprovisioned first. If you have any active clusters on your account, you’ll see a notice like this:

Once you have deprovisioned all of the clusters on your account, you will be able to cancel your account completely. You will see a screen requesting your account password to confirm the cancellation:

So long, farewell, auf Wiedersehen, good night!

We’re sorry that you no longer want to have an account with us, but wish you the very best with your application and search. If there’s anything you feel we could do better, please don’t hesitate to send us an email with comments.