{"_id":"5a948086f9c4390069a0b185","project":"5633ebff7e9e880d00af1a53","version":{"_id":"5a8fae0268264c001f20cc00","project":"5633ebff7e9e880d00af1a53","__v":4,"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","5b8ee7842790f8000333f9ba","5b8ee8f244a21a00034b5cd9"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2.0"},"category":{"_id":"5a8fae0268264c001f20cc01","version":"5a8fae0268264c001f20cc00","project":"5633ebff7e9e880d00af1a53","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-10-30T22:34:26.440Z","from_sync":false,"order":0,"slug":"early-project-setup","title":"Bonsai.io Basics"},"user":"5637d336aa96490d00a64f81","githubsync":"","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-02-26T21:47:50.408Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"Ready to provision an Elasticsearch 3-node cluster in less than 30 seconds? Read our guide below.\n\n# Choose your options using the Cluster form\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Hold Up!\",\n  \"body\": \"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:\\n\\n* [Getting Started With Heroku](doc:getting-started-with-heroku) \\n* [Getting Started With Manifold](doc:getting-started-with-manifold)\"\n}\n[/block]\nOnce your account [has been created](doc:creating-your-account), 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 a larger cluster with more resources, you can click on the link to [add a credit card](https://app.bonsai.io/account/billing) to your account. See [Managing Your Account](doc:managing-your-account) for more information.\n\nCreating your account will take you to the [Create a Cluster](https://app.bonsai.io/clusters/new) form. This form will allow you to specify some details about the cluster you want:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/dc0542d-FireShot_Capture_001_-_Create_a_new_cluster_-_https___app.bonsai.io_clusters_new.png\",\n        \"FireShot Capture 001 - Create a new cluster - https___app.bonsai.io_clusters_new.png\",\n        1160,\n        992,\n        \"#f3f3f3\"\n      ],\n      \"caption\": \"Overview of the cluster creation menu.\"\n    }\n  ]\n}\n[/block]\nThe 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.\n\nThere are several attributes that can be configured, which are discussed in detail below.\n[block:api-header]\n{\n  \"title\": \"Cluster Name\"\n}\n[/block]\nUsers 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. \n\nFor 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`.\n\nCluster names can be changed later, but the host name that is generated when the cluster is first created is immutable.\n[block:api-header]\n{\n  \"title\": \"Cluster Region\"\n}\n[/block]\nWe 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:\n\n* us-east-1 (Virginia)\n* us-west-2 (Oregon)\n* eu-west-1 (Ireland)\n* ap-southeast-2 (Sydney)\n* eu-central-1 (Frankfurt). \n\nThese regions are supported due to broad demand. We can support other regions as well, but pricing will vary. [Shoot us an email](mailto:support:::at:::bonsai.io) if you'd like to learn more about getting Bonsai running in a region not listed above.\n\nAlso 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.\n[block:api-header]\n{\n  \"title\": \"Elasticsearch Version\"\n}\n[/block]\nWe 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.\n\nWe can accomodate 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](mailto:support@bonsai.io) to discuss options.\n[block:api-header]\n{\n  \"title\": \"Cluster Plan\"\n}\n[/block]\nThe 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:\n\n* Free and Staging plans have the lowest limits\n* Production grade plans have limits suitable for production applications\n* Enterprise grade plans have no metering at all\n\nYou 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.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Free to Start!\",\n  \"body\": \"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.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Limitations\",\n  \"body\": \"While the first cluster can be free, customers are limited to a single free cluster for each production-grade (paid) cluster.\"\n}\n[/block]\nWhen you're ready to proceed, click on \"Create Cluster.\"\n\nCongratulations! Your Elasticsearch cluster will instantly be up and running, and you will be automatically routed to your cluster dashboard.\n[block:api-header]\n{\n  \"title\": \"Viewing Your Cluster\"\n}\n[/block]\nWhen you visit [your dashboard](https://app.bonsai.io/clusters), you'll see your new cluster listed:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/86ee100-Screen_Shot_2018-02-26_at_4.16.12_PM.png\",\n        \"Screen Shot 2018-02-26 at 4.16.12 PM.png\",\n        2560,\n        674,\n        \"#12567f\"\n      ],\n      \"caption\": \"The Login view. Logging in to Bonsai will take you to a dashboard listing all of your clusters.\"\n    }\n  ]\n}\n[/block]\nAt 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.\n\nClick 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:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/f90da02-Screen_Shot_2018-03-27_at_4.31.43_PM.png\",\n        \"Screen Shot 2018-03-27 at 4.31.43 PM.png\",\n        2512,\n        976,\n        \"#f3f3f3\"\n      ],\n      \"caption\": \"Cluster overview. This is the default landing view when accessing a specific cluster.\"\n    }\n  ]\n}\n[/block]\nThe cluster dashboard is covered in detail in [Exploring Your Cluster Dashboard](doc: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:\n\n**https://randomuser:randompass@strickland-propane-3917077713.us-east-1.bonsaisearch.net**\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Credentials are not your login\",\n  \"body\": \"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\\\"\"\n}\n[/block]\nBonsai clusters are configured to support [SSL/TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) and [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication) 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.\n\nYou can test that the cluster is available by using a tool like `curl`:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$ curl \\\"https://randomuser:randompass@strickland-propane-3917077713.us-east-1.bonsaisearch.net\\\"\\n\\n{\\n  \\\"name\\\": \\\"e_dJ9rV\\\",\\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\"\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://randomuser:randompass@strickland-propane-3917077713.us-east-1.bonsaisearch.net\\\"\\n\\nGood: \\\"My cluster is strickland-propane-3917077713\\\"\\n\\nIf your URL is leaked somehow, you can regenerate the credentials. See [Exploring Your Cluster Dashboard](doc:exploring-your-cluster-dashboard) for more information.\"\n}\n[/block]\nNow 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](doc:exploring-your-cluster-dashboard).","excerpt":"Instantly provision an Elasticsearch cluster","slug":"creating-your-first-cluster","type":"basic","title":"Creating Your First Cluster"}

Creating Your First Cluster

Instantly provision an Elasticsearch cluster

Ready to provision an Elasticsearch 3-node cluster in less than 30 seconds? Read our guide below. # Choose your options using the Cluster form [block:callout] { "type": "warning", "title": "Hold Up!", "body": "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:\n\n* [Getting Started With Heroku](doc:getting-started-with-heroku) \n* [Getting Started With Manifold](doc:getting-started-with-manifold)" } [/block] Once your account [has been created](doc:creating-your-account), 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 a larger cluster with more resources, you can click on the link to [add a credit card](https://app.bonsai.io/account/billing) to your account. See [Managing Your Account](doc:managing-your-account) for more information. Creating your account will take you to the [Create a Cluster](https://app.bonsai.io/clusters/new) form. This form will allow you to specify some details about the cluster you want: [block:image] { "images": [ { "image": [ "https://files.readme.io/dc0542d-FireShot_Capture_001_-_Create_a_new_cluster_-_https___app.bonsai.io_clusters_new.png", "FireShot Capture 001 - Create a new cluster - https___app.bonsai.io_clusters_new.png", 1160, 992, "#f3f3f3" ], "caption": "Overview of the cluster creation menu." } ] } [/block] 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. [block:api-header] { "title": "Cluster Name" } [/block] 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. [block:api-header] { "title": "Cluster Region" } [/block] 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](mailto:support@bonsai.io) 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. [block:api-header] { "title": "Elasticsearch Version" } [/block] 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 accomodate 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](mailto:support@bonsai.io) to discuss options. [block:api-header] { "title": "Cluster Plan" } [/block] 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. [block:callout] { "type": "info", "title": "Free to Start!", "body": "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." } [/block] [block:callout] { "type": "warning", "title": "Limitations", "body": "While the first cluster can be free, customers are limited to a single free cluster for each production-grade (paid) cluster." } [/block] 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. [block:api-header] { "title": "Viewing Your Cluster" } [/block] When you visit [your dashboard](https://app.bonsai.io/clusters), you'll see your new cluster listed: [block:image] { "images": [ { "image": [ "https://files.readme.io/86ee100-Screen_Shot_2018-02-26_at_4.16.12_PM.png", "Screen Shot 2018-02-26 at 4.16.12 PM.png", 2560, 674, "#12567f" ], "caption": "The Login view. Logging in to Bonsai will take you to a dashboard listing all of your clusters." } ] } [/block] 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: [block:image] { "images": [ { "image": [ "https://files.readme.io/f90da02-Screen_Shot_2018-03-27_at_4.31.43_PM.png", "Screen Shot 2018-03-27 at 4.31.43 PM.png", 2512, 976, "#f3f3f3" ], "caption": "Cluster overview. This is the default landing view when accessing a specific cluster." } ] } [/block] The cluster dashboard is covered in detail in [Exploring Your Cluster Dashboard](doc: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** [block:callout] { "type": "warning", "title": "Credentials are not your login", "body": "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\"" } [/block] Bonsai clusters are configured to support [SSL/TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) and [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication) 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`: [block:code] { "codes": [ { "code": "$ curl \"https://randomuser:randompass@strickland-propane-3917077713.us-east-1.bonsaisearch.net\"\n\n{\n \"name\": \"e_dJ9rV\",\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}", "language": "shell" } ] } [/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://randomuser:randompass@strickland-propane-3917077713.us-east-1.bonsaisearch.net\"\n\nGood: \"My cluster is strickland-propane-3917077713\"\n\nIf your URL is leaked somehow, you can regenerate the credentials. See [Exploring Your Cluster Dashboard](doc:exploring-your-cluster-dashboard) for more information." } [/block] 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](doc:exploring-your-cluster-dashboard).