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 -s -o /dev/null http://api.astarte.localhost && 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 --recurse-submodules git@github.com:edgehog-device-manager/edgehog.git && 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.

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.

SEEDS_REALM_PRIVATE_KEY_FILE must point to the private key of the test realm you created in Astarte. If you followed the "Astarte in 5 minutes" guide, astartectl generated the key as test_private.pem in the astarte repository, so set this variable to its full path, for example ../astarte/test_private.pem. Keeping the default value (the bundled realm_private.pem) would prevent Edgehog from communicating with your Astarte instance.

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

This creates acme_private.pem and acme_public.pem in the current working directory.

Remember to update the .env file, setting SEEDS_TENANT_PRIVATE_KEY_FILE to the location of acme_private.pem (e.g. ./acme_private.pem if you ran the command in the edgehog directory)!

The SEEDS_* variables and the key files are read by Docker Compose when the containers are created, so make sure to edit .env and generate your key pairs before starting the containers. If you already ran docker compose up -d, recreate the containers for the changes to take effect:

$ docker compose up -d --force-recreate

Start Edgehog

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!

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 Elixir installed in your system. If you're using the asdf version manager, you can install Elixir by running:

$ asdf install

Now you can generate the login token with

$ ./tools/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

$ ./tools/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

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.