Merge pull request #7 from b1zzu/update-docs

docs: update README.md
b1zzu · Feb 8, 2022 · 6adad52 · 6adad52
2 parents c4f1d9d + 568e0c6
commit 6adad52
Showing 1 changed file with 165 additions and 32 deletions.
diff --git a/README.md b/README.md
@@ -2,64 +2,197 @@
 
 A tooling to import and export Report Portal dashboards in YAML
 
-## Build & Install
+## Installation
 
-Prerequisites:
+### Linux
 
-- [go](https://go.dev/)
-- [git](https://git-scm.com/)
+#### Manual installation
 
-Clone the repository on your local machine:
+1. Navigate to the [Releases](https://github.com/b1zzu/reportportal-dashboards-as-code/releases) page and download the `rpdac_x.y.z_linux_arch.tar.gz` archive, where `x.y.z` is the version you want to install and `arch` is the CPU architecture of your PC (for Intel and AMD CPUs use `amd64`)
 
+2. Extract the `rpdac` from the archive:
+   ```
+   tar xfv rpdac_x.y.z_linux_arch.tar.gz
+   ```
+
+3. Install `rpdac` in your `$PATH` (we suggest installing it in `~/.local/bin`)
+   ```
+   mv rpdac ~/.local/bin
+   rpdac --help
+   ```
+
+#### Fedora/CentOS/RHEL/OpenSUSE
+
+1. Navigate to the [Releases](https://github.com/b1zzu/reportportal-dashboards-as-code/releases) page and download the `rpdac_x.y.z_linux_arch.rpm` RPM package, where `x.y.z` is the version you want to install and `arch` is the CPU architecture of your PC (for Intel and AMD CPUs use `amd64`)
+
+2. Install the RPM package:
+   ```
+   sudo rpm -i ./rpdac_x.y.z_linux_arch.rpm
+   rpdac --help
+   ```
+
+#### Ubuntu/Debian/ElementaryOS
+
+1. Navigate to the [Releases](https://github.com/b1zzu/reportportal-dashboards-as-code/releases) page and download the `rpdac_x.y.z_linux_arch.deb` DEB package, where `x.y.z` is the version you want to install and `arch` is the CPU architecture of your PC (for Intel and AMD CPUs use `amd64`)
+
+2. Install the RPM package:
+   ```
+   sudo apt install ./rpdac_x.y.z_linux_arch.deb
+   rpdac --help
+   ```
+
+### MacOS
+
+#### Manual installation
+
+1. Navigate to the [Releases](https://github.com/b1zzu/reportportal-dashboards-as-code/releases) page and download the `rpdac_x.y.z_darwin_arch.tar.gz` archive, where `x.y.z` is the version you want to install and `arch` is the CPU architecture of your Mac (for Intel CPUs use `amd64`, for Apple M1 use `arm64`)
+
+2. Extract the `rpdac` from the archive:
+   ```
+   tar xfv rpdac_x.y.z_darwin_arch.tar.gz
+   ```
+
+3. Install `rpdac` in your `$PATH` (we suggest installing it in `$HOME/bin`)
+   ```
+   mv rpdac $HOME/bin
+   rpdac --help
+   ```
+
+## Getting Started
+
+This is a short step-by-step tutorial on how to use `rpdac`.
+
+**Requirements:**
+
+* `rpdac` is [installed](#Installation) on your PC
+* You have a ReportPortal instance and a Access token
+
+1. Navigate to your ReportPortal instance and in your project manually create a dashboard with as many widgets as you want and name it `My Dashboard`.
+
+2. Open a terminal and export your ReportPortal endpoint, Access token, and Project name as environment variables.
+   ```
+   export RPDAC_ENDPOINT="https://example.com"
+   export RPDAC_TOKEN="a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1"
+   export RPDAC_PROJECT="my_project"
+   ```
+
+3. Run the `export dashboard` command to export the `My Dashboard` locally.
+   ```
+   rpdac export dashboard --name 'My Dashboard' -f my-dashboard.yaml
+   ```
+
+4. Now edit the `description` of the dashboard in the `my-dashboard.yaml` file.
+
+5. Run the `apply` command to update the dashboard in ReportPortal.
+   ```
+   rpdac apply -f my-dashboard.yaml
+   ```
+
+6. Navigate to ReportPortal and verify that the description of `My Dashboard` has updated correctly.
+
+
+
+1. Install `rpdac` on your machine
+
+## Configuration
+
+After installing `rpdac` you need to configure the ReportPortal endpoint and token. 
+
+The **Endpoint** is the URL of your ReportPortal instance (example: `https://example.com`)
+
+The **Access token** can be found in the *Profile* page (example: `a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1`)
+
+The endpoint and token can be configured as Environment Variables, Config File, or as Flags before each Command.
+
+### As Environment Variables
+
+| Name | Description |
+| ---- | ----------- |
+| RPDAC_ENDPOINT | The ReportPortal endpoint URL | 
+| RPDAC_TOKEN    | The Access token to authenticate against ReportPortal |
+
+Example:
 ```
-git clone https://github.com/b1zzu/reportportal-dashboards-as-code.git
+export RPDAC_ENDPOINT="https://example.com"
+export RPDAC_TOKEN="a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1"
 ```
 
-build the `rpdac` tool for your machine:
+### As Config File
+
+The `.rpdac.toml` config file can be created in the current directory with the ReportPortal endpoint and token:
 
+File example:
+```toml
+endpoint = "https://example.com"
+token = "a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1"
 ```
-go build -o rpdac
+
+By default `rpdac` will look for the `.rpdac.toml` config file in the current directory but with the `--config` flag or the `RPDAC_CONFIG` ENV a different path can be specified.
+
+### As Flags before each Command
+
+The `--endpoint` and `--token` flags can also be specified before each command to configure the ReportPortal endpoint and token.
+
+Example:
 ```
+$ rpdac --endpoint "https://example.com" --token "a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1" export dashboard [...]
+```
+
+## Commands
+
+### Export a Dashboard
 
-test the new executable:
+Dashboards can be exported in YAML using the `export dashboard` command. Exporting a dashboard is useful to copy it (if you create it again with a different name using the `create` command), save it as code (to be then re-created in the same instance if it gets deleted or in a new instance), migrate it to a new instance.
 
+Example:
 ```
-./rpdac help
+$ rpdac export dashboard -p my_project --name 'My Dashboard Name' -f my-dashboard.yaml
 ```
 
-you can now use the `rpdac` as it is or move it in a PATH directory in your machine to install it globally.
+### Export a Filter
 
-## Export a Dashboard
+Like for Dashboards, Filters can be exported in YAML using the `export filter` command. 
 
-1. Create `.rpdac.toml` configuration file for in the directory from which you will execute the `rpdac` tool like this:
+Example:
+```
+$ rpdac export filter -p my_project --name 'My Filter Name' -f my-filter.yaml
+```
 
-   ```toml
-   endpoint = "https://your.report-portal.url"
-   token = "your-report-portal-token"
-   ```
+### Import/Create a Dashboard
 
-   > Note: you can also specify a different path for the config file using `-c` flag when executing `rpdac`
+If you already have a Dashboard definition in YAML or you have exported a Dashboard in YAML you can create it in a new ReportPortal instance or in the same if it got deleted using the `create` command.
 
-1. Identify the Dashboard ID, which you can find in the Dashboard URL if you open the Dashboard you want to export in the ReportPortal UI
+Example:
+```
+$ rpdac create -p my_project  -f my-dashboard.yaml
+```
 
-1. Export the Dashboard to a local YAML file:
+> Note: the `create` command automatically detects that the `.yaml` file is a Dashboard
 
-   ```
-   rpdac -p the_dashboard_project -d 1 -f ./mydashboard.yaml
-   ```
+### Import/Create a Filter
 
-   > Note: in this example, the Dashboard ID we are going to export is `1`
+Like for Dashboards, Filters can be created from a YAML definition using the `create` command.
 
-## Import/Create a Dashboard
+Example:
+```
+$ rpdac create -p my_project  -f my-filter.yaml
+```
 
-1. Like for [Export a Dashboard](#export-a-dashboard) you will need to create a `.prdac.toml` config file before proceeding
+> Note: the `create` command automatically detect that the `.yaml` file is a Filter
 
-1. Create a YAML file with the Dashboard definition you want to create
+### Apply all Dashboards and Filters from a folder
 
-   > Note: use the UI to create a Dashboard and Widgets then export it using `rpdac export ...` to learn the format of a YAML Dashboard, you can then duplicate and/or edit the YAML manually to create multiple Dashboard, or use it as it is too import it in a different Report Portal instance or Project.
+Using the `apply` command is possible to create or update a single Dashboard or Filter but also an entire directory containing multiple Dashboards and/or Filters.
 
-1. Create the Dashboard in Report Portal from the YAML definition using the `rpdac create ...` like this:
+For example, the current (`$PWD`) directory contains the `my-dashboard.yaml`, `my-filter-01.yaml` and `my-filter-02.yaml`. `my-dashboard.yaml` already exists in ReportPortal but it needs to be updated, `my-filter-01.yaml` doesn't exist in ReportPortal and `my-filter-02.yaml` already exists, and it doesn't need to be updated. When we apply the current directory, the `my-dashboard.yaml` will be updated, the `my-filter-01.yaml` will be created, and the `my-filter-02.yaml` will be ignored.
 
-   ```
-   rpdac -p my_project -f ./mydashboard.yaml
-   ```
+```
+$ rpdac apply -p my_project -f . -r
+0000/00/00 00:00:00 Dashboard with name 'My Dashboard' updated in project 'my_project'
+0000/00/00 00:00:00 Filter with name 'My Filter 01' created in project 'my_project'
+0000/00/00 00:00:00 Skip apply Filter with name 'My Filter 02' in project 'my_project'
+```
+
+> Note: If you apply a directory with multiple Dashboards and then you delete one of the Dashboards and apply again the dashboard will not be deleted from ReportPortal, same for filters.
+
+> Note: The apply command will only update a dashboard if it match the name, so if you rename a dashboard in the yaml and apply again it will create a new dashboard in ReportPortal instead of renaming it, same for filters.