Adds a quickstart guide (#1739)
* Beginning quickstart guide Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Add sample docker compose yaml to assets Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Adding verbiage about compose commands Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * More additions but saving before a lunch break Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Remove sample compose file from the quickstart guide since it is linked externally Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Added first common problem Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Formatting of common issues - oh and I renamed it common issues because problems sounds too negative Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Formatting Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Adding more content. I love Starbucks White Chocolate Mocha creamer Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Indentation Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Added common issue re: docker perms Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Changing the common issues section around a bit so the ordering makes more sense Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Removed blank target from important settings links since we don't do that for other links Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Updates Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Committing changes Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Added newline to docker compose file and started working on steps in the guide Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Adding steps Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Added cURL command for example query Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Reworded intro paragraph and added more steps. Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Added tip about using the pretty query parameter Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Editing Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Added dashboards content and working on next steps segue Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Wrapping up for the day Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Cleaning up before reviews Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Finishing up Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Editorial fixes Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Final editorial changes Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Changes relating to PM review Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Incorporating feedback from docs review Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> * Final changes Signed-off-by: JeffH-AWS <jeffhuss@amazon.com> Signed-off-by: JeffH-AWS <jeffhuss@amazon.com>
This commit is contained in:
Jeff Huss
GitHub
parent
8493efbf70
commit
0d488028c6
167
_opensearch/install/quickstart.md
Normal file
167
_opensearch/install/quickstart.md
Normal file
@ -0,0 +1,167 @@
|
||||
---
|
||||
layout: default
|
||||
title: Quickstart guide
|
||||
parent: Install OpenSearch
|
||||
nav_order: 1
|
||||
---
|
||||
|
||||
# Quickstart guide
|
||||
|
||||
Get started using OpenSearch and OpenSearch Dashboards by deploying your containers with [Docker](https://www.docker.com/). Before proceeding, you need to [get Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://github.com/docker/compose) installed on your local machine.
|
||||
|
||||
The Docker Compose commands used in this guide are written with a hyphen (for example, `docker-compose`). If you installed Docker Desktop on your machine, which automatically installs a bundled version of Docker Compose, then you should remove the hyphen. For example, change `docker-compose` to `docker compose`.
|
||||
{: .note}
|
||||
|
||||
## Starting your cluster
|
||||
|
||||
You'll need a special file, called a Compose file, that Docker Compose uses to define and create the containers in your cluster. The OpenSearch Project provides a sample Compose file that you can use to get started. Learn more about working with Compose files by reviewing the official [Compose specification](https://docs.docker.com/compose/compose-file/).
|
||||
|
||||
1. Before running OpenSearch on your machine, you should review and apply these [important system settings]({{site.url}}{{site.baseurl}}/opensearch/install/important-settings/).
|
||||
- Disable memory paging and swapping performance on the host to improve performance.
|
||||
```bash
|
||||
sudo swapoff -a
|
||||
```
|
||||
- Increase the number of memory maps available to OpenSearch.
|
||||
```bash
|
||||
# Edit the sysctl config file.
|
||||
sudo vi /etc/sysctl.conf
|
||||
|
||||
# Define the max map count.
|
||||
vm.max_map_count=262144
|
||||
|
||||
# Reload the kernel parameters.
|
||||
sudo sysctl -p
|
||||
```
|
||||
1. Download the sample Compose file to your host. You can download the file with command line utilities like `curl` and `wget`, or you can manually copy [docker-compose.yml](https://github.com/opensearch-project/documentation-website/tree/{{site.opensearch_version}}/assets/examples/docker-compose.yml) from the OpenSearch Project documentation-website repository using a web browser.
|
||||
```bash
|
||||
# Using cURL:
|
||||
curl -O https://github.com/opensearch-project/documentation-website/tree/{{site.opensearch_version}}/assets/examples/docker-compose.yml
|
||||
|
||||
# Using wget:
|
||||
wget https://github.com/opensearch-project/documentation-website/tree/{{site.opensearch_version}}/assets/examples/docker-compose.yml
|
||||
```
|
||||
1. In your terminal application, navigate to the directory containing the `docker-compose.yml` file you just downloaded, and run the following command to create and start the cluster as a background process.
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
1. Confirm that the containers are running with the command `docker-compose ps`. You should see an output like the following:
|
||||
```bash
|
||||
$ docker-compose ps
|
||||
NAME COMMAND SERVICE STATUS PORTS
|
||||
opensearch-dashboards "./opensearch-dashbo…" opensearch-dashboards running 0.0.0.0:5601->5601/tcp
|
||||
opensearch-node1 "./opensearch-docker…" opensearch-node1 running 0.0.0.0:9200->9200/tcp, 9300/tcp, 0.0.0.0:9600->9600/tcp, 9650/tcp
|
||||
opensearch-node2 "./opensearch-docker…" opensearch-node2 running 9200/tcp, 9300/tcp, 9600/tcp, 9650/tcp
|
||||
```
|
||||
1. Query the OpenSearch REST API to verify that the service is running. You should use `-k` (also written as `--insecure`) to disable host name checking because the default security configuration uses demo certificates. Use `-u` to pass the default username and password (`admin:admin`).
|
||||
```bash
|
||||
curl https://localhost:9200 -ku admin:admin
|
||||
```
|
||||
- Sample response:
|
||||
```json
|
||||
{
|
||||
"name" : "opensearch-node1",
|
||||
"cluster_name" : "opensearch-cluster",
|
||||
"cluster_uuid" : "Cd7SL5ysRSyuau325M3h9w",
|
||||
"version" : {
|
||||
"distribution" : "opensearch",
|
||||
"number" : "2.3.0",
|
||||
"build_type" : "tar",
|
||||
"build_hash" : "6f6e84ebc54af31a976f53af36a5c69d474a5140",
|
||||
"build_date" : "2022-09-09T00:07:12.137133581Z",
|
||||
"build_snapshot" : false,
|
||||
"lucene_version" : "9.3.0",
|
||||
"minimum_wire_compatibility_version" : "7.10.0",
|
||||
"minimum_index_compatibility_version" : "7.0.0"
|
||||
},
|
||||
"tagline" : "The OpenSearch Project: https://opensearch.org/"
|
||||
}
|
||||
```
|
||||
1. Explore OpenSearch Dashboards by opening `http://localhost:5601/` in a web browser on the same host that is running your OpenSearch cluster.
|
||||
- The default username is `admin` and the default password is `admin`.
|
||||
|
||||
## Create an index and field mappings using sample data
|
||||
|
||||
Create an index and define field mappings using a dataset provided by the OpenSearch Project. The same fictitious e-commerce data is also used for sample visualizations in OpenSearch Dashboards. To learn more, see [Getting started with OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/dashboards/index/).
|
||||
|
||||
1. Download [ecommerce-field_mappings.json](https://github.com/opensearch-project/documentation-website/blob/{{site.opensearch_version}}/assets/examples/ecommerce-field_mappings.json). This file defines a [mapping]({{site.url}}{{site.baseurl}}/opensearch/mappings/) for the sample data you will use.
|
||||
```bash
|
||||
# Using cURL:
|
||||
curl -O https://github.com/opensearch-project/documentation-website/blob/{{site.opensearch_version}}/assets/examples/ecommerce-field_mappings.json
|
||||
|
||||
# Using wget:
|
||||
wget https://github.com/opensearch-project/documentation-website/blob/{{site.opensearch_version}}/assets/examples/ecommerce-field_mappings.json
|
||||
```
|
||||
1. Download [ecommerce.json](https://github.com/opensearch-project/documentation-website/blob/{{site.opensearch_version}}/assets/examples/ecommerce.json). This file contains the index data formatted so that it can be ingested by the bulk API. To learn more, see [index data]({{site.url}}{{site.baseurl}}/opensearch/index-data/) and [Bulk]({{site.url}}{{site.baseurl}}/api-reference/document-apis/bulk/).
|
||||
```bash
|
||||
# Using cURL:
|
||||
curl -O https://github.com/opensearch-project/documentation-website/blob/{{site.opensearch_version}}/assets/examples/ecommerce.json
|
||||
|
||||
# Using wget:
|
||||
wget https://github.com/opensearch-project/documentation-website/blob/{{site.opensearch_version}}/assets/examples/ecommerce.json
|
||||
```
|
||||
1. Define the field mappings with the mapping file.
|
||||
```bash
|
||||
curl -H "Content-Type: application/x-ndjson" -X PUT "https://localhost:9200/ecommerce" -ku admin:admin --data-binary "@ecommerce-field_mappings.json"
|
||||
```
|
||||
1. Upload the index to the bulk API.
|
||||
```bash
|
||||
curl -H "Content-Type: application/x-ndjson" -X PUT "https://localhost:9200/ecommerce/_bulk" -ku admin:admin --data-binary "@ecommerce.json"
|
||||
```
|
||||
1. Query the data using the search API. The following command submits a query that will return documents where `customer_first_name` is `Sonya`.
|
||||
```bash
|
||||
curl -H 'Content-Type: application/json' -X GET "https://localhost:9200/ecommerce/_search?pretty=true" -ku admin:admin -d' {"query":{"match":{"customer_first_name":"Sonya"}}}'
|
||||
```
|
||||
- Add the query parameter `pretty=true` to OpenSearch API requests that return a JSON to see a more readable version of the response body. Otherwise, the response will be a flat JSON. For more information about `pretty` and other query parameters, see [Common REST parameters]({{site.url}}{{site.baseurl}}/opensearch/common-parameters/).
|
||||
1. Access OpenSearch Dashboards by opening `http://localhost:5601/` in a web browser on the same host that is running your OpenSearch cluster.
|
||||
- The default username is `admin` and the default password is `admin`.
|
||||
1. On the top menu bar, go to **Management > Dev Tools**.
|
||||
1. In the left pane of the console, enter the following:
|
||||
```json
|
||||
GET ecommerce/_search
|
||||
{
|
||||
"query": {
|
||||
"match": {
|
||||
"customer_first_name": "Sonya"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
1. Choose the triangle icon at the top right of the request to submit the query. You can also submit the request by pressing `Ctrl+Enter` (or `Cmd+Enter` for Mac users). To learn more about using the OpenSearch Dashboards console for submitting queries, see [Running queries in the console]({{site.url}}{{site.baseurl}}/dashboards/run-queries/).
|
||||
|
||||
## Next steps
|
||||
|
||||
You successfully deployed your own OpenSearch cluster with OpenSearch Dashboards and added some sample data. Now you're ready to learn about configuration and functionality in more detail. Here are a few recommendations on where to begin:
|
||||
- [About the security plugin]({{site.url}}{{site.baseurl}}/security-plugin/index/)
|
||||
- [OpenSearch configuration]({{site.url}}{{site.baseurl}}/opensearch/configuration/)
|
||||
- [OpenSearch plugin installation]({{site.url}}{{site.baseurl}}/opensearch/install/plugins/)
|
||||
- [Getting started with OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/dashboards/index/)
|
||||
- [OpenSearch tools]({{site.url}}{{site.baseurl}}/tools/index/)
|
||||
- [Index APIs]({{site.url}}{{site.baseurl}}/api-reference/index-apis/index/)
|
||||
|
||||
## Common issues
|
||||
|
||||
Review these common issues and suggested solutions if your containers fail to start or exit unexpectedly.
|
||||
|
||||
### Docker commands require elevated permissions
|
||||
|
||||
Eliminate the need for running your Docker commands with `sudo` by adding your user to the `docker` user group. See Docker's [Post-installation steps for Linux](https://docs.docker.com/engine/install/linux-postinstall/) for more information.
|
||||
```bash
|
||||
sudo usermod -aG docker $USER
|
||||
```
|
||||
|
||||
### Error message: "-bash: docker-compose: command not found"
|
||||
|
||||
If you installed Docker Desktop, then Docker Compose is already installed on your machine. Try `docker compose` (without the hyphen) instead of `docker-compose`. See [Use Docker Compose](https://docs.docker.com/get-started/08_using_compose/).
|
||||
|
||||
### Error message: "docker: 'compose' is not a docker command."
|
||||
|
||||
If you installed Docker Engine, then you must install Docker Compose separately, and you will use the command `docker-compose` (with a hyphen). See [Docker Compose](https://github.com/docker/compose).
|
||||
|
||||
### Error message: "max virtual memory areas vm.max_map_count [65530] is too low"
|
||||
|
||||
OpenSearch will fail to start if your host's `vm.max_map_count` is too low. Review the [important system settings]({{site.url}}{{site.baseurl}}/opensearch/install/important-settings/) if you see the following errors in the service log, and set `vm.max_map_count` appropriately.
|
||||
```bash
|
||||
opensearch-node1 | ERROR: [1] bootstrap checks failed
|
||||
opensearch-node1 | [1]: max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]
|
||||
opensearch-node1 | ERROR: OpenSearch did not exit normally - check the logs at /usr/share/opensearch/logs/opensearch-cluster.log
|
||||
```
|
||||
66
assets/examples/docker-compose.yml
Normal file
66
assets/examples/docker-compose.yml
Normal file
@ -0,0 +1,66 @@
|
||||
version: '3'
|
||||
services:
|
||||
opensearch-node1: # This is also the hostname of the container within the Docker network (i.e. https://opensearch-node1/)
|
||||
image: opensearchproject/opensearch:latest
|
||||
container_name: opensearch-node1
|
||||
environment:
|
||||
- cluster.name=opensearch-cluster # Name the cluster
|
||||
- node.name=opensearch-node1 # Name the node that will run in this container
|
||||
- discovery.seed_hosts=opensearch-node1,opensearch-node2 # Nodes to look for when discovering the cluster
|
||||
- cluster.initial_cluster_manager_nodes=opensearch-node1,opensearch-node2 # Nodes eligibile to serve as cluster manager
|
||||
- bootstrap.memory_lock=true # Disable JVM heap memory swapping
|
||||
- "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" # Set min and max JVM heap sizes to at least 50% of system RAM
|
||||
ulimits:
|
||||
memlock:
|
||||
soft: -1 # Set memlock to unlimited (no soft or hard limit)
|
||||
hard: -1
|
||||
nofile:
|
||||
soft: 65536 # Maximum number of open files for the opensearch user - set to at least 65536
|
||||
hard: 65536
|
||||
volumes:
|
||||
- opensearch-data1:/usr/share/opensearch/data # Creates volume called opensearch-data1 and mounts it to the container
|
||||
ports:
|
||||
- 9200:9200 # REST API
|
||||
- 9600:9600 # Performance Analyzer
|
||||
networks:
|
||||
- opensearch-net # All of the containers will join the same Docker bridge network
|
||||
opensearch-node2:
|
||||
image: opensearchproject/opensearch:latest # This should be the same image used for opensearch-node1 to avoid issues
|
||||
container_name: opensearch-node2
|
||||
environment:
|
||||
- cluster.name=opensearch-cluster
|
||||
- node.name=opensearch-node2
|
||||
- discovery.seed_hosts=opensearch-node1,opensearch-node2
|
||||
- cluster.initial_cluster_manager_nodes=opensearch-node1,opensearch-node2
|
||||
- bootstrap.memory_lock=true
|
||||
- "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m"
|
||||
ulimits:
|
||||
memlock:
|
||||
soft: -1
|
||||
hard: -1
|
||||
nofile:
|
||||
soft: 65536
|
||||
hard: 65536
|
||||
volumes:
|
||||
- opensearch-data2:/usr/share/opensearch/data
|
||||
networks:
|
||||
- opensearch-net
|
||||
opensearch-dashboards:
|
||||
image: opensearchproject/opensearch-dashboards:latest # Make sure the version of opensearch-dashboards matches the version of opensearch installed on other nodes
|
||||
container_name: opensearch-dashboards
|
||||
ports:
|
||||
- 5601:5601 # Map host port 5601 to container port 5601
|
||||
expose:
|
||||
- "5601" # Expose port 5601 for web access to OpenSearch Dashboards
|
||||
environment:
|
||||
OPENSEARCH_HOSTS: '["https://opensearch-node1:9200","https://opensearch-node2:9200"]' # Define the OpenSearch nodes that OpenSearch Dashboards will query
|
||||
networks:
|
||||
- opensearch-net
|
||||
|
||||
volumes:
|
||||
opensearch-data1:
|
||||
opensearch-data2:
|
||||
|
||||
networks:
|
||||
opensearch-net:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user