Skip to content

Latest commit

 

History

History
134 lines (89 loc) · 7.32 KB

node-devbox-setup.md

File metadata and controls

134 lines (89 loc) · 7.32 KB
Raw

Prepare your development environment

This document describes how to prepare your development environment to work with the Microsoft Azure IoT SDKs for Node.js code.

Important: If you don't need to modify the code for the node SDKs, it is recommended to use the npm packages as the below instructions are meant to test the code and not to be used for app development. Instructions for using the npm packages can be found here:

Prerequisites

If you're running linux and want to install Node.js using a package manager, please refer to these instructions. The Azure IoT SDK for Node.js supports Node.js version 6 and up. It may still work with older versions (Node 0.10, 0.12 and 4) but our dependencies are dropping support for those versions since they have been end-of-lifed, so we cannot guarantee full support for these anymore.

The Node Version Switcher can be used if you would like to be able to switch from one Node.js version to another.

In order to be able to create and test x509 certificates using our build scripts, you will also need to have OpenSSL installed.

Setup your development environment

The SDK is entirely open-source. Downloading the whole SDK source code is as simple as cloning the repository:

$ git clone https://github.com/azure/azure-iot-sdk-node

If you are going to be developing on Windows you will need to install some additional build tools. In an administrator command prompt:

npm install -g windows-build-tools

This will probably take serveral minutes to run.

The SDK ships in multiple NPM packages that depend on one another. We use lerna.js to "link" those package together in a single environment. At a prompt with administrative privileges:

npm install -g lerna

Once lerna is installed, you can set up your development environment by running the bootstrap command at the root of the repository. This installs all dependencies and links packages together. We add the --hoist option to eliminate duplicate dependencies and reduce the time and space requirements of the cloned repository.

lerna bootstrap --hoist

If you want to build/run the code, you'll need to compile the packages:

lerna run build

If you want to run the tests, add the necessary environment variables (described below) then execute:

lerna run ci

Same with the end-to-end tests:

lerna run e2e

Environment variables for testing

Please note that running tests and end-to-end tests require having an Azure IoT hub and an Azure IoT Hub Provisioning service setup and the proper environment variables configured. Here is the list of all the environment variables as well as how we use them:

  • OPENSSL_CONF: The SDK build script relies on OpenSSL to create certificates and keys so OpenSSL must be in the path and OPENSSL_CONF must be set to the path of your openssl.cnf configuration file.
  • IOTHUB_CONNECTION_STRING: must be set to a configuration string of your IoT Hub that has rights to create/delete devices and send messages to devices (typically, the one associated with the iothubowner policy or equivalent). Connection strings can be found in the settings section of the Azure portal.
  • STORAGE_CONNECTION_STRING: must be set to an Azure Storage connection string if you want to test bulk import/export of device identities.
  • IOTHUB_CA_ROOT_CERT: must be set to the base64-encoded content of the certificate set a custom CA cert provisioned on IoT Hub.
  • IOTHUB_CA_ROOT_CERT_KEY: must be set to the base64-encoded content of the key if the custom CA cert provisioned on IoT Hub.
  • IOT_PROVISIONING_DEVICE_IDSCOPE: must be set to the idScope of your provisioning service.
  • IOT_PROVISIONING_DEVICE_ENDPOINT: must be set to the public endpoint of your provisioning service or the global endpoint.
  • IOT_PROVISIONING_SERVICE_CONNECTION_STRING: must be set to the connection string of your provisioning service.
  • IOT_PROVISIONING_ROOT_CERT: must be set to the base64-encoded content of a root certificate used to test the group enrollments feature of the device provisioning service
  • IOT_PROVISIONING_ROOT_CERT_KEY: must be set to the base64-encoded content of the key associated with the group enrollment root certificate.
  • DPS_CONN_STRING_INVALID_CERT: must be set to a connection string for a DPS instance, such that DNS resolution for the server specified in the connection string will direct to a server which does not present a matching certificate during TLS connection establishment.
  • DPS_GLOBAL_DEVICE_ENDPOINT_INVALID_CERT: must be set to a DPS global endpoint, such that DNS resolution for the server specified in the string will direct to a server which does not present a matching certificate during TLS connection establishment.
  • IOTHUB_CONN_STRING_INVALID_CERT: must be set to a connection string for an IoT Hub instance, such that DNS resolution for the server specified in the connection string will direct to a server which does not present a matching certificate during TLS connection establishment.
  • IOTHUB_DEVICE_CONN_STRING_INVALID_CERT: must be set to a connection string for an IoT Device, such that DNS resolution for the server specified in the connection string will direct to a server which does not present a matching certificate during TLS connection establishment.

Running the samples in the samples folder

The device and service SDKs samples are located in their respective folders. If you build and run the samples in the samples folder after running lerna bootstrap then the samples will be linked to local 'packages' at the same time as the rest of the SDK.

$ cd device/samples

Then, add the environment variable DEVICE_CONNECTION_STRING to your terminal session. Depending on the sample, you may have to add more credentials such as a storage key. You can open the sample file to check.

$ export DEVICE_CONNECTION_STRING="<YourIoTHubDeviceConnectionString>"

Once this is done, just run it like any other node script:

$ node simple_sample_device.js

Running the samples NOT in the samples folder

Refer to the readme in the samples folder, linked here.

Going further

Standard NPM scripts

Each package in the SDK comes with the same set of NPM scripts that run various operations on the package:

  • npm run build will run the TypeScript compiler and generate javascript code
  • npm run lint will run tslint and lint the TypeScript code
  • npm run alltest will lint, build, run all tests, and create code coverage data
  • npm run ci will lint, build, run all tests and verify code coverage against existing numbers. (this is what the CI build does).

Tests

The Azure IoT SDKs team keeps a close watch on tests and code coverage when committing new code, whether it's for bugfixes or new features. To learn how to run the unit, integration and E2E tests, read this.