diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index 899de4c0634a..46df57956e97 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -132,7 +132,11 @@ $ yarn osd clean ### Run OpenSearch -OpenSearch Dashboards requires a running version of OpenSearch to connect to. In a separate terminal you can run the latest snapshot built using: +OpenSearch Dashboards requires a running version of OpenSearch to connect to. You can choose to run OpenSearch locally yourself or point to an existing cluster. + +#### Run a local OpenSearch cluster + +In a separate terminal you can run the latest snapshot built using: _(Linux, Windows, Darwin (MacOS) only - for others, you'll need to [set up using Docker](https://github.com/opensearch-project/OpenSearch-Dashboards/blob/main/docs/docker-dev/docker-dev-setup-manual.md) or [run OpenSearch from a tarball](#alternative---run-opensearch-from-tarball) instead)_ @@ -140,6 +144,47 @@ _(Linux, Windows, Darwin (MacOS) only - for others, you'll need to [set up using $ yarn opensearch snapshot ``` +#### Alternative - Connect to an external OpenSearch cluster + +Instead of running OpenSearch locally, you can point OpenSearch Dashboards to an existing OpenSearch cluster: + +1. Clone the security dashboards plugin inside your OpenSearch Dashboards plugins folder and bootstrap: +```bash +$ cd plugins +$ git clone https://github.com/opensearch-project/security-dashboards-plugin.git +$ cd .. +$ yarn osd bootstrap --single-version=loose +``` +2. Create a configuration directory outside your repository to avoid accidentally committing credentials. For example: +```bash +$ mkdir -p /configs/me +$ mkdir -p /configs/prod +``` +3. Create `opensearch_dashboards.yml` file(s) in your config directories. Here's an example config: +```yaml +opensearch.hosts: ["https://your-opensearch-host"] +opensearch.username: 'admin' +opensearch.password: 'your-password' +opensearch.ignoreVersionMismatch: true +opensearch.ssl.verificationMode: none +opensearch.requestHeadersWhitelist: [authorization] +opensearch_security.multitenancy.enabled: false +opensearch_security.readonly_mode.roles: [kibana_read_only] +opensearch_security.cookie.secure: false +``` +4. Set the `OSD_PATH_CONF` environment variable to point to your config directory: +```bash +$ export OSD_PATH_CONF=/absolute/path/to/configs/me +``` + +This approach allows you to: +- Develop against a production-like environment +- Avoid running resource-intensive local clusters +- Maintain different configurations for different environments +- Keep sensitive credentials out of your repository + +Note: Make sure your OpenSearch cluster is accessible and credentials are valid before starting OpenSearch Dashboards. + ### Run OpenSearch Dashboards _**Warning:** Starting the OpenSearch Dashboards instance before the OpenSearch server is fully initialized can cause Dashboards to misbehave. Ensure that the OpenSearch server instance is up and running first. You can validate by running `curl localhost:9200` in another console tab or window (see [OpenSearch developer guide](https://github.com/opensearch-project/OpenSearch/blob/main/DEVELOPER_GUIDE.md#run-opensearch))._ diff --git a/changelogs/fragments/9080.yml b/changelogs/fragments/9080.yml new file mode 100644 index 000000000000..5d05588145c0 --- /dev/null +++ b/changelogs/fragments/9080.yml @@ -0,0 +1,2 @@ +doc: +- Update dev guide to connect to external cluster ([#9080](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/9080)) \ No newline at end of file