Customize and redeploy a microservice

This tutorial shows you how to edit one of the microservices in the Remote Monitoring solution, build an image of your microservice, deploy the image to your docker hub, and then use it in Remote Monitoring solution. To introduce this concept, the tutorial uses a basic scenario where you call a microservice API and change the status message from "Alive and Well" to "New Edits Made Here!"

Remote Monitoring solution uses microservices that are built using docker images that are pulled from a docker hub.

In this tutorial, you learn how to:

  • Edit and build a microservice in the Remote Monitoring solution
  • Build a docker image
  • Push a docker image to your docker hub
  • Pull the new docker image
  • Visualize the changes

Prerequisites

To follow this tutorial, you need:

Call the API and view response status

In this part, you call the default IoT hub manager microservice API. The API returns a status message that you change later on by customizing the microservice.

  1. Make sure the Remote Monitoring solution is running locally on your machine.

  2. Locate where you downloaded Postman and open it.

  3. In Postman, enter the following in the GET: http://localhost:8080/iothubmanager/v1/status.

  4. View the return and you should see, "Status": "OK:Alive and Well".

    Alive and Well Postman Message

Change the status and build the image

Now change the status message of the Iot Hub Manager microservice to "New Edits Made Here!" and then rebuild the docker image with this new status. If you run into issues here, refer to our Troubleshooting section.

  1. Make sure your terminal is open and change to the directory where you have cloned the Remote Monitoring solution.

  2. Change your directory to "azure-iot-pcs-remote-monitoring-dotnet/services/iothub-manager/Services".

  3. Open StatusService.cs in any text editor or IDE that you like.

  4. Locate the following code:

    var result = new StatusServiceModel(true, "Alive and well!");
    

    and change it to the code below and save it.

    var result = new StatusServiceModel(true, "New Edits Made Here!");
    
  5. Go back to your terminal but now change to the following directory: "azure-iot-pcs-remote-monitoring-dotnet/services/iothub-manager/scripts/docker".

  6. To build your new docker image, type

    sh build
    

    or on Windows:

    ./build.cmd
    
  7. To verify your new image was successfully created, type

    docker images 
    

The repository should be "azureiotpcs/iothub-manager-dotnet".

Successful docker image

Tag and push the image

Before you can push your new docker image to a docker hub, Docker expects your images to be tagged. If you run into issues here, refer to our Troubleshooting section.

  1. Locate the Image ID of the docker image you created by typing:

    docker images
    
  2. To tag your image with "testing" type

    docker tag [Image ID] [docker ID]/iothub-manager-dotnet:testing 
    
  3. To push your newly tagged image to your docker hub, type

    docker push [docker ID]/iothub-manager-dotnet:testing
    
  4. Open your internet browser and go to your docker hub and sign in.

  5. You should now see your newly pushed docker image on your docker hub. Docker image in docker hub

Update your Remote Monitoring solution

You now need to update your local docker-compose.yml to pull your new docker image from your docker hub. If you run into issues here, refer to our Troubleshooting section.

  1. Go back to the terminal and change to the following directory: "azure-iot-pcs-remote-monitoring-dotnet/services/scripts/local".

  2. Open docker-compose.yml in any text editor or IDE that you like.

  3. Locate the following code:

    image: azureiotpcs/iothub-manager-dotnet:testing
    

    and change it to look like the image below and save it.

    image: [docker ID]/iothub-manager-dotnet:testing
    

View the new response status

Finish up by redeploying a local instance of the Remote Monitoring solution and viewing the new status response in Postman.

  1. Go back to your terminal and change to the following directory: "azure-iot-pcs-remote-monitoring-dotnet/scripts/local".

  2. Start your local instance of the Remote Monitoring solution by typing the following command into the terminal:

    docker-compose up
    
  3. Locate where you downloaded Postman and open it.

  4. In Postman, enter the following request in the GET: http://localhost:8080/iothubmanager/v1/status. You should now see, "Status": "OK: New Edits Made Here!".

New Edits Made Here postman message

Troubleshoot

If you're running into issues, try removing the docker images and containers on the local machine.

  1. To remove all containers, you'll first need to stop all running containers. Open your terminal and type

    docker stop $(docker ps -aq)
    docker rm $(docker ps -aq)
    
  2. To remove all images, open your terminal and type

    docker rmi $(docker images -q)
    
  3. You can check if there are any containers on the machine by typing

    docker ps -aq 
    

    If you successfully removed all containers, nothing should show up.

  4. You can check if there are any images on the machine by typing

    docker images
    

    If you successfully removed all containers, nothing should show up.

Next steps

In this tutorial, you saw how to:

  • Edit and build a microservice in the Remote Monitoring solution
  • Build a docker image
  • Push a docker image to your docker hub
  • Pull the new docker image
  • Visualize the changes

The next thing to try is customizing the device simulator microservice in the Remote Monitoring solution

For more developer information about the Remote Monitoring solution, see: