Merge pull request #19 from cloudradar-monitoring/docs

Docs
realvnc-labs · Aug 3, 2022 · 911ec4f · 911ec4f
2 parents ed576cb + 53a58f6
commit 911ec4f
Show file tree

Hide file tree

Showing 233 changed files with 3,538 additions and 241 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,43 @@
+name: Build and deploy docs
+on: [ push ]
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+jobs:
+  docs:
+    name: Build and deploy docs
+    runs-on: ubuntu-20.04
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Markdown Lint
+        run: |
+          cd docs
+          npx markdownlint-cli  content/
+
+      - name: Build with Hugo
+        run: |
+          pwd
+          curl -sL https://github.com/gohugoio/hugo/releases/download/v0.101.0/hugo_0.101.0_Linux-64bit.tar.gz|tar xzf - hugo
+          mv hugo ~/
+          ~/hugo --version||true
+          cd docs
+          test -e public||mkdir public
+          ~/hugo --minify
+          find public
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v1
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: './docs/public'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@main
diff --git a/.gitignore b/.gitignore
@@ -2,3 +2,5 @@
 /.vscode
 /vendor
 /bin
+docs/public
+docs/.hugo_build.lock
diff --git a/README.md b/README.md
@@ -1,258 +1,34 @@
-# Rport CLI (v1)
-
-Rport CLI is a tool to help you managing [rport API](https://github.com/cloudradar-monitoring/rport) directly from your terminal.
-
-## Installation
-
-### As a compiled binary
-
-Jump to [our release page](https://github.com/cloudradar-monitoring/rportcli/releases/tag/v0.0.1pre1) and download a binary for your host OS. Don't forget to download a corresponding md5 file as well.
-
-    # On MacOS
-    wget https://github.com/cloudradar-monitoring/rportcli/releases/download/v0.0.1pre1/rportcli-v0.0.1pre1-darwin-amd64.tar.gz
-
-    # On linux
-    wget https://github.com/cloudradar-monitoring/rportcli/releases/download/v0.0.1pre1/rportcli-v0.0.1pre1-linux-386.tar.gz
-
-    # On Windows
-    Just download https://github.com/cloudradar-monitoring/rportcli/releases/download/v0.0.1pre1/rportcli-v0.0.1pre1-windows-amd64.zip
-    Also download https://github.com/cloudradar-monitoring/rportcli/releases/download/v0.0.1pre1/rportcli-v0.0.1pre1-windows-amd64.zip.md5
-
-Verify the checksum:
-
-    #On MacOS
-    curl -Ls https://github.com/cloudradar-monitoring/rportcli/releases/download/v0.0.1pre1/rportcli-v0.0.1pre1-darwin-amd64.tar.gz.md5 | sed 's:$: rportcli-v0.0.1pre1-darwin-amd64.tar.gz:' | md5sum -c
-
-    #On linux
-    curl -Ls https://github.com/cloudradar-monitoring/rportcli/releases/download/v0.0.1pre1/rportcli-v0.0.1pre1-linux-386.tar.gz.md5 | sed 's:$: rportcli-v0.0.1pre1-linux-386.tar.gz:' | md5sum -c
-
-    #On Windows assuming you're in the directory with the donwloaded file
-    CertUtil -hashfile rportcli-v0.0.1pre1-windows-amd64.zip MD5
-
-    #The output will be :
-    MD5 hash of tacoscript-0.0.4pre-windows-amd64.zip:
-    7103fcda170a54fa39cf92fe816833d1
-    CertUtil: -hashfile command completed successfully.
-
-    #Compare the command output to the contents of file rportcli-v0.0.1pre1-windows-amd64.zip.md5 they should match
-
-_Note: if the checksums didn't match please skip the installation!_
-
-Unpack and install the rportcli binary on your host machine
-
-    #On linux/MacOS
-    tar -xzvf rportcli-v0.0.1pre1-darwin-amd64.tar.gz
-    mv rportcli /usr/local/bin/rportcli
-    chmod +x /usr/local/bin/rportcli
-
-For Windows
-
-- Extract file contents
-
-- Create a `RportCLI` folder in `C:\Program Files`
-
-- Copy the rportcli.exe binary to `C:\Program Files\RportCLI`
-
-- Double click on the rportcli.exe and allow it's execution
-
-## Install as a go binary:
-
-    go get github.com/cloudradar-monitoring/rportcli
-
-## Server Authentication
-
-The rportcli requires authentication with the rportd server. The most straightforward
-method is to use environment variables with an API token.
-
-Alternatively a username and password can be specified again via environment variables.
-However, if 2fa is enabled then this approach will not work, and it will be necessary to
-use the config.json file and a authentication token (see below).
-
-Finally, a username and password can be provided to the init command which then authorises
-with the rportd server and saves a authentication token locally (to a config file). The authentication token
-is valid for 30 days and will automatically be used by rportcli without further authentication.
-The init command will need to be run again after the 30 days expires to reauthorise the user
-and download a new authentication token.
-
-_Note_
-
-_RPORT_API_USER, RPORT_API_PASSWORD and RPORT_API_URL replace the previous RPORT_USER,
-RPORT_PASSWORD and RPORT_SERVER_URL environment variables. Please update any scripts
-accordingly. Support for RPORT_USER, RPORT_PASSWORD and RPORT_SERVER_URL will be removed
-in a future release._
-
-### Using RPORT_API_TOKEN
-
-The easiest and most flexible way to authenticate with the rportd server is to use an API
-token. Using RPORT_API_TOKEN will bypass 2 factor authentication, allowing the rport cli to
-be used in automated scenarios.
 
-Also, if using RPORT_API_TOKEN then the config file will be ignored completed, so the
-RPORT_API_URL must be used.
-
-For example
-
-    export RPORT_API_URL=http://localhost:3000
-    export RPORT_API_USER=admin
-    export RPORT_API_TOKEN=xxxxxxxx
-    #now you can run any rportcli command without config or 2fa
-    rportcli client list
-
-_Note that it is not possible to use the init commmand (see below) when using an api token._
-
-### Using RPORT_API_PASSWORD
-
-For example
-
-    export RPORT_API_URL=http://localhost:3000
-    export RPORT_API_USER=admin
-    export RPORT_API_PASSWORD=foobaz
-    #now you can run any rportcli command without config
-    rportcli client list
-
-The cli will complain if both the api token and the password are set. Please use one or the other.
-
-### Using config.json and a cached Authentication Token
-
-This method for authentication is useful when not using an API token but 2fa is enabled. The `init` command
-will download an authentication token that will be cached in the config.json until expires. With a valid token
-the user does not need to reauthenticate each use of the cli.
-
-Rportcli looks for the config file at \$HOME/.config/rportcli/config.json (for Linux and MacOS) or C:\Users\<CurrentUserName>\.config\rportcli\config.json (for Windows).
-If current user has no home folder, RportCli will look for a config file next to the current binary location.
-
-You can override config path by providing env variable CONFIG_PATH, e.g.
-
-    CONFIG_PATH=/tmp/config.json rportcli init
-
-You can generate config by running:
-
-    rportcli init
-
-Rportcli will interactively ask for config options and validate the result:
-You'll get request for following parameters:
-
-**server address**
-
-address of rport server, e.g. `http://localhost:3000`
-
-**login**
+[![License](https://img.shields.io/github/license/cloudradar-monitoring/rportcli?style=for-the-badge)](https://github.com/cloudradar-monitoring/rportcli/blob/main/LICENSE)
+# Rport CLI (v1)
 
-basic auth login to access rport server, e.g. `admin`
+Rport CLI is a tool to help you managing your remote machines connected 
+to the [rport API](https://github.com/cloudradar-monitoring/rport) directly from your terminal.
 
-**password**
+The rport command line interface `rportcli` is a great addition to the rport server. Executing some tasks on the
+command line can be much faster and more efficient than doing it on the web user interface.
 
-basic auth password to access rport server, e.g. `foobaz`
+Rportcli does not cover all functions of the user interface. On the other hand, you can do things on the command line,
+you cannot do on the user interface.
 
-You can skip the interactive wizard by providing parameters as cli options , e.g.
+Integrates well with:
 
-     rportcli init -s http://localhost:3000 -l admin -p foobaz
+![Powershell](https://img.shields.io/badge/Powershell-2CA5E0?style=for-the-badge&logo=powershell&logoColor=white) 
+![GnuBash](https://img.shields.io/badge/GNU%20Bash-4EAA25?style=for-the-badge&logo=GNU%20Bash&logoColor=white)
+![Git](https://img.shields.io/badge/GIT-E44C30?style=for-the-badge&logo=git&logoColor=white)
 
-You can also use a hybrid variant, where e.g. user and server url are provided as config options and password as an environment variable.
+## Documentation
 
-     rportcli init -s http://localhost:3000 -l admin
-     export RPORT_API_PASSWORD=foobaz
-     rportcli client list
+[![documentation](https://img.shields.io/badge/Documentation-Read_Now-green?style=for-the-badge&logo=Gitbook)](https://cli.rport.io)
 
-After the authentication token expires, it will be necessary to run `init` again to reauthorise and update the token.
+📖 Read the documentation on [https://cli.rport.io/](https://cli.rport.io/)
 
 ## Using the Cli
 
-Trigger this command to see all available commands and their options:
+Execute this command to see all available commands and their options:
 
     rportcli --help
 
 You can also display help for a certain command:
 
     rportcli init --help
-
-## Additional configuration with environment variables
-
-<table>
-    <tr>
-    <th>Variable</th>
-    <th>Description</th>
-    <th>Default Value</th>
-    <th>Example</th>
-    </tr>
-    <tr>
-    <td>CONFIG_PATH</td>
-    <td>Changes default config location to the provided value</td>
-    <td>${HOME}/.config/rportcli/config.json</td>
-    <td>CONFIG_PATH=/tmp/config.json rportcli init</td>
-    </tr>
-    <tr>
-    <td>CONN_TIMEOUT_SEC</td>
-    <td>Connection timeout to call rport server (seconds)</td>
-    <td>10 seconds</td>
-    <td>CONN_TIMEOUT_SEC=20 rportcli client list</td>
-    </tr>
-    <tr>
-    <td>SESSION_VALIDITY_SECONDS</td>
-    <td>Initial lifetime of an interactive command session in seconds. Max value is 90 days</td>
-    <td>10(minutes) * 60</td>
-    <td>SESSION_VALIDITY_SECONDS=1800 rportcli command -i</td>
-    </tr>
-    <tr>
-    <td>RPORT_API_USER</td>
-    <td>Basic auth login to access rport server</td>
-    <td></td>
-    <td>RPORT_API_USER=admin rportcli client list</td>
-    </tr>
-    <tr>
-    <td>RPORT_API_PASSWORD</td>
-    <td>Basic auth password to access rport server</td>
-    <td></td>
-    <td>RPORT_API_PASSWORD=foobaz rportcli client list</td>
-    </tr>
-    <tr>
-    <td>RPORT_API_URL</td>
-    <td>Address of rport server</td>
-    <td></td>
-    <td>RPORT_API_URL=http://localhost:3000 rportcli client list</td>
-    </tr>
-    <tr>
-    <td>RPORT_API_TOKEN</td>
-    <td>Api token for accessing the rport server. Must be specified with RPORT_API_USER and RPORT_API_URL.</td>
-    <td></td>
-    <td>RPORT_API_TOKEN=xxxxxxxx rportcli client list</td>
-    </tr>
-</table>
-
-## Using YAML input for Options (command and script only)
-
-For `command execute` and `script execute`, the CLI supports reading of the required options / parameters
-from yaml files via the `--read-yaml` (short form `-y`) command line option. This will allow users to set the CLI options
-for execution in files, rather than always being required on the command line itself.
-
-Any related options specified on the command line will have precedence over options set in YAML files.
-
-Multiple yaml files are supported but only to set the options for a single execution. The last yaml file
-on the command line with have precedence and any duplication options will overwrite options set in previously included
-yaml files.
-
-For example
-
-```yaml
-# check-clients.yaml
-cids:
-  - cdeb33642b4b43caa13b73ce0045d388
-  - 7ca5718bd76f1bca7a5ee72660d3120c
-  - 42560923b8414a519c7a42047f251fb3
-conc: true
-full-command-response: true
-command: |
-  ls
-```
-
-Can be executed using
-
-```bash
-$ rport_cli -y "check-clients.yml
-```
-
-And the targeted clients can be overridden using:
-
-```bash
-$ `rport_cli -y "check-clients.yml --name "test-server"`
-```
diff --git a/cmd/help.go b/cmd/help.go
@@ -22,7 +22,9 @@ Global Flags:
 Additional help topics:{{range .Commands}}{{if .IsAdditionalHelpTopicCommand}}
   {{rpad .CommandPath .CommandPathPadding}} {{.Short}}{{end}}{{end}}{{end}}{{if .HasAvailableSubCommands}}
 
-Use "{{.CommandPath}} [command] --help" for more information about a command.{{end}}`
+Use "{{.CommandPath}} [command] --help" for more information about a command.{{end}}
+
+More help online: https://cli.rport.io`
 
 var environmentVariables = `
 

diff --git a/docs/.markdownlint.yaml b/docs/.markdownlint.yaml
@@ -0,0 +1,23 @@
+# Default state for all rules
+default: true
+
+# MD013/line-length - Line length
+MD013:
+  # Number of characters
+  line_length: 120
+  # Number of characters for headings
+  heading_line_length: 80
+  # Number of characters for code blocks
+  code_block_line_length: 120
+  # Include code blocks
+  code_blocks: true
+  # Include tables
+  tables: true
+  # Include headings
+  headings: true
+  # Include headings
+  headers: true
+  # Strict length checking
+  strict: false
+  # Stern length checking
+  stern: false
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,18 @@
+# About documentation
+
+The documentation system is based on [Hugo](https://gohugo.io/) and the [Geekdocs Theme](https://geekdocs.de/)
+
+## Write
+Use markdown with the [shortcodes from Geekdocs](https://geekdocs.de/shortcodes/).
+
+Start a local Hugo server to get a live preview of your changes
+```shell
+cd docs
+hugo server
+```
+
+## Check
+Before pushing, check your file with [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli)
+```shell
+npx markdownlint-cli content/
+```
diff --git a/docs/archetypes/default.md b/docs/archetypes/default.md
@@ -0,0 +1,6 @@
+---
+title: "{{ replace .Name "-" " " | title }}"
+date: {{ .Date }}
+draft: true
+---
+