diff --git a/CHANGELOG.md b/CHANGELOG.md index 9879054c5ca8..041fb3b05c13 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -130,6 +130,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) - [Doc] Improve DEVELOPER_GUIDE to make first time setup quicker and easier ([#3421](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/3421)) - Correct copyright date range of NOTICE file and notice generator ([#3308](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/3308)) - Simplify the in-code instructions for upgrading `re2` ([#3328](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/3328)) +- [Doc] Add docker dev set up instruction ([#3444](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/3444)) ### 🛠 Maintenance diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index e06d67ce98e4..ae4344022bda 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -110,7 +110,7 @@ $ yarn osd clean OpenSearch Dashboards requires a running version of OpenSearch to connect to. In a separate terminal you can run the latest snapshot built using: -_(Linux, Windows, Darwin (MacOS) only - for others, you'll need to [run OpenSearch from a tarball](#alternative---run-opensearch-from-tarball) instead)_ +_(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)_ ```bash $ yarn opensearch snapshot ``` diff --git a/dev-tools/install-docker-dev.sh b/dev-tools/install-docker-dev.sh new file mode 100644 index 000000000000..0d40d12afed6 --- /dev/null +++ b/dev-tools/install-docker-dev.sh @@ -0,0 +1,28 @@ +#!/usr/bin/env bash + +{ # this ensures the entire script is downloaded # + +osd_docker_dev_install_dir(){ + printf "opensearch-dashboards-docker-dev" +} + +osd_download(){ + curl --fail --compressed -q "$@" +} + +osd_do_copy_dev_docker_files(){ + local INSTALL_DIR + INSTALL_DIR="$(osd_docker_dev_install_dir)" + local ENTRYPOINT_SRC + ENTRYPOINT_SRC="https://raw.githubusercontent.com/opensearch-project/OpenSearch-Dashboards/main/docs/docker-dev/entrypoint.sh" + local DOCKER_COMPOSE_SRC + DOCKER_COMPOSE_SRC="https://raw.githubusercontent.com/opensearch-project/OpenSearch-Dashboards/main/docs/docker-dev/docker-compose.yml" + + mkdir -p "$INSTALL_DIR" + osd_download -s "$ENTRYPOINT_SRC" -o "./$INSTALL_DIR/entrypoint.sh" + osd_download -s "$DOCKER_COMPOSE_SRC" -o "./$INSTALL_DIR/docker-compose.yml" +} + +osd_do_copy_dev_docker_files + +} # this ensures the entire script is downloaded # diff --git a/docs/docker-dev/docker-compose.yml b/docs/docker-dev/docker-compose.yml new file mode 100644 index 000000000000..f2f0ffb64cf0 --- /dev/null +++ b/docs/docker-dev/docker-compose.yml @@ -0,0 +1,57 @@ +version: '3' +services: + opensearch-node: + image: opensearchproject/opensearch:latest + container_name: opensearch-node + environment: + - cluster.name=opensearch-cluster # Name the cluster + - node.name=opensearch-node # Name the node that will run in this container + - discovery.seed_hosts=opensearch-node # Nodes to look for when discovering the cluster + - cluster.initial_cluster_manager_nodes=opensearch-node # 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 + - "DISABLE_INSTALL_DEMO_CONFIG=true" # Prevents execution of bundled demo script which installs demo certificates and security configurations to OpenSearch + - "DISABLE_SECURITY_PLUGIN=true" # Disables security plugin + 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-data:/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 + dev-env: + image: abbyhu/opensearch-dashboards-dev:latest + container_name: dev-env + ports: + - 5601:5601 + - 5603:5603 + stdin_open: true + tty: true + expose: + - "5601" + - "5603" + environment: + - 'OPENSEARCH_HOSTS=["http://opensearch-node:9200"]' + - 'SERVER_HOST="0.0.0.0"' + - 'REPO_URL=${REPO_URL}' + volumes: + - osd-dev:/home/osd-dev + - ./entrypoint.sh:/entrypoint.sh + networks: + - opensearch-net + entrypoint: + - /bin/bash + - /entrypoint.sh +volumes: + opensearch-data: + osd-dev: +networks: + opensearch-net: + \ No newline at end of file diff --git a/docs/docker-dev/docker-dev-setup-manual.md b/docs/docker-dev/docker-dev-setup-manual.md new file mode 100644 index 000000000000..53b80e9ff633 --- /dev/null +++ b/docs/docker-dev/docker-dev-setup-manual.md @@ -0,0 +1,59 @@ +# Docker Development Environment Setup +The following instructions demonstrate how to set up a development environment for OpenSearch Dashboards using Docker. It utilizes tools such as `Docker` and `VS Code`, and users should be familiar with the basic usages of them. Users will be able to develop and run the application inside VS Code without additional configurations. + +1. Install [Docker](https://docs.docker.com/get-docker/) if not already installed. + * Make sure that Docker daemon is running. (For windows and macos,you need to have [Docker Desktop](https://docs.docker.com/desktop/), or its alternatives, such as [Finch](https://github.com/runfinch/finch)) + +2. In the terminal, run the command below. + * This should create a folder named `opensearch-dashboards-docker-dev` and it should contain two files: `docker-compose.yml` and `entrypoint.sh`. + * Here is the link to the installer script: `https://raw.githubusercontent.com/opensearch-project/OpenSearch-Dashboards/main/dev-tools/install-docker-dev.sh` if needed. + +```bash +curl -o- https://raw.githubusercontent.com/opensearch-project/OpenSearch-Dashboards/main/dev-tools/install-docker-dev.sh | bash +``` + +3. Open VS Code or [install it](https://code.visualstudio.com/download), if it's not already installed. + * Make sure VS Code has the extensions `Dev Containers` and `Docker` installed. If not, go to `Extensions` tab, search and install them. + +4. Under the Discover tab, click `Open Folder`, and open the `opensearch-dashboards-docker-dev` folder that we just created. + +5. Open the `opensearch-dashboards-docker-dev` folder in VS Code integrated terminal, set environment variable for the fork repository URL by running the command below. + * If fork repo has not been created: Go to [OpenSearch Dashboards github page](https://github.com/opensearch-project/OpenSearch-Dashboards) and under fork, select create a new fork, and then copy the https link of the fork url and use it in the above command. The command needs to be re-run every time it re-start the docker compose file in a new terminal. +```bash +export REPO_URL=[insert your fork repo url here] +``` + +6. Run the `docker-compose.yml` file in the background by typing: +```bash +docker compose up -d --build +``` + +7. Under the `Docker` tab in VS Code, verify that there are two containers running: `opensearchproject/opensearch:latest` and `abbyhu/opensearch-dashboards-dev:latest`. + * This can also be verified by using the command line: + ```bash + docker ps + ``` + +8. Right-click `abbyhu/opensearch-dashboards-dev:latest`, and select `Attach Visual Studio Code`. + * This will ssh into the container and you will be able to view and edit the files using VS Code as the code editor. + * If you do not wish to use VS Code as the code editor, the alternative way of ssh into the container is by using the command below: + ```bash + docker exec -it dev-env /bin/bash + ``` + +9. For the new VS Code window, if it is not showing the repository code, then select `Open Folder`. Then open `/workspace-docker/OpenSearch-Dashboards`. + +10. In the terminal, start the OpenSearch Dashboards application by typing: +```bash +yarn start:docker +``` + +11. Now that OpenSearch Dashboards is running, you should be able to see a log line similar to `[info][server][OpenSearchDashboards][http] http server running at http://0.0.0.0:5603/dog`. + * The last three letters `dog` are randomly generated every time we start dashboards. + +12. Wait for the optimizer to run, which takes about 100s - 200s. Once the optimizer is finished running, it will show a line such as `[success][@osd/optimizer] 48 bundles compiled successfully after 204.9 sec, watching for changes`. + +13. Then paste the link into a chrome browser and view dashboard running in browser, but change ‘0.0.0.0’ to ‘localhost’. So here the link should be `http://localhost:5603/dog`. + * Files are constantly watched, so when you make code changes, OpenSearch Dashboards will rebuild and restart automatically. Refresh the link in the browser and the new changes should be applied. + +14. `Git` is already configured in the `entrypoint.sh` file, and the remote is already tracking the fork repository. You can start contributing by creating your branch off the main, and commit your first PR! diff --git a/docs/docker-dev/entrypoint.sh b/docs/docker-dev/entrypoint.sh new file mode 100644 index 000000000000..ed5c4e720d69 --- /dev/null +++ b/docs/docker-dev/entrypoint.sh @@ -0,0 +1,5 @@ +#!/bin/bash +echo $REPO_URL +git remote set-url origin $REPO_URL +git fetch +tail -f /dev/null diff --git a/package.json b/package.json index ed11f17df74a..e791a29ca5d7 100644 --- a/package.json +++ b/package.json @@ -61,6 +61,7 @@ "build-platform": "node scripts/build", "build": "node scripts/build --all-platforms", "start": "node scripts/opensearch_dashboards --dev", + "start:docker": "node scripts/opensearch_dashboards --dev --opensearch.hosts=$OPENSEARCH_HOSTS --opensearch.ignoreVersionMismatch=true --server.host=$SERVER_HOST", "debug": "node --nolazy --inspect scripts/opensearch_dashboards --dev", "debug-break": "node --nolazy --inspect-brk scripts/opensearch_dashboards --dev", "lint": "yarn run lint:es && yarn run lint:style",