{"_id":"567af469b56bac0d0019d887","parentDoc":null,"version":{"_id":"5633ec007e9e880d00af1a56","project":"5633ebff7e9e880d00af1a53","__v":15,"createdAt":"2015-10-30T22:15:28.105Z","releaseDate":"2015-10-30T22:15:28.105Z","categories":["5633ec007e9e880d00af1a57","5633f072737ea01700ea329d","5637a37d0704070d00f06cf4","5637cf4e7ca5de0d00286aeb","564503082c74cf1900da48b4","564503cb7f1fff210078e70a","567af26cb56bac0d0019d87d","567afeb8802b2b17005ddea0","567aff47802b2b17005ddea1","567b0005802b2b17005ddea3","568adfffcbd4ca0d00aebf7e","56ba80078cf7c9210009673e","574d127f6f075519007da3d0","574fde60aef76a0e00840927","57a22ba6cd51b22d00f623a0"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"__v":9,"category":{"_id":"567afeb8802b2b17005ddea0","project":"5633ebff7e9e880d00af1a53","pages":["56b3cd7ac25dea2b00b0caf6"],"version":"5633ec007e9e880d00af1a56","__v":1,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-12-23T20:06:16.013Z","from_sync":false,"order":2,"slug":"quickstart-guides-1","title":"Quickstart Guides"},"project":"5633ebff7e9e880d00af1a53","user":"5633ec9b35355017003ca3f2","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-12-23T19:22:17.688Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"Users of Django/Haystack can easily integrate with Bonsai Elasticsearch! We recommend using the [official Python client](http://www.elasticsearch.org/guide/en/elasticsearch/client/python-api/current/), as it is being actively developed alongside Elasticsearch. Let's get started:\n\n\n## Adding the Elasticsearch library\n\nYou'll need to add the elasticsearch-py and django-haystack libraries to your `requirements.txt` file:\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"elasticsearch>=1.0.0,<2.0.0\\ndjango-haystack>=1.0.0,<2.0.0\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Connecting to Bonsai\"\n}\n[/block]\nBonsai requires basic authentication for all read/write requests. You'll need to configure the client so that it includes the username and password when communicating with the cluster. We recommend adding the cluster URL to an environment variable, `BONSAI_URL`, to avoid hard-coding your authentication credentials.\n\nThe following code is a good starter for integrating Bonsai Elasticsearch into your app:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"ES_URL = urlparse(os.environ.get('BONSAI_URL') or 'http://127.0.0.1:9200/')\\n\\nHAYSTACK_CONNECTIONS = {\\n    'default': {\\n        'ENGINE': 'haystack.backends.elasticsearch_backend.ElasticsearchSearchEngine',\\n        'URL': ES_URL.scheme + '://' + ES_URL.hostname + ':443',\\n        'INDEX_NAME': 'haystack',\\n    },\\n}\\n\\nif ES_URL.username:\\n    HAYSTACK_CONNECTIONS['default']['KWARGS'] = {\\\"http_auth\\\": ES_URL.username + ':' + ES_URL.password}\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Note about ports\",\n  \"body\": \"The sample code above uses port 443, which is the default for the https:// protocol. If you're not using SSL/TLS and want to use http:// instead, change this value to 80.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Common Issues\"\n}\n[/block]\nOne of the most common issues users see relates to SSL certs. Bonsai URLs are using TLS to secure communications with the cluster, and our certificates are signed by an authority (CA) that has verified our identity. Python needs access to the proper root certificate in order to verify that the app is actually communicating with Bonsai; if it can't find the certificate it needs, you'll start seeing exception messages like this:\n\n`Root certificates are missing for certificate`\n\nThe fix is straightforward enough. Simply install the [certifi](https://pypi.python.org/pypi/certifi) package in the environment where your app is hosted. You can do this locally by running `pip install certifi`. **Heroku users** will also need to modify their `requirements.txt`, [per the documentation](https://devcenter.heroku.com/articles/python-pip):\n\n```\ncertifi==0.0.8\n```\n\n## I can't install root certificates or certifi\n\nIf certifi and root cert management isn't possible, you can simply bypass verification by modifying your `HAYSTACK_CONNECTIONS` like so:\n\n```\nHAYSTACK_CONNECTIONS = {\n    'default': {\n            'ENGINE': 'haystack.backends.elasticsearch_backend.ElasticsearchSearchEngine',\n            'URL': ES_URL.scheme + '://' + ES_URL.hostname + ':443',\n            'INDEX_NAME': 'documents',\n            'KWARGS': {\n              'use_ssl': True,\n              'verify_certs': False,\n            }\n     },\n}\n```\n\nThis instructs Haystack to use TLS without verifying the host. This does allow for the possibility of MITM attacks, but the probably of that happening is pretty low. You'll need to weigh the expediency of this approach against the unlikely event of someone eavesdropping, and decide whether there is an acceptable security risk of leaking data in that way.","excerpt":"","slug":"django-haystack","type":"basic","title":"Django/Haystack"}
Users of Django/Haystack can easily integrate with Bonsai Elasticsearch! We recommend using the [official Python client](http://www.elasticsearch.org/guide/en/elasticsearch/client/python-api/current/), as it is being actively developed alongside Elasticsearch. Let's get started: ## Adding the Elasticsearch library You'll need to add the elasticsearch-py and django-haystack libraries to your `requirements.txt` file: [block:code] { "codes": [ { "code": "elasticsearch>=1.0.0,<2.0.0\ndjango-haystack>=1.0.0,<2.0.0", "language": "text" } ] } [/block] [block:api-header] { "type": "basic", "title": "Connecting to Bonsai" } [/block] Bonsai requires basic authentication for all read/write requests. You'll need to configure the client so that it includes the username and password when communicating with the cluster. We recommend adding the cluster URL to an environment variable, `BONSAI_URL`, to avoid hard-coding your authentication credentials. The following code is a good starter for integrating Bonsai Elasticsearch into your app: [block:code] { "codes": [ { "code": "ES_URL = urlparse(os.environ.get('BONSAI_URL') or 'http://127.0.0.1:9200/')\n\nHAYSTACK_CONNECTIONS = {\n 'default': {\n 'ENGINE': 'haystack.backends.elasticsearch_backend.ElasticsearchSearchEngine',\n 'URL': ES_URL.scheme + '://' + ES_URL.hostname + ':443',\n 'INDEX_NAME': 'haystack',\n },\n}\n\nif ES_URL.username:\n HAYSTACK_CONNECTIONS['default']['KWARGS'] = {\"http_auth\": ES_URL.username + ':' + ES_URL.password}", "language": "python" } ] } [/block] [block:callout] { "type": "info", "title": "Note about ports", "body": "The sample code above uses port 443, which is the default for the https:// protocol. If you're not using SSL/TLS and want to use http:// instead, change this value to 80." } [/block] [block:api-header] { "type": "basic", "title": "Common Issues" } [/block] One of the most common issues users see relates to SSL certs. Bonsai URLs are using TLS to secure communications with the cluster, and our certificates are signed by an authority (CA) that has verified our identity. Python needs access to the proper root certificate in order to verify that the app is actually communicating with Bonsai; if it can't find the certificate it needs, you'll start seeing exception messages like this: `Root certificates are missing for certificate` The fix is straightforward enough. Simply install the [certifi](https://pypi.python.org/pypi/certifi) package in the environment where your app is hosted. You can do this locally by running `pip install certifi`. **Heroku users** will also need to modify their `requirements.txt`, [per the documentation](https://devcenter.heroku.com/articles/python-pip): ``` certifi==0.0.8 ``` ## I can't install root certificates or certifi If certifi and root cert management isn't possible, you can simply bypass verification by modifying your `HAYSTACK_CONNECTIONS` like so: ``` HAYSTACK_CONNECTIONS = { 'default': { 'ENGINE': 'haystack.backends.elasticsearch_backend.ElasticsearchSearchEngine', 'URL': ES_URL.scheme + '://' + ES_URL.hostname + ':443', 'INDEX_NAME': 'documents', 'KWARGS': { 'use_ssl': True, 'verify_certs': False, } }, } ``` This instructs Haystack to use TLS without verifying the host. This does allow for the possibility of MITM attacks, but the probably of that happening is pretty low. You'll need to weigh the expediency of this approach against the unlikely event of someone eavesdropping, and decide whether there is an acceptable security risk of leaking data in that way.