Adds a quickstart guide (#1739)

* Beginning quickstart guide Signed-off-by: JeffH-AWS <[email protected]> * Add sample docker compose yaml to assets Signed-off-by: JeffH-AWS <[email protected]> * Adding verbiage about compose commands Signed-off-by: JeffH-AWS <[email protected]> * More additions but saving before a lunch break Signed-off-by: JeffH-AWS <[email protected]> * Remove sample compose file from the quickstart guide since it is linked externally Signed-off-by: JeffH-AWS <[email protected]> * Added first common problem Signed-off-by: JeffH-AWS <[email protected]> * Formatting of common issues - oh and I renamed it common issues because problems sounds too negative Signed-off-by: JeffH-AWS <[email protected]> * Formatting Signed-off-by: JeffH-AWS <[email protected]> * Adding more content. I love Starbucks White Chocolate Mocha creamer Signed-off-by: JeffH-AWS <[email protected]> * Indentation Signed-off-by: JeffH-AWS <[email protected]> * Added common issue re: docker perms Signed-off-by: JeffH-AWS <[email protected]> * Changing the common issues section around a bit so the ordering makes more sense Signed-off-by: JeffH-AWS <[email protected]> * Removed blank target from important settings links since we don't do that for other links Signed-off-by: JeffH-AWS <[email protected]> * Updates Signed-off-by: JeffH-AWS <[email protected]> * Committing changes Signed-off-by: JeffH-AWS <[email protected]> * Added newline to docker compose file and started working on steps in the guide Signed-off-by: JeffH-AWS <[email protected]> * Adding steps Signed-off-by: JeffH-AWS <[email protected]> * Added cURL command for example query Signed-off-by: JeffH-AWS <[email protected]> * Reworded intro paragraph and added more steps. Signed-off-by: JeffH-AWS <[email protected]> * Added tip about using the pretty query parameter Signed-off-by: JeffH-AWS <[email protected]> * Editing Signed-off-by: JeffH-AWS <[email protected]> * Added dashboards content and working on next steps segue Signed-off-by: JeffH-AWS <[email protected]> * Wrapping up for the day Signed-off-by: JeffH-AWS <[email protected]> * Cleaning up before reviews Signed-off-by: JeffH-AWS <[email protected]> * Finishing up Signed-off-by: JeffH-AWS <[email protected]> * Editorial fixes Signed-off-by: JeffH-AWS <[email protected]> * Final editorial changes Signed-off-by: JeffH-AWS <[email protected]> * Changes relating to PM review Signed-off-by: JeffH-AWS <[email protected]> * Incorporating feedback from docs review Signed-off-by: JeffH-AWS <[email protected]> * Final changes Signed-off-by: JeffH-AWS <[email protected]> Signed-off-by: JeffH-AWS <[email protected]> (cherry picked from commit 0d48802)
opensearch-project · Nov 23, 2022 · 4792af8 · 4792af8
1 parent db3d47d
commit 4792af8
Show file tree

Hide file tree

Showing 2 changed files with 233 additions and 0 deletions.
diff --git a/_opensearch/install/quickstart.md b/_opensearch/install/quickstart.md
@@ -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
+```
diff --git a/assets/examples/docker-compose.yml b/assets/examples/docker-compose.yml
@@ -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:
+