forked from opensearch-project/security-dashboards-plugin
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Updates Dev guide (opensearch-project#897)
Signed-off-by: Darshit Chanpura <[email protected]>
- Loading branch information
1 parent
bc61403
commit b6fe0c0
Showing
1 changed file
with
53 additions
and
7 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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) | | ||
| | [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: | ||
|
|
||
| ```yaml | ||
| ######## Start OpenSearch Security Demo Configuration ######## | ||
|
|
@@ -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" | ||
|
|
@@ -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 [email protected]:opensearch-project/security-dashboards-plugin.git | ||
| git clone [email protected]:<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 | ||
|
|
||