Skip to content

Updates Dev guide #897

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

Merged
cliu123 merged 5 commits into from
Jun 29, 2022
Merged

Updates Dev guide #897

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
075924c
Updates Dev guide
DarshitChanpura Feb 1, 2022
1609ea0
Updates dev guide to reflect changes from PR comments
DarshitChanpura Feb 2, 2022
249bfc2
Addresses PR comments
DarshitChanpura Feb 3, 2022
bc16209
Updates the dev-guide to add version information
DarshitChanpura Feb 4, 2022
ed5c07d
Merge branch 'main' into dev-guide-update
peternied Jun 27, 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
60 changes: 53 additions & 7 deletions DEVELOPER_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,36 @@ 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 Dashboards](**https://github.com/opensearch-project/OpenSearch-Dashboards) and needs an [OpenSearch server](https://github.com/opensearch-project/OpenSearch) running with the [Security Plugin](https://github.com/opensearch-project/security) installed. At the time of this writing there is a strict version check between these components, so we recommend running all of them from their respective branches with matching versions (this will also ensure they work well together before we cut a new release.)

As a prerequisite, please follow [the developer guide of the Security Plugin](https://github.com/opensearch-project/security/blob/main/DEVELOPER_GUIDE.md). This will leave you with a running OpenSearch server with security enabled. For the sake of this guide, let's assume the latest versions at the time of writing (`1.3.0-SNAPSHOT` for OpenSearch and OpenSearch Dashboards, and `1.3.0.0-SNAPSHOT` for both backend and frontend (this repo) security plugins.) Update the config file (`config/opensearch.yml`) to look like this one:
This project is a plugin of [OpenSearch-Dashboards](**https://github.com/opensearch-project/OpenSearch-Dashboards). It requires an [OpenSearch](https://github.com/opensearch-project/OpenSearch) server running with the [Security](https://github.com/opensearch-project/security) plugin installed. At the time of this writing there is a strict version check between these components, so we recommend running all of them from their respective branches with matching versions (this will also ensure they work well together before we cut a new release.)

As a prerequisite, please follow [the developer guide of the Security Plugin](https://github.com/opensearch-project/security/blob/main/DEVELOPER_GUIDE.md). This will get a OpenSearch server running with security plugin enabled.


> NOTE: If you are following this guide by the dot, please make sure that source code that you compile for OpenSearch project using `./gradlew localDistro` is done from [1.x branch](https://github.com/opensearch-project/OpenSearch/tree/1.x).


At present there are following branches available to choose from for the setup:

### **Back-end**

| OpenSearch<br>branch | Security Plugin<br>branch | OpenSearch<br>version |
|-------- |--- |--- |
| [1.x](https://github.com/opensearch-project/OpenSearch/tree/1.x) | [main](https://github.com/opensearch-project/security/) | [v1.3.0](https://github.com/opensearch-project/OpenSearch/blob/6eda740be744846f7aa0b2674820b5ed9b6be17e/buildSrc/version.properties#L1) |
Copy link
Member

@peternied peternied Jun 27, 2022

Choose a reason for hiding this comment

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

While I think it would be better to use more recent builds, IMO any update to this guide that make it more usable are for the better, and we can update it afterward.

| [main](https://github.com/opensearch-project/OpenSearch) | (under development) | [v2.0.0](https://github.com/opensearch-project/OpenSearch/blob/1e5d98329eaa76d1aea19306242e6fa74b840b75/buildSrc/version.properties#L1) |

<br>

### **Front-end**
| OpenSearch Dashboards<br>branch | Security Dashboards Plugin<br>branch | OpenSearch Dashboards<br>version |
| --- | --- | --- |
| [1.x](https://github.com/opensearch-project/OpenSearch-Dashboards/tree/1.x) | [main](https://github.com/opensearch-project/security-dashboards-plugin/) | [v1.3.0](https://github.com/opensearch-project/OpenSearch-Dashboards/blob/b82f214babf7ef8db4a9705b7b51a912f779184c/package.json#L14) |
| [main](https://github.com/opensearch-project/OpenSearch-Dashboards) | (under development) | [v2.0.0](https://github.com/opensearch-project/OpenSearch-Dashboards/blob/0c3f901c569838b2708a079d058c7d09970b944c/package.json#L14) |

\
For the sake of this guide, let's assume that the latest versions (`1.3.0-SNAPSHOT` for OpenSearch and OpenSearch Dashboards, and `1.3.0.0-SNAPSHOT` for the backend and the frontend of this Security plugin).

Next, ensure that the config file (`config/opensearch.yml`) in the OpenSearch home directory where you copied the source code using the [dev-guide](https://github.com/opensearch-project/security/blob/main/DEVELOPER_GUIDE.md#:~:text=export%20OPENSEARCH_HOME%3D~/Test/opensearch%2D1.3.0%2DSNAPSHOT) (basically `cd $OPENSEARCH_HOME`) contains this:
Copy link
Member Author

@DarshitChanpura DarshitChanpura Feb 4, 2022

Choose a reason for hiding this comment

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

@hsiang9431-amzn @davidlago ... can you please review this again?


```yaml
######## Start OpenSearch Security Demo Configuration ########
Expand Down Expand Up @@ -39,7 +66,15 @@ node.max_local_storage_nodes: 3
######## End OpenSearch Security Demo Configuration ########
```

Next, we need to check out OpenSearch Dashboards from the branch matching our version, in this example that would be the [1.x branch](https://github.com/opensearch-project/OpenSearch-Dashboards/tree/1.x). Follow the [developer guide](https://github.com/opensearch-project/OpenSearch-Dashboards/blob/1.x/DEVELOPER_GUIDE.md) and replace the version of `opensearch-dashboards.yml` there with this:

**Please Note** : This project runs on node `10.24.1` at the time of writing this guide (refer to the `.nvmrc` or `.node-version` file in the base directory for correct version) and so when installing node please ensure that you install this version. You can do so by running
```script
nvm use --install
```


Next, checkout the [1.x branch](https://github.com/opensearch-project/OpenSearch-Dashboards/tree/1.x) from OpenSearch-Dashboards repo. Follow the [developer guide](https://github.com/opensearch-project/OpenSearch-Dashboards/blob/1.x/DEVELOPER_GUIDE.md) and replace the version of `opensearch-dashboards.yml` there with this:


```yaml
server.host: "0"
Expand All @@ -56,20 +91,31 @@ opensearch_security.readonly_mode.roles: ["kibana_read_only"]
opensearch_security.cookie.secure: false
```

Note that at this point running `yarn start` will fail, as we still don't have the security plugin installed in Dashboards. We are ready to install it now.
\
Note that at this point `yarn start` will fail, as we still don't have the security plugin installed in the Dashboards. We are ready to install it now.


## Building

First create a fork of this repo and clone it locally under the `plugins` directory of the previously cloned OpenSearch Dashboards project, and build the plugin:
Change to the `plugins` directory of the locally cloned Opensearch Dashboards directory.
```
cd <your-path-to>/OpenSearch-Dashboards
cd plugins
```

Create a fork of this repo and clone it locally under the `plugins` directory, and build the plugin:

```
cd plugins
git clone git@github.com:opensearch-project/security-dashboards-plugin.git
git clone git@github.com:<your-git-username>/security-dashboards-plugin.git
cd security-dashboards-plugin
yarn build
```

We should be able to run Dashboards now changing back to its base directory and running `yarn start`. Navigating to the URL given as console output (something like `http://localhost:5601/omf`) you should now be able to log in with user `admin` and password `admin`.
Next, go to the base directory and run `yarn osd bootstrap` to install any additional packages introduced by the security plugin. (If you do not run this, `yarn start` might fail with an error like `Cannot find module xxxxx`)


Now, from the base directory and run `yarn start`. This should start dashboard UI successfully. `Cmd+click` the url in the console output (It should look something like `http://0:5601/omf`). Once the page loads, you should be able to log in with user `admin` and password `admin`.

## Submitting Changes

Expand Down