Deploy the Remote Monitoring solution accelerator locally - Docker
This article shows you how to deploy the Remote Monitoring solution accelerator to your local machine for testing and development. You learn how to deploy the microservices to local Docker containers. A local microservices deployment uses the following cloud services: IoT Hub, Cosmos DB, Azure Streaming Analytics, and Azure Time Series Insights services in the cloud.
If you want to run the Remote Monitoring solution accelerator in an IDE on your local machine, see Deploy the Remote Monitoring solution accelerator locally - Visual Studio.
Prerequisites
To deploy the Azure services used by the Remote Monitoring solution accelerator, you need an active Azure subscription.
If you don’t have an account, you can create a free trial account in just a couple of minutes. For details, see Azure Free Trial.
Machine setup
To complete the local deployment, you need the following tools installed on your local development machine:
- Git
- Docker
- Visual Studio - if you plan to make changes to the microservices.
- Node.js v8 - this software is a prerequisite for the PCS CLI that the scripts use to create Azure resources. Don't use Node.js v10.
Note
These tools are available on many platforms, including Windows, Linux, and iOS.
Download the source code
The Remote Monitoring source code repositories include the source code and the Docker configuration files you need to run the microservices Docker images.
To clone and create a local version of the repository, use your command-line environment to navigate to a suitable folder on your local machine. Then run one of the following sets of commands to clone either the .NET repository:
To download the latest version of the .NET microservice implementations, run:
git clone --recurse-submodules https://github.com/Azure/azure-iot-pcs-remote-monitoring-dotnet.git
# To retrieve the latest submodules, run the following command:
cd azure-iot-pcs-remote-monitoring-dotnet
git submodule foreach git pull origin master
Note
These commands download the source code for all the microservices in addition to the scripts you use to run the microservices locally. Although you don't need the source code to run the microservices in Docker, the source code is useful if you later plan to modify the solution accelerator and test your changes locally.
Deploy the Azure services
Although this article shows you how to run the microservices locally, they depend on Azure services running in the cloud. Use the following script to deploy the Azure services. The following script examples assume you're using the .NET repository on a Windows machine. If you're working in another environment, adjust the paths, file extensions, and path separators appropriately.
Create new Azure resources
If you've not yet created the required Azure resources, follow these steps:
In your command-line environment, navigate to the \services\scripts\local\launch folder in your cloned copy of the repository.
Run the following commands to install the pcs CLI tool and sign in to your Azure account:
npm install -g iot-solutions pcs loginRun the start.cmd script. The script prompts you for the following information:
A solution name.
The Azure subscription to use.
The location of the Azure datacenter to use.
The script creates resource group in Azure with your solution name. This resource group contains the Azure resources the solution accelerator uses. You can delete this resource group once you no longer need the corresponding resources.
The script also adds a set of environment variables with a prefix PCS to your local machine. These environment variables provide the details for Remote Monitoring to be able to read from an Azure Key Vault resource. This Key Vault resource is where Remote Monitoring will read its configuration values from.
Tip
When the script completes, it also saves the environment variables to a file called <your home folder>\.pcs\<solution name>.env. You can use them for future solution accelerator deployments. Note that any environment variables set on your local machine override values in the services\scripts\local\.env file when you run docker-compose.
Exit from your command-line environment.
Use existing Azure resources
If you've already created the required Azure resources, create the corresponding environment variables on your local machine. Set the environment variables for the following:
- PCS_KEYVAULT_NAME - Name of the Azure Key Vault resource
- PCS_AAD_APPID - The AAD application ID
- PCS_AAD_APPSECRET - The AAD application secret
Configuration values will be read from this Azure Key Vault resource. These environment variables may be saved in the <your home folder>\.pcs\<solution name>.env file from the deployment. Note that environment variables set on your local machine override values in the services\scripts\local\.env file when you run docker-compose.
Some of the configuration needed by the microservice is stored in an instance of Key Vault that was created on initial deployment. The corresponding variables in keyvault should be modified as needed.
Run the microservices in Docker
Open a new command prompt to be sure to have access to the environment variables set by the start.cmd script. On Windows, you can verify the environment variables are set by running the following command:
set PCS
The command shows all the environment variables set by the start.cmd script.
Make sure that Docker is running on your local machine.
Note
Docker must be running Linux containers if it is running on Windows.
The microservices running in the local Docker containers need to access the Azure cloud services. You can test the internet connectivity of your Docker environment using the following command to ping an internet address from inside a container:
docker run --rm -ti library/alpine ping google.com
To run the solution accelerator, navigate to the services\scripts\local folder in your command-line environment and run the following command:
docker-compose up
Note
Make sure you share a local drive with Docker before you run docker-compose up.
The first time you run this command, Docker downloads the microservice images from Docker hub to build the containers locally. On following runs, Docker runs the containers immediately.
Tip
Microsoft frequently publishes new Docker images with new functionality. You can use the following set of commands to cleanup your local Docker containers and corresponding images before you pull the latest ones:
docker list
docker rm <list_of_containers>
docker rmi <list_of_images>
You can use a separate shell to view the logs from the container. First find the container ID using the docker ps command. Then use docker logs {container-id} --tail 1000 to view the last 1000 entries for the specified container.
Start the Stream Analytics job
Follow these steps to start the Stream Analytics job:
- Navigate to the Azure portal.
- Navigate to the Resource group created for your solution. The name of the resource group is the name you chose for your solution when you ran the start.cmd script.
- Click on the Stream Analytics job in the list of resources.
- On the Stream Analytics job overview page, click the Start button. Then click Start to start the job now.
Connect to the dashboard
To access the Remote Monitoring solution dashboard, navigate to https://localhost:8080 in your browser. You can now use the Web UI and the local microservices.
Clean up
To avoid unnecessary charges, when you've finished your testing remove the cloud services from your Azure subscription. To remove the services, navigate to the Azure portal and delete the resource group that the start.cmd script created.
Use the docker-compose down --rmi all command to remove the Docker images and free up space on your local machine. You can also delete the local copy of the Remote Monitoring repository created when you cloned the source code from GitHub.
Next steps
Now that you've deployed the Remote Monitoring solution, the next step is to explore the capabilities of the solution dashboard.