From 5ea10bd7e307c08dbaf83ab6cc5fc97b0bb539af Mon Sep 17 00:00:00 2001 From: Aaron Chong Date: Fri, 28 Apr 2023 02:03:25 +0000 Subject: [PATCH] Documentation (#705) * Change OpenRMF to Open-RMF, make dashboard build command handle prereqs as well Signed-off-by: Aaron Chong * Moved postgres related documentation to api-server Signed-off-by: Aaron Chong * Fresh README Signed-off-by: Aaron Chong * Contribution guide Signed-off-by: Aaron Chong * Use absolute link to orphan media branch gif Signed-off-by: Aaron Chong * Using H3 for sub titles Signed-off-by: Aaron Chong * Link to package, rather than their readmes, encourage folks to open tickets Signed-off-by: Aaron Chong * Added blurb about api-server in readme Signed-off-by: Aaron Chong * Mentioning storybook, adding blurb to dashboard readme Signed-off-by: Aaron Chong * Added code of conduct and general open-rmf contributing guidelines Signed-off-by: Aaron Chong * Visually shift link Signed-off-by: Aaron Chong * Fix name Signed-off-by: Aaron Chong * Adding link to statically hosted API definition Signed-off-by: Aaron Chong * Added API definition mentions in package as well Signed-off-by: Aaron Chong --------- Signed-off-by: Aaron Chong --- CODE_OF_CONDUCT.md | 4 + CONTRIBUTING.md | 18 +++ README.md | 121 ++++++++++-------- packages/api-server/README.md | 35 +++++ packages/dashboard/README.md | 14 +- packages/dashboard/package.json | 2 +- packages/dashboard/src/components/appbar.tsx | 2 +- .../react-components/lib/header-bar.spec.tsx | 4 +- .../lib/header-bar.stories.tsx | 2 +- 9 files changed, 139 insertions(+), 63 deletions(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..98b5d8083 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,4 @@ +# Code of Conduct + +In the interest of fostering an open and welcoming environment, Open-RMF uses the [ROS Code of Conduct](https://osrf.github.io/code_of_conduct/). +See that document for details. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..cfba094da --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,18 @@ +Any contribution that you make to this repository will +be under the Apache 2 License, as dictated by that +[license](http://www.apache.org/licenses/LICENSE-2.0.html): + +~~~ +5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. +~~~ + +Contributors must sign-off each commit by adding a `Signed-off-by: ...` +line to commit messages to certify that they have the right to submit +the code they are contributing to the project according to the +[Developer Certificate of Origin (DCO)](https://developercertificate.org/). diff --git a/README.md b/README.md index 5f029211e..be2dcea1c 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,26 @@ [![Nightly](https://github.com/open-rmf/rmf-web/actions/workflows/nightly.yml/badge.svg)](https://github.com/open-rmf/rmf-web/actions/workflows/nightly.yml) [![Dashboard End-to-End](https://github.com/open-rmf/rmf-web/actions/workflows/dashboard-e2e.yml/badge.svg)](https://github.com/open-rmf/rmf-web/actions/workflows/dashboard-e2e.yml) [![react-components](https://github.com/open-rmf/rmf-web/workflows/react-components/badge.svg)](https://github.com/open-rmf/rmf-web/actions?query=workflow%3Areact-components+branch%3Amain) [![dashboard](https://github.com/open-rmf/rmf-web/workflows/dashboard/badge.svg)](https://github.com/open-rmf/rmf-web/actions?query=workflow%3Adashboard+branch%3Amain) [![api-server](https://github.com/open-rmf/rmf-web/workflows/api-server/badge.svg)](https://github.com/open-rmf/rmf-web/actions?query=workflow%3Aapi-server+branch%3Amain) [![rmf-auth](https://github.com/open-rmf/rmf-web/actions/workflows/rmf-auth.yml/badge.svg)](https://github.com/open-rmf/rmf-web/actions/workflows/rmf-auth.yml) [![ros-translator](https://github.com/open-rmf/rmf-web/actions/workflows/ros-translator.yml/badge.svg)](https://github.com/open-rmf/rmf-web/actions/workflows/ros-translator.yml) [![api-client](https://github.com/open-rmf/rmf-web/actions/workflows/api-client.yml/badge.svg)](https://github.com/open-rmf/rmf-web/actions/workflows/api-client.yml) [![codecov](https://codecov.io/gh/open-rmf/rmf-web/branch/main/graph/badge.svg)](https://codecov.io/gh/open-rmf/rmf-web) -# Building the Dashboard +# RMF Web -## Prerequisites +![](https://github.com/open-rmf/rmf-web/blob/media/dashboard_office_world.gif) -### Ubuntu 22.04 +Open-RMF Web is a collection of packages that provide a web-based interface for users to visualize and control all aspects of Open-RMF deployments. -Install nodejs +- [Getting started](#getting-started) +- [API server](packages/api-server) +- [API client](packages/api-client) +- [Dashboard](packages/dashboard) +- [Configuration](#configuration) +- [Contribution guide](#contribution-guide) +- [Roadmap](https://github.com/open-rmf/rmf-web/wiki/Open-RMF-Web-Dashboard) + +# Getting started + +### Prerequisites + +We currently support [Ubuntu 22.04](https://releases.ubuntu.com/jammy/), [ROS 2 Humble](https://docs.ros.org/en/humble/index.html) and Open-RMF's [22.09](https://github.com/open-rmf/rmf/releases/tag/22.09) release. Other distributions may work as well, but is not guaranteed. + +Install [nodejs](https://nodejs.org/en/download/package-manager/) >= 16, ```bash sudo apt update && sudo apt install curl curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.37.2/install.sh | bash @@ -24,25 +38,21 @@ Install pipenv pip3 install pipenv ``` -### Install rmf - -Refer to the following documentation: - -* [rmf](https://github.com/open-rmf/rmf) +For Debian/Ubuntu systems, you may need to install `python3-venv` first. +```bash +sudo apt install python3-venv +``` -### Others +### Installing Open-RMF -Refer to the following documentations: +Refer to the following documentation for either building from source or installing released binaries: -* [nodejs](https://nodejs.org/en/download/package-manager/) >= 16 -* [rmf_demos](https://github.com/open-rmf/rmf_demos) +* [rmf](https://github.com/open-rmf/rmf) -## Install dependencies +> **Note** +> Simulation demos are not part of the released binaries, and therefore a built workspace with at least the [demos repository](https://github.com/open-rmf/rmf_demos) would be required for trying out the web dashboard with simulation. -For Debian/Ubuntu systems, you may need to install `python3-venv` first. -```bash -sudo apt install python3-venv -``` +### Install dependencies Run ```bash @@ -54,56 +64,65 @@ You may also install dependencies for only a subset of the packages pnpm install -w --filter ... ``` -### PostgreSQL -If you would like to use PostgreSQL, you will also need to install and set it up. The defaults are for PostgreSQL to be listening on 127.0.0.1:5432. +### Launching -#### Docker -We can use Docker to quickly bring up a PostgreSQL instance. +Source Open-RMF and launch the dashboard in development mode, +```bash +# For binary installation +source /opt/ros/humble/setup.bash -Install docker: `https://docs.docker.com/engine/install/ubuntu/` -Start a a database instance: `docker run -it --rm --name rmf-postgres --network=host -e POSTGRES_PASSWORD=postgres -d postgres` +# For source build +source /path/to/workspace/install/setup.bash -To stop the instance: `docker kill rmf-postgres` +cd packages/dashboard +pnpm start +``` +This starts up the API server which sets up endpoints to communicate with an Open-RMF deployment, as well as begin compilation of the dashboard. Once completed, it can be viewed at [localhost:3000](http://localhost:3000). -#### Bare Metal -Alternatively, we can install PostgreSQL 'bare metal'. -``` -apt install postgresql postgresql-contrib -y -# Set a default password -sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'postgres';" +If presented with a login screen, use `user=admin password=admin`. -sudo systemctl restart postgresql -# interactive prompt -sudo -i -u postgres -``` -To manually reset the database: -``` -sudo -u postgres bash -c "dropdb postgres; createdb postgres" -``` +### Optimized build -## Launching +The dashboard can also be built statically for better performance. -Before running the commands, make sure that rmf is sourced. ```bash cd packages/dashboard +pnpm run build + +# Once completed +npm install -g serve +serve -s build +``` + +This only serves the frontend, the API server can be started manually to work with an Open-RMF deployment on another terminal instance, + +```bash +# source Open-RMF before proceeding +cd packages/api-server pnpm start ``` -When presented with a login screen, use `user=admin password=admin`. -This launches a development server with the office world from `rmf_demos`. The server is useful for development but is obviously not useful for actual usage. +# Contribution guide -## Configuration +* For general contribution guidelines, see [CONTRIBUTING](CONTRIBUTING.md). +* Follow [typescript guidelines](https://basarat.gitbook.io/typescript/styleguide). +* When introducing a new feature or component in [`react-components`](packages/react-components), write tests and stories. +* When introducing a new feature in [`dashboard`](packages/dashboard), write tests as well as [e2e](packages/dashboard-e2e) test whenever possible. +* When introducing API changes with [`api-server`](packages/api-server), + * If the new changes are to be used externally (outside of the web packages, with other Open-RMF packages for example), make changes to [`rmf_api_msgs`](https://github.com/open-rmf/rmf_api_msgs), before generating the required models using [this script](packages/api-server/generate-models.sh) with modified commit hashes. + * Don't forget to update the API client with the newly added changes with [these instructions](packages/api-client/README.md/#generating-rest-api-client). +* Check out the latest API definitions [here](https://open-rmf.github.io/rmf-web/docs/api-server), or visit `/docs` relative to your running server's url, e.g. `http://localhost:8000/docs`. +* Develop the frontend without launching any Open-RMF components using [storybook](packages/dashboard/README.md/#storybook). -See the [rmf-dashboard](packages/dashboard/README.md#configuration) docs. +# Configuration -## API Docs +See the [rmf-dashboard](packages/dashboard/README.md#configuration) docs. -Docs for the api-server can be found at `/docs` relative to your server's url, e.g. `http://localhost:8000/docs`. +# Troubleshooting -The docs can also be found online at https://open-rmf.github.io/rmf-web/docs/api-server. +* If a feature is missing or is not working, it could be only available in an Open-RMF source build, and not in the binaries. Try building Open-RMF from source and source that new workspace before launching the API server. `rmf-web` may use in-development features of Open-RMF. -## Troubleshooting -First thing to try is to build rmf from source, in order to speed up development, `rmf-web` may use in-development features of rmf. That means that the binary releases may not have the features required, sometimes the features `rmf-web` uses may be so new that not even the rolling releases has it. +* Creating tasks from the web dashboard when running a simulated Open-RMF deployment will require the task start time suit simulation time, which starts from unix millis 0. Try creating the same task with a start date of before the year of 1970. -Refer to [rmf_demos](https://github.com/open-rmf/rmf_demos) for instructions to build rmf. You should end up with a colcon workspace with all of rmf packages, remember to source the workspace before running any of the commands. +* Check if the issue has already been [reported or fixed](https://github.com/open-rmf/rmf-web/issues). diff --git a/packages/api-server/README.md b/packages/api-server/README.md index 81726f700..405ef6aa3 100644 --- a/packages/api-server/README.md +++ b/packages/api-server/README.md @@ -1,3 +1,7 @@ +# Open-RMF API Server + +This API server sets up the necessary endpoints with an Open-RMF deployment and enables the use of the web dashboard. The server comes with the capability of logging to databases, as well as handling authentication and permissions. + # Setup If not already done so, [install dependencies](../../README.md#Install-dependencies), you can use @@ -6,6 +10,10 @@ pnpm install -w --filter api-server... ``` to install dependencies for only this package. +# API + +Check out the latest API definitions [here](https://open-rmf.github.io/rmf-web/docs/api-server), or visit `/docs` relative to your running server's url, e.g. `http://localhost:8000/docs`. + # Run the server ```bash @@ -62,6 +70,33 @@ postgres://:@/ for more information, see https://tortoise-orm.readthedocs.io/en/latest/databases.html. +### PostgreSQL +If you would like to use PostgreSQL, you will also need to install and set it up. The defaults are for PostgreSQL to be listening on 127.0.0.1:5432. + +#### Docker +We can use Docker to quickly bring up a PostgreSQL instance. + +Install docker: `https://docs.docker.com/engine/install/ubuntu/` +Start a a database instance: `docker run -it --rm --name rmf-postgres --network=host -e POSTGRES_PASSWORD=postgres -d postgres` + +To stop the instance: `docker kill rmf-postgres` + +#### Bare Metal +Alternatively, we can install PostgreSQL 'bare metal'. +``` +apt install postgresql postgresql-contrib -y +# Set a default password +sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'postgres';" + +sudo systemctl restart postgresql +# interactive prompt +sudo -i -u postgres +``` +To manually reset the database: +``` +sudo -u postgres bash -c "dropdb postgres; createdb postgres" +``` + ## Running behind a proxy When running behind a reverse proxy like nginx, you need to set the `public_url` option to the url where rmf-server is served on. The reverse proxy also MUST strip the prefix. diff --git a/packages/dashboard/README.md b/packages/dashboard/README.md index 7f4ededc4..563c99e6a 100644 --- a/packages/dashboard/README.md +++ b/packages/dashboard/README.md @@ -1,17 +1,17 @@ -## rmf-dashboard +# rmf-dashboard -Hello! `rmf-dashboard` is a web application that provides overall visualization and control over the RMF system. +`rmf-dashboard` is a web application that provides overall visualization and control over the RMF system. -## Building +# Setup -Follow the build instructions [here](../../README.md#building-the-dashboard). +Follow the build instructions [here](../../README.md/#launching). ## Configuration ### (Optional) Import external resources. ```bash -npm run setup +pnpm run setup ``` When executing this command, a prompt will be displayed, and it will guide you through the process. @@ -45,12 +45,12 @@ Upon completion of the configuration, a file called .resources.json will be crea In case you want to modify the source of your resources. You can rerun the command: ```bash -npm run setup +pnpm run setup ``` ### Environment Variables -The default launch script with `npm start` launches only the backend servers without any simulation instances from `rmf_demos`. For local development, the launch script `npm run start:sim` launches a headless simulation instance on top of all the backend servers. +The default launch script with `pnpm start` launches only the backend servers without any simulation instances from `rmf_demos`. For local development, the launch script `pnpm run start:sim` launches a headless simulation instance on top of all the backend servers. In production, the dashboard would need to be configured so that it knows where to find the various services. diff --git a/packages/dashboard/package.json b/packages/dashboard/package.json index 85104d5ef..77407eb71 100644 --- a/packages/dashboard/package.json +++ b/packages/dashboard/package.json @@ -12,7 +12,7 @@ "start:rmf": "node scripts/start-rmf.js", "start:rmf-server": "RMF_SERVER_USE_SIM_TIME=true npm --prefix ../api-server start", "start:rmf-server:psql": "RMF_SERVER_USE_SIM_TIME=true npm run --prefix ../api-server start:psql", - "build": "react-scripts build", + "build": "pnpm run --filter {.}^... build && react-scripts build", "test": "react-scripts test", "test:coverage": "pnpm test -- --coverage --watchAll=false", "test:e2e": "cd e2e && npm test", diff --git a/packages/dashboard/src/components/appbar.tsx b/packages/dashboard/src/components/appbar.tsx index 574c665a8..edced6998 100644 --- a/packages/dashboard/src/components/appbar.tsx +++ b/packages/dashboard/src/components/appbar.tsx @@ -323,7 +323,7 @@ export const AppBar = React.memo(({ extraToolbarItems }: AppBarProps): React.Rea New Task - Powered by OpenRMF + Powered by Open-RMF {extraToolbarItems} { - Powered by OpenRMF + Powered by Open-RMF @@ -29,7 +29,7 @@ describe('Header Bar', () => { ); expect(screen.getByText('Building')).toBeTruthy(); expect(screen.getByText('Robots')).toBeTruthy(); - expect(screen.getByText('Powered by OpenRMF')).toBeTruthy(); + expect(screen.getByText('Powered by Open-RMF')).toBeTruthy(); expect(screen.getByLabelText('user-btn')).toBeTruthy(); cleanup(); }); diff --git a/packages/react-components/lib/header-bar.stories.tsx b/packages/react-components/lib/header-bar.stories.tsx index 14eb77df3..5c7aeb683 100644 --- a/packages/react-components/lib/header-bar.stories.tsx +++ b/packages/react-components/lib/header-bar.stories.tsx @@ -99,7 +99,7 @@ export const FullHeaderBar: Story = () => { /> - Powered by OpenRMF + Powered by Open-RMF