Adress demo documentation feedback

trento-project · Jul 26, 2023 · 7c117d7 · 7c117d7
1 parent 333b317
commit 7c117d7
Show file tree

Hide file tree

Showing 3 changed files with 117 additions and 68 deletions.
diff --git a/README.md b/README.md
@@ -235,16 +235,17 @@ To implement new checks and test them:
 - locate the newly created Check in the Catalog directory `./priv/catalog/`
 - test the execution as [previously described](#testing-executions)
 
-# Installing a development environment
+# Running a local Wanda instance
 
-To set up a local development environment for hacking on Wanda, you need to follow the instructions provided in [hack on wanda](./guides/development/hack_on_wanda.md).
+## Running a Development Environment
 
-This guide walks you through the process of installing and configuring the necessary dependencies, as well as setting up a local development environment.
+To set up a local development environment for hacking on Wanda, follow the instructions provided in [how to hack on wanda](./guides/development/hack_on_wanda.md).
 
-# Running a Demo environment
+This guide walks through the process of installing and configuring the necessary dependencies, as well as setting up a local development environment.
 
-Wanda can be run in demo mode.
-To set up a local development environment for hacking on Wanda, you need to follow the instructions provided in [run wanda demo on](./guides/demo.md).
+## Running a Demo Environment
+
+The demo mode of Wanda allows to showcase checks evaluation without the full setup with actual agents on the host. To run a demo instance, follow the instructions provided in [how to run wanda demo guide](./guides/demo.md).
 
 # Support
 

diff --git a/guides/demo.md b/guides/demo.md
@@ -1,124 +1,170 @@
 # Wanda Demo
 
-## Overview
+## Introduction
 
-Wanda Demo showcases the capabilities of the Trento project. It offers a simulated environment where we can demonstrate the seamless interaction between Web and Wanda. The configuration file provided in the demo simulates the fact gathering process, allowing us to perform a comprehensive evaluation of checks and displaying these on the web
+Wanda's demo mode provides a simulated environment where targets gathered facts are faked via a configuration yaml file. This empowers showcasing Trento's capabilities locally, and eases the development of the platform. The user is able to run check executions from the web, and wanda's fake server returns faked check execution data with failure messages and expectation names from the real catalog.
 
-## How to setup Wanda?
+## How to setup Wanda in demo mode?
 
-To set up a local development environment for hacking on Wanda, you need to follow the instructions provided in [hack on wanda](/guides/development/hack_on_wanda.md).
-
-## How to run Wanda in Demo mode?
-
-Instead of starting the local developer environment we need to start wanda in demo mode we can use this command
+First set up the [local environment](./development/hack_on_wanda.md) and run the following command to start Wanda in demo mode, instead of the usual `iex -S mix phx.server`
 
-```
-DATABASE_URL=ecto://postgres:postgres@localhost:5434/wanda_dev AMQP_URL=amqp://wanda:wanda@localhost:5674 SECRET_KEY_BASE=Tbp26GilFTZOXafb7FNVqt4dFQdeb7FAJ++am7ItYx2sMzYaPSB9SwUczdJu6AhQ CORS_ORIGIN=http://localhost:4000 ACCESS_TOKEN_ENC_SECRET=s2ZdE+3+ke1USHEJ5O45KT364KiXPYaB9cJPdH3p60t8yT0nkLexLBNw8TFSzC7k  PORT=4001  MIX_ENV=demo iex -S mix phx.server
+```bash
+$ DATABASE_URL=ecto://postgres:postgres@localhost:5434/wanda_dev \
+  AMQP_URL=amqp://wanda:wanda@localhost:5674 \
+  SECRET_KEY_BASE=Tbp26GilFTZOXafb7FNVqt4dFQdeb7FAJ++am7ItYx2sMzYaPSB9SwUczdJu6AhQ \
+  CORS_ORIGIN=http://localhost:4000 \
+  ACCESS_TOKEN_ENC_SECRET=s2ZdE+3+ke1USHEJ5O45KT364KiXPYaB9cJPdH3p60t8yT0nkLexLBNw8TFSzC7k \
+  PORT=4001 \
+  MIX_ENV=demo \
+  iex -S mix phx.server
 ```
 
-Explanation:
+### Explanation of environment variables:
 
 - DATABASE_URL: The URL to connect to the Postgres database running in the Docker container.
 - AMQP_URL: The URL for RabbitMQ, used for message exchange.
-- SECRET_KEY_BASE: The secret key for Wanda, keep it secure.
+- SECRET_KEY_BASE: The secret key for Wanda.
 - CORS_ORIGIN: The origin URL from where API requests are allowed (pointing to web).
 - ACCESS_TOKEN_ENC_SECRET: Secret key for encrypting access tokens.
 - PORT: The port on which Wanda will run (4001 in this case).
 - MIX_ENV: The environment in which Wanda will run (set to "demo" for the demo environment).
 
-## Modify the demo facts configuration
-
-Open the [fake_facts](priv/demo/fake_facts.yaml) configuration and add a new target entry to the targets section following this format:
+## Modify demo facts configuration
 
-### Add a new target to the demo configuration
-
-```
-targetX: <new_target_id>
-```
+In the Wanda demo environment, configure fake facts by editing the [fake_facts configuration](/priv/demo/fake_facts.yaml). Define custom facts for different targets and checks.
 
-Replace targetX with a unique target identifier (e.g target3), and <new_target_id>
+### YAML Structure
 
-Example
+The Configuration is saved in [fake_facts.yaml](/priv/demo/fake_facts.yaml) file, which follows a specific structure with two main sections: targets and facts.
 
-Existing configuration:
+Example:
 
-```
+```yaml
 targets:
   target1: 0a055c90-4cb6-54ce-ac9c-ae3fedaf40d4
   target2: 13e8c25c-3180-5a9a-95c8-51ec38e50cfc
+facts:
+  check_1:
+    fact_name1:
+      target1: 2
+      target2: 3
 ```
 
-Add new target with a identifier (e.g target3) and a new_target_id:
+#### Targets
 
-```
+The targets section allows defining handles for targets' UUIDs, providing a reference that can be used through the configuration.
+
+Format:
+
+```yaml
 targets:
-  target1: 0a055c90-4cb6-54ce-ac9c-ae3fedaf40d4
-  target2: 13e8c25c-3180-5a9a-95c8-51ec38e50cfc
-  target3: <new_target_id>
+  <target_reference>: <target_id>
 ```
 
-### Add a new check to the demo configuration
+<target_reference>: A user-defined handle or reference for a target.
 
-To add a new check locate the section that defines the facts.
+<target_id>: The UUID or identifier of the target.
 
-#### Add a new check entry using the following format
+#### Add a new target to the demo configuration
 
-```
-facts:
-<CheckID>:
-<Fact Name>:
-target1: <Fact Value>
-target2: <Fact Value>
-target3: <Fact Value>
-```
-
-Example:
+Open the [fake_facts](priv/demo/fake_facts.yaml) configuration and add a new target entry to the targets section, following this format:
 
 ```
-facts:
-.......existing checks..........
-
-new_check_id:
-  new_fact_name:
-    target1: <fact value>
-    target2: <fact value>
-    target3: <fact value>
+targetX: <new_target_id>
 ```
 
-Full example
+Replace targetX with an unique target identifier (e.g target3) and <new_target_id>
 
-Before
+Add new target with an identifier (e.g target3) and a new target id:
 
 ```
 targets:
   target1: 0a055c90-4cb6-54ce-ac9c-ae3fedaf40d4
   target2: 13e8c25c-3180-5a9a-95c8-51ec38e50cfc
+  target3: <new_target_id>
+```
 
-  facts:
-.......existing checks..........
+### Facts Section:
 
+The facts section allows specifying the facts associated with specific targets and checks. Each fact corresponds to a piece of information that a target can return during the evaluation of a check.
+
+The format for the facts section is as follows:
+
+```yaml
+facts:
+  <check_id>:
+    <fact_name>:
+      <target_reference>: <fact value>
+    <another_fact_name>:
+      <another_target_reference>: <fact value>
 ```
 
-After
+#### Add a new Fact to the demo configuration
+
+Open the [fake_facts](priv/demo/fake_facts.yaml) configuration and add a new fact to the facts section, following this format:
 
+```yaml
+facts:
+  <check_id>:
+    <fact_name>:
+      target1: <fact value>
+      target2: <fact value>
+      target3: <fact value>
 ```
+
+Example:
+
+```yaml
 targets:
   target1: 0a055c90-4cb6-54ce-ac9c-ae3fedaf40d4
   target2: 13e8c25c-3180-5a9a-95c8-51ec38e50cfc
   target3: <new_target_id>
 
 facts:
-.......existing checks..........
+.......existing facts..........
   new_check_id:
     new_fact_name:
       target1: <fact value>
       target2: <fact value>
       target3: <fact value>
 ```
 
-#### How to apply the changes?
+## FAQ
+
+### How to apply the configuration changes?
+
+Save the YAML configuration file and re-run executions from the [web](https://github.com/trento-project/web) ui
+
+### What happens with unmapped targets, facts or checks?
+
+Wanda will still evaluate and return a default fallback fact value "some fact value" for a check's execution. This means when a new check is added to wanda, changing the the configuration is optional.
+
+### How to know what's the correct return value of a fact?
+
+Determining the correct return value of a fact requires inspecting the specific check itself. Every Fact Gatherer has specific return values. To get an overview of all gatherers, refer to [Wanda's gatherers guide](/guides/gatherers.md).
+
+Visit the [Checks Catalog](/priv/catalog/) to find out which gatherer is used for the specific check
+
+Each check contains a facts section that provides information about the gatherer used.
+
+Example for Check "DA114A":
+
+```yaml
+facts:
+  - name: corosync_nodes
+    gatherer: corosync.conf
+    argument: nodelist.node
+```
+
+Reading the values section of a specific check helps to identify values, which a fact gatherer can return.
 
-- Save the YAML configuration file
-- Re-run executions from UI
+Example:
 
-### How do i know which values a check can have?
+```yaml
+values:
+  - name: expected_totem_interfaces
+    default: 2
+    conditions:
+      - value: 1
+        when: env.provider == "azure" || env.provider == "gcp"
+```
diff --git a/mix.exs b/mix.exs
@@ -60,7 +60,8 @@ defmodule Wanda.MixProject do
       "guides/expression_language.md",
       "guides/gatherers.md",
       "guides/rhai_expressions_cheat_sheet.cheatmd",
-      "guides/development/hack_on_wanda.md"
+      "guides/development/hack_on_wanda.md",
+      "guides/demo.md"
     ]
   end
 
@@ -71,7 +72,8 @@ defmodule Wanda.MixProject do
         "guides/expression_language.md",
         "guides/gatherers.md"
       ],
-      "Hack on Wanda": ["guides/development/hack_on_wanda.md"]
+      "Hack on Wanda": ["guides/development/hack_on_wanda.md"],
+      "Wanda Demo": ["guides/demo.md"]
     ]
   end