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.

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

Add docker dev set up instruction #3444

Merged
Merged
Changes from all commits
Commits
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
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -129,6 +129,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

2 changes: 1 addition & 1 deletion DEVELOPER_GUIDE.md
Original file line number Diff line number Diff line change
@@ -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
```
28 changes: 28 additions & 0 deletions dev-tools/install-docker-dev.sh
Original file line number Diff line number Diff line change
@@ -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 #
57 changes: 57 additions & 0 deletions docs/docker-dev/docker-compose.yml
Original file line number Diff line number Diff line change
@@ -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:

59 changes: 59 additions & 0 deletions docs/docker-dev/docker-dev-setup-manual.md
Original file line number Diff line number Diff line change
@@ -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.

abbyhu2000 marked this conversation as resolved.
Show resolved Hide resolved
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!
5 changes: 5 additions & 0 deletions docs/docker-dev/entrypoint.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
#!/bin/bash
echo $REPO_URL
git remote set-url origin $REPO_URL
git fetch
tail -f /dev/null
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
@@ -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",