Documentation (#705)

* Change OpenRMF to Open-RMF, make dashboard build command handle prereqs as well Signed-off-by: Aaron Chong <[email protected]> * Moved postgres related documentation to api-server Signed-off-by: Aaron Chong <[email protected]> * Fresh README Signed-off-by: Aaron Chong <[email protected]> * Contribution guide Signed-off-by: Aaron Chong <[email protected]> * Use absolute link to orphan media branch gif Signed-off-by: Aaron Chong <[email protected]> * Using H3 for sub titles Signed-off-by: Aaron Chong <[email protected]> * Link to package, rather than their readmes, encourage folks to open tickets Signed-off-by: Aaron Chong <[email protected]> * Added blurb about api-server in readme Signed-off-by: Aaron Chong <[email protected]> * Mentioning storybook, adding blurb to dashboard readme Signed-off-by: Aaron Chong <[email protected]> * Added code of conduct and general open-rmf contributing guidelines Signed-off-by: Aaron Chong <[email protected]> * Visually shift link Signed-off-by: Aaron Chong <[email protected]> * Fix name Signed-off-by: Aaron Chong <[email protected]> * Adding link to statically hosted API definition Signed-off-by: Aaron Chong <[email protected]> * Added API definition mentions in package as well Signed-off-by: Aaron Chong <[email protected]> --------- Signed-off-by: Aaron Chong <[email protected]>
open-rmf · Apr 28, 2023 · 5ea10bd · 5ea10bd
1 parent 3b2c221
commit 5ea10bd
Show file tree

Hide file tree

Showing 9 changed files with 139 additions and 63 deletions.
diff --git a/CODE_OF_CONDUCT.md 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
@@ -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
@@ -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 <package>...
 ```
 
-### 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
@@ -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://<user>:<password>@<host>/<database>
 
 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
@@ -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
@@ -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
@@ -323,7 +323,7 @@ export const AppBar = React.memo(({ extraToolbarItems }: AppBarProps): React.Rea
             New Task
           </Button>
           <Divider orientation="vertical" sx={{ marginLeft: 1, marginRight: 2 }} />
-          <Typography variant="caption">Powered by OpenRMF</Typography>
+          <Typography variant="caption">Powered by Open-RMF</Typography>
           {extraToolbarItems}
           <IconButton
             id="show-settings-btn"

diff --git a/packages/react-components/lib/header-bar.spec.tsx b/packages/react-components/lib/header-bar.spec.tsx
@@ -20,7 +20,7 @@ describe('Header Bar', () => {
           <Tab key={'robots-tab'} label={'Robots'} value={'robots'} aria-label={`building-tab`} />
         </NavigationBar>
         <Toolbar variant="dense">
-          <Typography variant="caption">Powered by OpenRMF</Typography>
+          <Typography variant="caption">Powered by Open-RMF</Typography>
           <IconButton id="user-btn" aria-label={'user-btn'} color="inherit">
             <AccountCircleIcon />
           </IconButton>
@@ -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
@@ -99,7 +99,7 @@ export const FullHeaderBar: Story = () => {
             />
           </NavigationBar>
           <Toolbar variant="dense" className={classes.toolbar}>
-            <Typography variant="caption">Powered by OpenRMF</Typography>
+            <Typography variant="caption">Powered by Open-RMF</Typography>
             <IconButton id="user-btn" aria-label={'user-btn'} color="inherit">
               <AccountCircleIcon />
             </IconButton>