The configuration microservice for Azure IoT Solutions
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

DEPRECATED: This repository is no longer maintained. It has been moved to a new location. Please visit our new repository here. This microservice is present under services sub-module.

Build Issues Gitter

Config Service Overview

This service handles communication with the Storage Adapter microservice to complete tasks.

The microservice provides a RESTful endpoint to make CRUD operation for "devicegroups","solution-settings" and "user-settings". The data will be stored by the Storage Adapter microservice.


This microservice was built as part of the Azure IoT Remote Monitoring project to provide a generic implementation for an end-to-end IoT solution. More information here.


  • Create or update device groups
  • Get all or a single device group
  • Get or upload logo
  • Get or set overall solution settings
  • Get or set individual user settings


  • View the API documentation in the Wiki.

How to Use

Running the service with Docker

You can run the microservice and its dependencies using Docker with this instructions here.

Running the service locally


1. Deploy Azure Services

This service has a dependency on the following Azure resources. Follow the instructions for Deploy the Azure services.

  • Cosmos DB
  • Iot Hub
  • Maps (optional)

2. Setup Dependencies

This service depends on the following repositories. Run those services from the instructions in their READMEs in the following order.

  1. Storage Adapter Microservice
  2. Telemetry Microservice
  3. Device Simulation Microservice

3. Environment variables required to run the service

In order to run the service, some environment variables need to be created at least once. See specific instructions for IDE or command line setup below for more information. More information on environment variables here.

Running the service in an IDE


Running the service with IntelliJ IDEA

IntelliJ IDEA lets you open the application without using a command prompt, without configuring anything outside of the IDE. The SBT build tool takes care of downloading appropriate libraries, resolving dependencies and building the project (more info here).

Steps using IntelliJ IDEA Community, with SBT plugin enabled:

  • Make sure the prerequisites are set up.
  • "Open" the project with IntelliJ, the IDE should automatically recognize the SBT structure. Wait for the IDE to download some dependencies (see IntelliJ status bar). This may take a while, hang in there!
  • Create a new Run Configuration, of type "SBT Task", with any name.
    • Enter "run 9004" (including the double quotes) in Tasks. This ensures that the service starts using the TCP port 9004. If you desire to use a different port, feel free to change it.
    • Define the following environment variable:
      • PCS_STORAGEADAPTER_DOCUMENTDB_CONNSTRING = {your Cosmos DB connection string}
      • etc.
  • Either from the toolbar or the Run menu, execute the configuration just created, using the Debug command/button
  • Test that the service is up and running pointing your browser to

Running the service with Eclipse

The integration with Eclipse requires the sbteclipse plugin, already included, and an initial setup via command line (more info here).

Steps using Eclipse Oxygen ("Eclipse for Java Developers" package):

  • Open a console (either Bash or Windows CMD), move into the project folder, execute sbt compile and then sbt eclipse. This generates some files required by Eclipse to recognize the project.
  • Open Eclipse, and from the Welcome screen "Import" an existing project, navigating to the root folder of the project.
  • From the console run sbt -jvm-debug 9999 "run 9004" to start the project
  • Test that the service is up and running pointing your browser to
  • In Eclipse, select "Run -> Debug Configurations" and add a "Remote Java Application", using "localhost" and port "9999".
  • After saving this configuration, you can click "Debug" to connect to the running application.

Running the service from the command line

  1. Make sure the prerequisites are set up.
  2. Set the following environment variables in your system. More information on environment variables here.
    1. PCS_STORAGEADAPTER_WEBSERVICE_URL = http://localhost:9022/v1
    2. PCS_DEVICESIMULATION_WEBSERVICE_URL = http://localhost:9003/v1
    3. PCS_TELEMETRY_WEBSERVICE_URL = http://localhost:9004/v1
    4. PCS_AZUREMAPS_KEY = static
  3. Use the scripts in the scripts folder for many frequent tasks:
    • build: compile all the projects and run the tests.
    • compile: compile all the projects.
    • run: compile the projects and run the service. This will prompt for elevated privileges in Windows to run the web service.

If you are familiar with SBT, you can also use SBT directly. A copy of SBT is included in the root of the project.

Project Structure

  • Code for the application is in app/com/microsoft/azure/iotsolutions/config
    • webservice - web service exposing REST interface
    • services - business logic for interacting with Storage Adapter webservice
  • Tests are in the test folder
    • WebService - Tests for web services functionality
    • Service - Tests for services functionality
  • Configuration files and routes are in the conf folder
  • The scripts folder contains build scripts, docker container creation scripts, and scripts for running the microservice from the command line

Updating the Docker image

The scripts folder includes a docker subfolder with the files required to package the service into a Docker image:

  • build: build a Docker container and store the image in the local registry.
  • run: run the Docker container from the image stored in the local registry.

You might notice that there is no Dockerfile. All Docker settings are defined in build.sbt.

dockerRepository := Some("azureiotpcs")
dockerAlias := DockerAlias(dockerRepository.value, None, packageName.value + "-java", Some((version in Docker).value))
dockerBaseImage := "toketi/openjdk-8-jre-alpine-bash"
dockerUpdateLatest := false
dockerBuildOptions ++= Seq("--compress", "--label", "Tags=azure,iot,pcs,telemetry,Java")
dockerEntrypoint := Seq("bin/telemetry")

The package logic is executed via sbt-native-packager, installed in plugins.sbt.

Configuration and Environment variables

The service configuration is stored using Akka's HOCON format in application.conf.

The HOCON format is a human readable format, very close to JSON, with some useful features:

  • Ability to write comments
  • Support for substitutions, e.g. referencing environment variables
  • Supports JSON notation

The configuration file in the repository references some environment variables that need to created at least once. Depending on your OS and the IDE, there are several ways to manage environment variables:

Contributing to the solution

Please follow our contribution guildelines and code style conventions. We love PRs!


Please enter issues, bugs, or suggestions as GitHub Issues.


Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT License.