Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updates Dev guide #1590

Merged
merged 7 commits into from
Apr 5, 2022
Merged

Updates Dev guide #1590

Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
41493dc
Updates Dev guide
DarshitChanpura Jan 28, 2022
c3ce697
Updates dev guide to account gradle migration
DarshitChanpura Feb 16, 2022
e46888d
Merge branch 'main' into dev-guide-update
DarshitChanpura Feb 16, 2022
feb0c41
Removes incorrect comment in dev guide
DarshitChanpura Feb 18, 2022
42a1c21
Adds a line that notes the Java versions that we currently support
DarshitChanpura Feb 22, 2022
457df27
Recommendationsons for the dev guide
peternied Apr 4, 2022
e08fe5b
Merge pull request #1 from peternied/dev-guide-update
DarshitChanpura Apr 4, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 23 additions & 10 deletions DEVELOPER_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,32 +7,41 @@ So you want to contribute code to this project? Excellent! We're glad you're her
- [Submitting Changes](#submitting-changes)

## Prerequisites
This project runs as a plugin of OpenSearch. You could [download a minimal release of OpenSearch](https://opensearch.org/downloads.html#minimal) and then install the plugin there, but at this time there are no MacOS distributions (although you can run it as a docker container, but those images come with the security plugin already preinstalled). In addition, it might come in handy to be able to always run against the latest commit of the version under development, so we'll be compiling it from source instead.

To get started, follow the [getting started section](https://github.com/opensearch-project/OpenSearch/blob/main/DEVELOPER_GUIDE.md#getting-started) of OpenSearch's developer guide. This will get you up and running with OpenSearch built from source code. Get to the point where you can run a successful `curl localhost:9200` call (you can skip the `./gradlew check` step to save some time. Great! now kill the server with `Ctrl+c` and copy the built code to a new folder somewhere else where you'll be running your service (run this from the base directory of the OpenSearch fork you cloned above):
>Please note:\
> OpenSearch builds on `gradle`, and this plugin is packaged using `maven`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we reference the instructions for how to install the jdk versions we support, OpenSearch has a markdown doc we could link?

> Please install Maven and JDK (We currently support versions 8, 11 and 14), if you haven't done so already.
peternied marked this conversation as resolved.
Show resolved Hide resolved

This project runs as a plugin of OpenSearch. You can [download a minimal release of OpenSearch](https://opensearch.org/downloads.html#minimal) and then install this plugin there. However, we will compile it using source code so that we are pulling in changes from the latest commit.
>**MacOS users please note:**\
>At this moment there are no MacOS distributions available for OpenSearch. Having said that, you have an option to run it as a Docker Container, but that will come with security plugin pre-installed which defeats the purpose of this setup.
peternied marked this conversation as resolved.
Show resolved Hide resolved

To get started, follow the [getting started section](https://github.com/opensearch-project/OpenSearch/blob/main/DEVELOPER_GUIDE.md#getting-started) of OpenSearch's developer guide. This will get OpenSearch up and running built from source code. You can skip the `./gradlew check` step to save some time. Reach to the point where you can run a successful `curl localhost:9200` call. Great! now kill the server with `Ctrl+c`.

Next, run the following commands to copy the built code (snapshot) to a new folder in a different location. (This where you'll be running OpenSearch service). Run this from the base directory of the OpenSearch fork you cloned above:
```bash
export OPENSEARCH_HOME=~/Test/opensearch-1.3.0-SNAPSHOT
export OPENSEARCH_HOME=~/<your-folder-location>/opensearch-1.3.0-SNAPSHOT
export OPENSEARCH_BUILD=distribution/archives/darwin-tar/build/install/opensearch-1.3.0-SNAPSHOT
cp -Rf $OPENSEARCH_BUILD $OPENSEARCH_HOME
```

Choose `$OPENSEARCH_HOME` as the base folder where your server will live, and adjust `$OPENSEARCH_BUILD` based on your version and OS (this is an example running on MacOS.)
Choose `$OPENSEARCH_HOME` as the base folder where your server will live, and adjust `$OPENSEARCH_BUILD` based on your version and OS (this is an example running on MacOS, hence `darwin`.)

Let's test it!
Let's test and see if we can run the server!

```bash
cd $OPENSEARCH_HOME
./bin/opensearch
```

The `curl localhost:9200` call from before should also succeed now. Kill the server again with `Ctrl+c`. We are ready to install the security plugin.
The `curl localhost:9200` call should succeed again. Kill the server with `Ctrl+c`. We are ready to install the security plugin.

>Worth noting is that the version of OpenSearch and the security plugin must match as there is an explicit version check at startup. This can be a bit confusing as, for example, at the time of this writing the `main` branch of this security plugin builds version `1.3.0.0-SNAPSHOT`, compatible with OpenSearch `1.3.0-SNAPSHOT` that gets built from branch `1.x`. Check the expected compatible version [here](https://github.com/opensearch-project/security/blob/main/plugin-descriptor.properties#L27) and make sure you get the correct branch from OpenSearch when building that project.
>Worth noting:\
> The version of OpenSearch and the security plugin must match as there is an explicit version check at startup. This can be a bit confusing as, for example, at the time of writing this guide, the `main` branch of this security plugin builds version `1.3.0.0-SNAPSHOT` compatible with OpenSearch `1.3.0-SNAPSHOT` that gets built from branch `1.x`. Check the expected compatible version [here](https://github.com/opensearch-project/security/blob/main/plugin-descriptor.properties#L27) and make sure you get the correct branch from OpenSearch when building that project.

## Building

First create a fork of this repo and clone it locally. Changing into the directory of the newly cloned repository, run the following to build the project:
First create a fork of this repo and clone it locally. Changing to directory containing this clone and run this to build the project:

```bash
./gradlew clean assemble
Expand All @@ -42,6 +51,7 @@ Install the built plugin into the OpenSearch server:

```bash
export OPENSEARCH_SECURITY_HOME=$OPENSEARCH_HOME/plugins/opensearch-security
mkdir $OPENSEARCH_SECURITY_HOME
cp build/distributions/opensearch-security-1.3.0.0-SNAPSHOT.zip $OPENSEARCH_SECURITY_HOME
cd $OPENSEARCH_SECURITY_HOME
unzip opensearch-security-1.3.0.0-SNAPSHOT.zip
Expand All @@ -50,7 +60,7 @@ rm opensearch-security-1.3.0.0-SNAPSHOT.zip

You will have to adjust it to your specific version. In this example I'm using `1.3.0.0-SNAPSHOT`.

Install the demo certificates and default configuration, answer `y` to the first two questions and `n` to the last one:
Install the demo certificates and default configuration, answer `y` to the first two questions and `n` to the last one. The log should look like below:

```bash
./tools/install_demo_configuration.sh
Expand Down Expand Up @@ -84,7 +94,10 @@ Detected OpenSearch Security Version: *
### (Ignore the SSL certificate warning because we installed self-signed demo certificates)
```

Now if we start our server again and try the original `curl localhost:9200`, it will fail. Try this one instead: `curl -XGET https://localhost:9200 -u 'admin:admin' --insecure`. You can also make this call to return the authenticated user details:
Now if we start our server again and try the original `curl localhost:9200`, it will fail.
Try this one instead: `curl -XGET https://localhost:9200 -u 'admin:admin' --insecure`. It should succeed.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Feel free to create a new issue
--insecure feels like a bad option to advertise. After the script has finished running can we add a step to install the CA cert that was generated from the install script so this option can be removed?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is something that we can discuss and set what needs to be displayed here.


You can also make this call to return the authenticated user details:

```bash
curl -XGET https://localhost:9200/_plugins/_security/authinfo -u 'admin:admin' --insecure
Expand Down