Local development setup

This guide will walk you through setting up an environment in which you launch the platform, setting up as many elements as possible locally.

Overview

The overview of the platform elements can be found on the technical index page.

In this guide, all of the elements will be launched locally, except for:

the Azure IoT Hub
Azure Service Bus
the InfluxDB database
an Azure Storage Account

For these services, you could use those that are deployed by the CI/CD pipeline on a development environment.

Depending on your needs, you might not have to launch everything locally. You can also simply pick what you need from this guide.

This guide will explain how to setup the environment and to launch locally:

the device management front-end
the Management API
the Azure functions
the device simulator

All of the code is in this project's mono-repository.

Azure Service Bus setup

One issue when running the platform locally is that the Azure Service Bus (ASB) cannot run outside of Azure. If you use the same one as one of your live environments, you will encounter conflicts between your local Azure Functions and the remote ones, since they will share the same data topics and subscriptions.

Consequently, before launching everything locally, it is advised to create an ASB dedicated to the local development. ASB is cheap in its standard version, so it will not increase the cost of your Azure subscription in any significant way.

Once it is created, you will need to setup the topics and subscription. It can be cumbersome and take some time, so a script is available in the dev-tools folder to initialize the ASB according to your needs. The script can also clear everything you have created. Before running it, you need to copy your ASB connection string. Then, open a terminal at the root of the project, and execute those commands:

cd dev-tools
npm i
npm run setup-service-bus

Follow the instructions, and everything will be setup automatically. It is advised to use a different suffix by developer to avoid conflicts.

Note

When created through the script, subscriptions and topics are configured to auto-delete on idle after 30 days.

Then, you need to configure your environment variables to use your topics and subscriptions names based on what have been created by the script. To find them, check the .envrc.example files of the Management API and WSS, and see the local.settings.example.json file of each of your Azure Functions. For the Azure Functions, it is strongly recommended to use a local.settings.json file (git-ignored) next to the example file to provide the environment variables.

This setup will allow you to run the whole ingestion chain locally without conflict, and without having to reconfigure stuff every day.

There is one limitation that can be easily overcome: the IoT Hub device lifecycle. Messages are directly sent from IoT Hub to the ASB. So, to work with it, you need to add a new custom endpoint pointing to your new ASB, and configure it the same way as the one that already handles the lifecycle events for the real.

Front-end

Requirements

When the front-end and the API are launched locally, the front-end does not need a specific setup.

Launching

In the monorepository root directory, the following commands will start the device management front-end:

npm install
npm run start:front

This will start the front-end app that lives in iot-manager/core/apps/client/management-front-end.

Additionally, you can launch the settings front-end:

npm run start:settings

This will start the front-end app that lives in iot-manager/core/apps/settings-app.

You will be able to access both front-ends through the link displayed once the startup has finished.

Management API

The API code is in iot-manager/core/apps/api/management-api.

Requirements

Some API functionalities depend on external services. The setup to use these services is explained in the API's readme file, in the Additional setup for using external services when running locally section.
The API needs a MS-SQL database. You can spin up one locally in any way you like, as long as you set the API's environment variables accordingly in your .envrc file.
Make sure your .envrc file looks like .envrc.example and review it to check your environment variables match your expectations.
If you want to load some initial fixtures, check out the Loading initial platform data guide.

Requirements

Some API functionalities depend on external services. The setup to use these services is explained in the API's readme file, in the Additional setup for using external services when running locally section.
The API needs a MS-SQL database. You can spin up one locally in any way you like, as long as you set the API's environment variables accordingly in your .envrc file. It should be a different database than for the other API.
Make sure your .envrc file looks like .envrc.example and review it to check your environment variables match your expectations.
If you want to load some initial fixtures, it works the same way as for the Management API.

Windows specificities

On Windows, you can not use the global launch command and you need to setup the environnement variables for the API to start.

You can either do that manually, or use direnv (recommended).

Direnv setup

This setup assumes you're using Git Bash as a command prompt.

Steps marked with a (1) are specific to Git Bash. If you're using another terminal, you must find the way to hook the terminal to direnv. See the direnv doc for more details.

Create a folder such as C:\tools to put the direnv.exe file and add it to the Windows PATH
Go to https://github.com/direnv/direnv/releases to find the latest release of direnv.
Click on direnv.windows-amd64.exe to download the file
Copy the file to C:\tools and rename it as direnv
Open the Git Bash terminal and execute $ echo ~ to find the location in Windows of the user's home directory (1)
If a .bash_profile file doesn't exist in the user's home directory, create one (1)
Follow the instructions at https://direnv.net/docs/hook.html#bash and add the following text to .bashrc: eval "$(direnv hook bash)" (1)
From your chosen terminal, open to the same location as the .envrc file, enter the command:

direnv allow

The result should look like this:

$ direnv allow
direnv: loading ~/Documents/DEV/iot-manager/core/apps/api/management-api/.envrc
direnv: export +APP_URL_DEVICE +APP_URL_SETTINGS +AUTH0_DOMAIN_URL +AUTH0_MANAGEMENT_API_CLIENT_ID +AUTH0_MANAGEMENT_API_CLIENT_SECRET +AUTH0_MANAGEMENT_API_URL +CORS_ORIGIN +DB_HOST +DB_NAME +DB_PASSWORD +DB_PORT +DB_USER +INFLUX_AF_KEY +INFLUX_AF_URL +JWT_AUDIENCE +JWT_ISSUER +JWT_ISSUER_WELL_KNOWN_URL +LOG_LEVELS +NODE_ENV +PORT +STORAGE_ACCOUNT_URL

You're set ! You can now run at the root of the managament-api folder the following:

npm run start

Please note that after every change to the .envrc file, you must again execute the command:

direnv allow

Launching

In the mono-repository root directory, the following commands will start the API:

npm install
npm run start:management-api

Azure functions

The Azure functions code is in iot-manager/core/apps/azure-functions.

Requirements

The func command to start the functions
Setting environment variables

More information about the two elements above can be found in the Azure functions readme file.

The Azure functions require a database to retrieve information about the telemetries they handle. Make sure in the environment variables to target the same database as the API, so that the database schema and data will exist as expected.

Launching

In the functions directory:

npm install
npm run start

Device simulator

The device simulator code can be found in iot-manager/device-simulator.

The requirements depend on the way you will authenticate your device for the IoT Hub.

If you use the DPS, the information to set it up is in the device simulator's readme file.

If you use a device SAS key, you can choose one of two ways to retrieve a key for your device:

Through the API

Create or choose an existing device using the API or the front-end. This device needs to have a device type that can use an IoT Hub interface.
Provision the device, or choose an already provisioned device for IoT Hub
Retrieve its SAS primary key through the API or show them in the front-end

Through the IoT Hub

Navigate to the IoT Hub on the Azure portal
In the menu, select Devices
Choose a device or create a new one
Click on your device, and copy its Primary key

The instructions to run the simulator are described in the simulator's readme file.