feat: Edgehog in 5 minutes

Signed-off-by: Francesco Noacco <francesco.noacco@secomind.com>

doc/mix.exs

@@ -50,7 +50,8 @@ defmodule Doc.MixProject do
         "User Guide": ~r"/user/",
         Architecture: ~r"/architecture/",
         "Admin Guide": ~r"/admin/",
-        "Integrating with Edgehog": ~r"/integrating/"
+        "Integrating with Edgehog": ~r"/integrating/",
+        Tutorials: ~r"/tutorials"
       ],
       groups_for_modules: []
     ]
@@ -68,6 +69,7 @@ defmodule Doc.MixProject do
       "pages/user/groups.md",
       "pages/user/ota_updates.md",
       "pages/user/batch_operations.md",
+      "pages/tutorials/edgehog_in_5_minutes.md",
       "pages/architecture/overview.md",
       "pages/integrating/interacting_with_edgehog.md",
       "pages/integrating/astarte_interfaces.md",

doc/pages/tutorials/edgehog_in_5_minutes.md

@@ -0,0 +1,273 @@
+<!---
+  Copyright 2023 SECO Mind Srl
+
+  SPDX-License-Identifier: Apache-2.0
+-->
+
+# Edgehog in 5 minutes
+
+## Prerequisites
+
+### Setup a local Astarte instance
+
+You need a working astarte instance for edgehog to connect to. If you don't already have one, the
+easiest way is by following the [Astarte in 5 minutes](https://docs.astarte-platform.org/astarte/latest/010-astarte_in_5_minutes.html)
+guide, up until the creation of a `test` realm.
+
+To make sure your astarte instance is working and up to date, try running this command:
+
+```sh
+$ curl api.astarte.localhost &> /dev/null && echo 'Connected!' || echo 'Astarte is unreachable'
+```
+
+If you get "Astarte is unreachable", make sure your running astarte version is >= v1.1.0
+
+### Setup a python environment
+
+> This is only needed for generating the jwt token using the official script
+
+You need python version 3 installed.
+If you're on ubuntu/debian, you may also need to install the `python3-venv` package.
+
+```sh
+$ python3 --version
+Python 3.x.y
+```
+
+Let's now create a virtual environment.
+
+```sh
+$ python3 -m venv pyenv
+```
+
+and activate it
+
+```sh
+$ source pyenv/bin/activate
+```
+
+This will let you install python packages without messing with your system files.
+
+## Run a local Edgehog instance
+
+To setup edgehog, you must first clone a copy of edgehog locally
+
+```sh
+$ git clone https://github.com/edgehog-device-manager/edgehog && cd edgehog
+```
+
+You can then run edgehog with
+
+```sh
+$ docker-compose up -d
+```
+
+Try navigating to `http://localhost:8080`: you should be presented with a login screen!
+
+## Setup the environment
+
+> If you just want to try out Edgehog, you can jump to
+> [the next section](#populate-the-database-and-log-in-to-edgehog).
+> Astarte communication will not work this way though.
+
+Open the `.env` file in your favorite text editor.
+Here you can edit docker's variables to match your current environment.
+Right now we're only interested in the `SEEDS_*` variables, which are used to populate the database.
+
+| Variable                        | Description                                                                                           |
+|---------------------------------|-------------------------------------------------------------------------------------------------------|
+| `SEEDS_REALM`                   | The name of your astarte realm. It should match what you've created in your astarte setup             |
+| `SEEDS_REALM_PRIVATE_KEY_FILE`  | The location of the realm's private key file (`test_private.pem` from the Astarte in 5 minutes guide) |
+| `SEEDS_TENANT_PRIVATE_KEY_FILE` | The location of the [tenant's private key file](#generate-a-key-pair-for-the-tenant)                  |
+| `SEEDS_ASTARTE_BASE_API_URL`    | The endpoint for Astarte API.                                                                         |
+
+If for whatever reason you don't want to edit the `.env` file, you can also export
+environment variables of the same name.
+
+`SEEDS_REALM` and `SEEDS_ASTARTE_BASE_API_URL` should already be set for you, so only edit those if
+needed.
+
+### Generate a key pair for the tenant
+
+Although it is possible to use a default key, it is recommended to have your own key pair for the
+tenant.
+
+You should already have [`astartectl`](https://github.com/astarte-platform/astartectl#installation)
+installed from the Astarte in 5 minutes guide.
+
+```sh
+$ astartectl utils gen-keypair acme
+```
+
+Remember to update the `.env` file with the `acme_private.pem` location!
+
+## Populate the database and log in to Edgehog
+
+Run this command to populate the database
+
+```sh
+$ docker-compose exec edgehog-backend bin/edgehog eval Edgehog.Release.seed
+```
+
+This will create the tenant `acme-inc` and add a sample device.
+
+> *"I had the wrong variables set, and now I can't run the seed again. What now?"*
+> If this happens, the easiest solution is to just recreate the edgehog volumes:
+> `docker-compose down -v && docker-compose up -d`
+
+To log in to edgehog you need to create a jwt. Edgehog includes a scripts to do just that!
+
+First you'll need to [setup python](#setup-a-python-environment).
+Then, navigate to the `tools/` subdirectory and install the required dependencies
+
+```sh
+$ cd tools
+
+$ pip install -r requirements.txt
+```
+
+Now you can generate the token with
+
+```sh
+$ ./gen-edgehog-jwt -k ../acme_private.pem
+```
+
+this should give you back the token you can use for login.
+
+> If in the previous section you had decided not to use a custom key, use this command instead
+>
+> ```sh
+> $ ./gen-edgehog-jwt -k ../backend/priv/keys/tenant_private.pem
+> ```
+
+You can finally navigate to `http://localhost:8080` in your browser and login to the
+`acme-inc` tenant with the newly generated token.
+
+## Test Astarte connection
+
+First of all navigate to your astarte directory and run this command.
+
+```sh
+$ git clone https://github.com/edgehog-device-manager/edgehog-astarte-interfaces && find edgehog-astarte-interfaces -name '*.json' -exec astartectl realm-management interfaces sync {} --astarte-url http://api.astarte.localhost -r test -k test_private.pem -y \;
+```
+
+This will clone the required interfaces locally and install them using astartectl.
+
+> The reason we told you to exec this command inside the astarte directory is because you should
+> have `test_private.pem` inside there, but feel free to do this anywhere and adjust the
+> private key location.
+
+Now, proceed with the
+[trigger](https://docs.astarte-platform.org/astarte/latest/010-astarte_in_5_minutes.html#install-a-trigger)
+installation:
+
+- Connection trigger:
+
+```json
+{
+    "name": "edgehog-connection",
+    "action": {
+        "http_url": "http://edgehog-backend:4000/tenants/acme-inc/triggers",
+        "ignore_ssl_errors": true,
+        "http_method": "post",
+        "http_static_headers": {}
+    },
+    "simple_triggers": [
+        {
+            "type": "device_trigger",
+            "on": "device_connected"
+        }
+    ]
+}
+```
+
+- Disconnection trigger:
+
+```json
+{
+    "name": "edgehog-disconnection",
+    "action": {
+        "http_url": "http://edgehog-backend:4000/tenants/acme-inc/triggers",
+        "ignore_ssl_errors": true,
+        "http_method": "post",
+        "http_static_headers": {}
+    },
+    "simple_triggers": [
+        {
+            "type": "device_trigger",
+            "on": "device_disconnected"
+        }
+    ]
+}
+```
+
+- OTA Event trigger:
+
+```json
+{
+    "name": "edgehog-ota-event",
+    "action": {
+        "http_url": "http://edgehog-backend:4000/tenants/acme-inc/triggers",
+        "ignore_ssl_errors": true,
+        "http_method": "post",
+        "http_static_headers": {}
+    },
+    "simple_triggers": [
+        {
+            "type": "data_trigger",
+            "interface_name": "io.edgehog.devicemanager.OTAEvent",
+            "interface_major": 0,
+            "on": "incoming_data",
+            "match_path": "/*",
+            "value_match_operator": "*"
+        }
+    ]
+}
+```
+
+- System Info trigger:
+
+```json
+{
+    "name": "edgehog-system-info",
+    "action": {
+        "http_url": "http://edgehog-backend:4000/tenants/acme-inc/triggers",
+        "ignore_ssl_errors": true,
+        "http_method": "post",
+        "http_static_headers": {}
+    },
+    "simple_triggers": [
+        {
+            "type": "data_trigger",
+            "on": "incoming_data",
+            "interface_name": "io.edgehog.devicemanager.SystemInfo",
+            "interface_major": 0,
+            "match_path": "/*",
+            "value_match_operator": "*"
+        }
+    ]
+}
+```
+
+If you now connect a device to astarte and open or reload the edgehog web page,
+you should see the new device in the appropriate section.
+
+
+> You can use [stream-qt5-test](https://docs.astarte-platform.org/astarte/latest/010-astarte_in_5_minutes.html#stream-data).
+> If you do so the device won't have any edgehog interface, but it will still show up as connected.
+
+## Cleaning up
+
+As with astarte, you can clean your environment by running
+
+```sh
+$ docker-compose down
+```
+
+to stop all the running edgehog containers.
+
+It's a good idea to also clean your shell from the python virtual environment by simply typing
+
+```sh
+$ deactivate
+```