Edgehog in 5 minutes

Prerequisites

Edgehog interacts with devices through Astarte. While it's possible to run an instance of Edgehog without the local instance of Astarte for development purposes, it's recommended to setup Astarte locally for full functionality.

Setup your local Astarte instance

The easiest way to setup local Astarte instance is to follow the Astarte in 5 minutes 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:

$ 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

Run a local Edgehog instance

To setup edgehog, you must first clone a copy of edgehog locally

$ git clone https://github.com/edgehog-device-manager/edgehog && cd edgehog

If you just want to try out Edgehog without interacting with the device, run it without the Astarte instance:

$ docker compose \
$   -f docker-compose.yml \
$   -f docker-compose.without-astarte.yml \
$   up -d

Then jump to the populate the database section.

Run Edgehog along with a local instance of Astarte with

$ docker compose up -d

Try navigating to http://edgehog.localhost: you should be presented with a login screen!

Setup the environment

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.

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 installed from the Astarte in 5 minutes guide.

$ 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

$ docker compose exec edgehog-backend bin/edgehog eval Edgehog.Release.seed

This will create the tenant acme-inc and add a sample device to it.

"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

Nice! Now we have our tenant but we can't access to it yet, we need a token. Luckily Edgehog includes a scripts to generate one!

First you'll need to make sure to have python version 3 installed.

$ python3 --version
Python 3.x.y

While not mandatory, it is advised to use a python virtual environment to make sure your globally installed python packages don't mess with this script's dependencies and vice versa. Doing this is pretty straightforward, but you may need to install the python3-venv package if you are using a Debian/Ubuntu-based system.

$ python3 -m venv pyenv
$ source pyenv/bin/activate

Then, navigate to the tools/ subdirectory and install the required dependencies

$ cd tools && pip install -r requirements.txt

Now you can generate the login token with

$ ./gen-edgehog-jwt -t tenant -k ../acme_private.pem

If in the previous section you had decided not to use a custom key, use this command instead

$ ./gen-edgehog-jwt -t tenant -k ../backend/priv/repo/seeds/keys/tenant_private.pem

You can finally navigate to http://edgehog.localhost in your browser and login to the acme-inc tenant using your newly generated token.

Test Astarte connection

Astarte connectivity may not work right away, as edgehog has not yet reconciled its interfaces and triggers with astarte. Without waiting, we can force it to execute the reconciler using:

$ docker compose exec edgehog-backend bin/edgehog rpc "Edgehog.Tenants.list_tenants |> Enum.each(&Edgehog.Tenants.reconcile_tenant/1)"

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. 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

$ docker compose down

to stop all the running edgehog containers.