{"_id":"5a8fae0368264c001f20cc16","category":{"_id":"5a8fae0368264c001f20cc06","version":"5a8fae0268264c001f20cc00","project":"5633ebff7e9e880d00af1a53","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-12-23T19:13:48.702Z","from_sync":false,"order":1,"slug":"quickstart-guides","title":"Bonsai Heroku Basics"},"parentDoc":null,"user":"5633ec9b35355017003ca3f2","project":"5633ebff7e9e880d00af1a53","version":{"_id":"5a8fae0268264c001f20cc00","project":"5633ebff7e9e880d00af1a53","__v":2,"createdAt":"2018-02-23T06:00:34.961Z","releaseDate":"2018-02-23T06:00:34.961Z","categories":["5a8fae0268264c001f20cc01","5a8fae0268264c001f20cc02","5a8fae0368264c001f20cc03","5a8fae0368264c001f20cc04","5a8fae0368264c001f20cc05","5a8fae0368264c001f20cc06","5a8fae0368264c001f20cc07","5a8fae0368264c001f20cc08","5a8fae0368264c001f20cc09","5abaa7eb72d6dc0028a07bf3"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2.0"},"__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-12-23T19:14:10.420Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"Heroku makes it quick and easy to get started with Bonsai Elasticsearch. We recommend using one of the [official clients](https://www.elastic.co/guide/en/elasticsearch/client/index.html).\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Bonsai clusters can be provisioned in a couple of different ways. These instructions are for Heroku users. If you have an account on Bonsai.io or via Manifold, then you will not need these instructions. Instead, check out:\\n\\n* [Getting Started With Bonsai.io](doc:getting-started-with-bonsaiio) \\n* [Getting Started With Manifold](doc:getting-started-with-manifold)\",\n  \"title\": \"Hold up!\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Installing Bonsai Elasticsearch\"\n}\n[/block]\nAdding Bonsai to your app automatically creates a cluster for you. It also adds a variable called BONSAI_URL to your application's environment, which will contain the canonical URL and credentials to your Elasticsearch cluster. This automation makes it fast and easy to get started with your new cluster.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"We offer a free Sandbox 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.\",\n  \"title\": \"Our Heroku Add-on\"\n}\n[/block]\nThere are two ways to add Bonsai to your Heroku app:\n1. Through the Heroku CLI tool\n2. Through the Heroku app dashboard\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using the Heroku CLI tool\"\n}\n[/block]\nYou can add Bonsai Elasticsearch to your app with this command:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ heroku addons:add bonsai\\n\\t-----> Adding bonsai to some-appname-4005... done, v18 (free)\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nYou can verify that the operation was successful by running `heroku config:get BONSAI_URL`:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ heroku config:get BONSAI_URL\\n\\t-----> http://username:password:::at:::redwood-12345.us-east-1.bonsai.io/\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nIf 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](mailto:support@bonsai.io).\n\nOnce the Add-on has been successfully added, you can check on the status of your cluster by running `$ heroku addons:open bonsai -a <your app>`\n\n### Adding a specific version of Elasticsearch\n\nYou have a fair amount of flexibility to choose the version of Elasticsearch your cluster can run. There is a command line flag for specifying which version to use. This flag is called `--version` and it can be invoked in a couple different ways. To use it on the command line, you would use something like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"heroku addons:create bonsai:[plan] [-a APP_NAME] [--version=X.Y]\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nBonsai only supports certain versions of Elasticsearch, so users can not provision _any_ version. If you request a version that is not available, Bonsai will return an error message indicating what versions are available:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"heroku addons:create bonsai --version=1.2.3\\nCreating bonsai on ⬢ someapp... !\\n ▸    An error was encountered when contacting the add-on partner to create bonsai:sandbox-6: The requested version [1.2.3] is not available in this region on your plan. Available options are: 1.7.5, 2.4.0, 5.3.2, 5.4.3, 5.6.8, 6.0.1\\n\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nIn addition to the error message, there is a list of available versions documented here: [Supported Elasticsearch Versions](https://docs.bonsai.io/docs/supported-elasticsearch-versions). In short, the options available will be determined by three factors:\n\n1. **Region.** Your cluster will be provisioned in the same AWS region where your Heroku app is located. However, some regions support more versions than other regions, based on demand.\n2. **Plan.** Versions are rolled out to Sandbox and Staging tier plans in advance of Production grade plans. Additionally, older versions of Elasticsearch may only be supported on Dedicated tier plans.\n3. **Age.** Bonsai will occasionally deprecate older versions of Elasticsearch. If you need a version of Elasticsearch that is no longer supported, the only way to get it will be to upgrade to a [Dedicated plan](https://bonsai.io/pricing).\n\nThe `version` parameter also works in your app.json, if you use PR apps and Heroku pipelines:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"name\\\": \\\"Small Sharp Tool\\\",\\n  \\\"description\\\": \\\"This app does one little thing, and does it well.\\\",\\n  \\\"keywords\\\": [\\n    \\\"productivity\\\",\\n    \\\"HTML5\\\",\\n    \\\"scalpel\\\"\\n  ],\\n  \\\"addons\\\" : [\\n    {\\n    \\t\\\"plan\\\": \\\"bonsai:sandbox\\\",\\n      \\\"options\\\": {\\n        \\\"version\\\": \\\"2.4.0\\\"\\n      }\\n    }\\n  ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nFor further help with your app.json and addons, see Heroku's documentation here:\n\n- [Heroku App JSON Schema](https://devcenter.heroku.com/articles/app-json-schema#addons) \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using the Heroku dashboard\"\n}\n[/block]\nTo add Bonsai through the Heroku UI, open up your application in the Heroku dashboard:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/f00ad18-getting-started-1.png\",\n        \"getting-started-1.png\",\n        541,\n        517,\n        \"#ecf3f4\"\n      ],\n      \"caption\": \"The Heroku App Dashboard.\"\n    }\n  ]\n}\n[/block]\nClick 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:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/a4d4f1a-getting-started-2.png\",\n        \"getting-started-2.png\",\n        953,\n        523,\n        \"#ecf3f4\"\n      ],\n      \"caption\": \"The Resources tab shows how many addons the app has added.\"\n    }\n  ]\n}\n[/block]\nClick 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](https://elements.heroku.com/addons/bonsai) page for details about what each plan offers.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/94e1625-getting-started-3.png\",\n        \"getting-started-3.png\",\n        501,\n        425,\n        \"#8f8daa\"\n      ],\n      \"caption\": \"You can select the plan for Bonsai when adding it to your app.\"\n    }\n  ]\n}\n[/block]\nWhen you are ready, click on \"Provision.\" Your new cluster will be instantly created. Your dashboard will now show this:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/0512494-getting-started-4.png\",\n        \"getting-started-4.png\",\n        931,\n        255,\n        \"#f0f7f9\"\n      ],\n      \"caption\": \"The flash message indicates that Bonsai has been successfully added.\"\n    }\n  ]\n}\n[/block]\nWhen 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.\n\nYour 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.\n\nThere will be a section called \"Config Vars\":\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/7f814b3-getting-started-5.png\",\n        \"getting-started-5.png\",\n        485,\n        162,\n        \"#7c7e9c\"\n      ],\n      \"caption\": \"You can see the environment variables set for your application by revealing the Config Vars.\"\n    }\n  ]\n}\n[/block]\nClick on \"Reveal Config Vars\" to see your environment variables. This will reveal the value of each variable like so:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/a4a8f8b-getting-started-6.png\",\n        \"getting-started-6.png\",\n        916,\n        222,\n        \"#f1f3f6\"\n      ],\n      \"caption\": \"The `BONSAI_URL` variable shows the URL to your app's Elasticsearch cluster.\"\n    }\n  ]\n}\n[/block]\nYou 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ curl https://username:password@somehost-1234567.us-east-1.bonsai.io\\n{\\n  \\\"name\\\" : \\\"PvRcoFq\\\",\\n  \\\"cluster_name\\\" : \\\"elasticsearch\\\",\\n  \\\"cluster_uuid\\\" : \\\"DNlbVYS0TIGYwbQ6CUNwTw\\\",\\n  \\\"version\\\" : {\\n    \\\"number\\\" : \\\"5.4.3\\\",\\n    \\\"build_hash\\\" : \\\"eed30a8\\\",\\n    \\\"build_date\\\" : \\\"2017-06-22T00:34:03.743Z\\\",\\n    \\\"build_snapshot\\\" : false,\\n    \\\"lucene_version\\\" : \\\"6.5.1\\\"\\n  },\\n  \\\"tagline\\\" : \\\"You Know, for Search\\\"\\n}\\n\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/990bae9-getting-started-7.png\",\n        \"getting-started-7.png\",\n        604,\n        328,\n        \"#0b74e4\"\n      ],\n      \"caption\": \"You can copy/paste the cluster URL into a browser to see the cluster information. NOTE: the randomly-generated username and password must be included or the request will return an HTTP 429 error.\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"HTTP 401: Authentication required\",\n  \"body\": \"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.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Keep Your URL Secret\",\n  \"body\": \"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:\\n\\nBad: \\\"My cluster is https://username:password@somehost-1234567.us-east-1.bonsaisearch.net\\\"\\n\\nGood: \\\"My cluster is somehost-1234567\\\"\\n\\nIf your URL is leaked somehow, you can regenerate the credentials. See [The Dashboard](doc:bonsai-elasticsearch-dashboard) for more information.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Next Steps\"\n}\n[/block]\nNow that you have created your cluster and verified that it is up and running, let's take a look at [The Dashboard](doc:bonsai-elasticsearch-dashboard). \n\nWant to create some indices?\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Bonsai has index auto-creation disabled by default, so if your integration requires indices to be set up, now might be a good time to [create your first indices](doc:creating-your-first-index).\",\n  \"title\": \"Trouble Creating Indices?\"\n}\n[/block]","excerpt":"How to add and configure the Bonsai add on for Heroku applications.","slug":"getting-started-with-heroku","type":"basic","title":"Getting Started With Heroku"}

Getting Started With Heroku

How to add and configure the Bonsai add on for Heroku applications.

Heroku makes it quick and easy to get started with Bonsai Elasticsearch. We recommend using one of the [official clients](https://www.elastic.co/guide/en/elasticsearch/client/index.html). [block:callout] { "type": "warning", "body": "Bonsai clusters can be provisioned in a couple of different ways. These instructions are for Heroku users. If you have an account on Bonsai.io or via Manifold, then you will not need these instructions. Instead, check out:\n\n* [Getting Started With Bonsai.io](doc:getting-started-with-bonsaiio) \n* [Getting Started With Manifold](doc:getting-started-with-manifold)", "title": "Hold up!" } [/block] [block:api-header] { "type": "basic", "title": "Installing Bonsai Elasticsearch" } [/block] Adding Bonsai to your app automatically creates a cluster for you. It also adds a variable called BONSAI_URL to your application's environment, which will contain the canonical URL and credentials to your Elasticsearch cluster. This automation makes it fast and easy to get started with your new cluster. [block:callout] { "type": "info", "body": "We offer a free Sandbox 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.", "title": "Our Heroku Add-on" } [/block] There are two ways to add Bonsai to your Heroku app: 1. Through the Heroku CLI tool 2. Through the Heroku app dashboard [block:api-header] { "type": "basic", "title": "Using the Heroku CLI tool" } [/block] You can add Bonsai Elasticsearch to your app with this command: [block:code] { "codes": [ { "code": "$ heroku addons:add bonsai\n\t-----> Adding bonsai to some-appname-4005... done, v18 (free)", "language": "curl" } ] } [/block] You can verify that the operation was successful by running `heroku config:get BONSAI_URL`: [block:code] { "codes": [ { "code": "$ heroku config:get BONSAI_URL\n\t-----> http://username:password@redwood-12345.us-east-1.bonsai.io/", "language": "curl" } ] } [/block] 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](mailto:support@bonsai.io). Once the Add-on has been successfully added, you can check on the status of your cluster by running `$ heroku addons:open bonsai -a <your app>` ### Adding a specific version of Elasticsearch You have a fair amount of flexibility to choose the version of Elasticsearch your cluster can run. There is a command line flag for specifying which version to use. This flag is called `--version` and it can be invoked in a couple different ways. To use it on the command line, you would use something like this: [block:code] { "codes": [ { "code": "heroku addons:create bonsai:[plan] [-a APP_NAME] [--version=X.Y]", "language": "shell" } ] } [/block] Bonsai only supports certain versions of Elasticsearch, so users can not provision _any_ version. If you request a version that is not available, Bonsai will return an error message indicating what versions are available: [block:code] { "codes": [ { "code": "heroku addons:create bonsai --version=1.2.3\nCreating bonsai on ⬢ someapp... !\n ▸ An error was encountered when contacting the add-on partner to create bonsai:sandbox-6: The requested version [1.2.3] is not available in this region on your plan. Available options are: 1.7.5, 2.4.0, 5.3.2, 5.4.3, 5.6.8, 6.0.1\n", "language": "shell" } ] } [/block] In addition to the error message, there is a list of available versions documented here: [Supported Elasticsearch Versions](https://docs.bonsai.io/docs/supported-elasticsearch-versions). In short, the options available will be determined by three factors: 1. **Region.** Your cluster will be provisioned in the same AWS region where your Heroku app is located. However, some regions support more versions than other regions, based on demand. 2. **Plan.** Versions are rolled out to Sandbox and Staging tier plans in advance of Production grade plans. Additionally, older versions of Elasticsearch may only be supported on Dedicated tier plans. 3. **Age.** Bonsai will occasionally deprecate older versions of Elasticsearch. If you need a version of Elasticsearch that is no longer supported, the only way to get it will be to upgrade to a [Dedicated plan](https://bonsai.io/pricing). The `version` parameter also works in your app.json, if you use PR apps and Heroku pipelines: [block:code] { "codes": [ { "code": "{\n \"name\": \"Small Sharp Tool\",\n \"description\": \"This app does one little thing, and does it well.\",\n \"keywords\": [\n \"productivity\",\n \"HTML5\",\n \"scalpel\"\n ],\n \"addons\" : [\n {\n \t\"plan\": \"bonsai:sandbox\",\n \"options\": {\n \"version\": \"2.4.0\"\n }\n }\n ]\n}", "language": "json" } ] } [/block] For further help with your app.json and addons, see Heroku's documentation here: - [Heroku App JSON Schema](https://devcenter.heroku.com/articles/app-json-schema#addons) [block:api-header] { "type": "basic", "title": "Using the Heroku dashboard" } [/block] To add Bonsai through the Heroku UI, open up your application in the Heroku dashboard: [block:image] { "images": [ { "image": [ "https://files.readme.io/f00ad18-getting-started-1.png", "getting-started-1.png", 541, 517, "#ecf3f4" ], "caption": "The Heroku App Dashboard." } ] } [/block] 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: [block:image] { "images": [ { "image": [ "https://files.readme.io/a4d4f1a-getting-started-2.png", "getting-started-2.png", 953, 523, "#ecf3f4" ], "caption": "The Resources tab shows how many addons the app has added." } ] } [/block] 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](https://elements.heroku.com/addons/bonsai) page for details about what each plan offers. [block:image] { "images": [ { "image": [ "https://files.readme.io/94e1625-getting-started-3.png", "getting-started-3.png", 501, 425, "#8f8daa" ], "caption": "You can select the plan for Bonsai when adding it to your app." } ] } [/block] When you are ready, click on "Provision." Your new cluster will be instantly created. Your dashboard will now show this: [block:image] { "images": [ { "image": [ "https://files.readme.io/0512494-getting-started-4.png", "getting-started-4.png", 931, 255, "#f0f7f9" ], "caption": "The flash message indicates that Bonsai has been successfully added." } ] } [/block] 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": [block:image] { "images": [ { "image": [ "https://files.readme.io/7f814b3-getting-started-5.png", "getting-started-5.png", 485, 162, "#7c7e9c" ], "caption": "You can see the environment variables set for your application by revealing the Config Vars." } ] } [/block] Click on "Reveal Config Vars" to see your environment variables. This will reveal the value of each variable like so: [block:image] { "images": [ { "image": [ "https://files.readme.io/a4a8f8b-getting-started-6.png", "getting-started-6.png", 916, 222, "#f1f3f6" ], "caption": "The `BONSAI_URL` variable shows the URL to your app's Elasticsearch cluster." } ] } [/block] 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: [block:code] { "codes": [ { "code": "$ curl https://username:password@somehost-1234567.us-east-1.bonsai.io\n{\n \"name\" : \"PvRcoFq\",\n \"cluster_name\" : \"elasticsearch\",\n \"cluster_uuid\" : \"DNlbVYS0TIGYwbQ6CUNwTw\",\n \"version\" : {\n \"number\" : \"5.4.3\",\n \"build_hash\" : \"eed30a8\",\n \"build_date\" : \"2017-06-22T00:34:03.743Z\",\n \"build_snapshot\" : false,\n \"lucene_version\" : \"6.5.1\"\n },\n \"tagline\" : \"You Know, for Search\"\n}\n", "language": "shell" } ] } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/990bae9-getting-started-7.png", "getting-started-7.png", 604, 328, "#0b74e4" ], "caption": "You can copy/paste the cluster URL into a browser to see the cluster information. NOTE: the randomly-generated username and password must be included or the request will return an HTTP 429 error." } ] } [/block] [block:callout] { "type": "warning", "title": "HTTP 401: Authentication required", "body": "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." } [/block] [block:callout] { "type": "danger", "title": "Keep Your URL Secret", "body": "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:\n\nBad: \"My cluster is https://username:password@somehost-1234567.us-east-1.bonsaisearch.net\"\n\nGood: \"My cluster is somehost-1234567\"\n\nIf your URL is leaked somehow, you can regenerate the credentials. See [The Dashboard](doc:bonsai-elasticsearch-dashboard) for more information." } [/block] [block:api-header] { "type": "basic", "title": "Next Steps" } [/block] Now that you have created your cluster and verified that it is up and running, let's take a look at [The Dashboard](doc:bonsai-elasticsearch-dashboard). Want to create some indices? [block:callout] { "type": "warning", "body": "Bonsai has index auto-creation disabled by default, so if your integration requires indices to be set up, now might be a good time to [create your first indices](doc:creating-your-first-index).", "title": "Trouble Creating Indices?" } [/block]