Deploying a Microservice to a Linux Computer

Objective

The objective of this tutorial is to demonstrate how to deploy an edge microservice onto a linux computer. The code for the edge microservice you're going to deploy is predefined and made available as an open source project on GitHub.

Intended Readers

The intender readers of this document are developers familiar with executing tasks for the Linux operating system at the command line. For example, the reader should be able to execute a git command set to clone source code from the Git repository.

What You'll Be Doing

In this tutorial you will learn to deploy an edge microservice from open source code. The microservice you're going to deploy will output the string, Hello World when the microservice is called using the curl command.

You're going to use git to clone the code. Then, once you have the code downloaded to the development computer, you'll compile it into an edgeEngine Image which will be used to create an edgeEngine Container. (You can read about the key concepts behind an edgeEngine Image and an edgeEngine Container here)

Then, you'll use the mimik-edge-cli tool to deploy the edgeEngine Image. Once the edgeEngine Image is deployed you'll use the mimik-edge-cli tool to deploy and start an edgeEngine Container that represents the microservice.

Technical Prerequisites

The technical prerequisites for this tutorial are as follows:

The development computer needs to be running Linux with nodejs, npm and git installed
You need to have edgeEngine and mimik-cli-tool installed on the development computer. (To learn the details of this requirement go here)
The development computer needs to have curl installed on it
You need to have a working knowledge using npm package management system
edgeEngine needs to be up and running on the development computer

Deploying a microservice on a Linux computer

Packaging the edgeEngine microservice

Step 1: In a terminal window, clone the pre-existing starter-microservice

 git clone https://github.com/edgeMicroservice/starter-microservice.git

Step 2: Navigate to the cloned code's working directory:

 cd ./starter-microservice

Step 3: Install the edgeEngine microservice's dependencies:

 npm install

Step 4: : Build the edgeEngine microservice by executing the following command:

 npm run build

Step 5: Package the edgeEngine microservice by executing the following command:

 npm run package

You'll get out similar to the following:

1: output: .generated-9vcmev9z77/repositories
2: output: .generated-9vcmev9z77/c9ebbb58695b4894964f67558e9aabad2bbf21bb542a9798e0453179bc139a3b/json
3: output: .generated-9vcmev9z77/c9ebbb58695b4894964f67558e9aabad2bbf21bb542a9798e0453179bc139a3b/VERSION
4: output: layer.tar
5: output: .generated-9vcmev9z77/bef09a33c835239d7cd812ccfc7b6a1a718126f4bc09cc596abdf5080b3ae364.json
6: output: .generated-9vcmev9z77/manifest.json
7: output: ./build/microservice-v1-1.0.0.tar

Notice that the last line of the output shown above is as follows:

 output: ./build/microservice-v1-1.0.0.tar

The command set, npm run package created the .tar file and put it in the folder, build. The file, microservice-v1-1.0.0.tar represents the packaged microservice. You'll deploy this microservice to run under edgeEngine.

Deploying the edgeEngine Image for the microservice

In order to get an edgeEngine microservice up and running you need to deploy an edgeEngine Image which will be derived from the .tar file created previously. Then, once the edgeEngine image is deployed, you'll deploy an edgeEngine Container that is based on the newly deployed edgeEngine Image.

To deploy the edgeEngine Imaged execute the following steps.

Step 1: Navigate to the build directory

 cd ./build

Step 2: Using the mimik-edge-cli tool, execute a command similar to the following:

 mimik-edge-cli image deploy --image={YOUR_IMAGE_PATH} --token={EDGE_ACCESS_TOKEN}

WHERE

{YOUR_IMAGE_PATH} is the location of the .tar file that represents the edgeEngine microservice
{EDGE_ACCESS_TOKEN} is the Access Token you generated and associated previously with the current edgeEngine installation. (You can read about creating and using an edgeEngine Access Token here).

In this instance you'll execute the following command to deploy the edgeEngine Image:

 mimik-edge-cli image deploy --image=./microservice-v1-1.0.0.tar --token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjV2RG45aF9LSHNxTkJZNVZubUxFd0VfUVNpQTkzZEYyN1FTQUVRdVl5T2sifQ.eyJzdWIiOiIyODE0MzA0ODA1MTkyNjAxNjAwIiwiZW1haWwiOiIyODE0MzA0ODA1MTkyNjAxNjAwQGV4YW1wbGUuY29tIiwiYXVkIjoiYmI2ZmJhN2QtNjMyMS00MWM1LWFjMzctMWE3YThhOWE0YWMwIiwiZXhwIjoxNjMwNzg5OTg3LCJpYXQiOjE2xxxxxfffffeeeeekkkkkImh0dHBzOi8vbWlkLm1pbWlrMzYwLmNvbSJ9.f-1wP_m_3yiq8-Qhk-QA-qgGC7QZrK3d4GAJKLL9CS3bByopdCn5U8RP3vwkmAwsm20wrw7vDhxe8MFJNhRJNededBMFQUVP7ej3vTW1fTkRbNXVHkv3eN8Bww-LddRwJaf7riTXAZ637UN7a391Dz-9OCv-RXYtSDhm3S2SCszAOlFOASGaqPM4k3IHdAVMjljk3u6wQun6wnZslU2h0vJQG6ZYTspHPtTSy_0qDOoOLhGXRUEcR-YEXd15pJKhXUMTF5ZBmSR-W7YT9Q6Rajs0-wwPhoZwjQhgAB-4vaDutM8Mhu18L97b4kHrEC8wvQ5XszkA0-nkoUgKQZhv8Q

Upon executing the command described above, you'll get output similar to the following:

1: created: 1617907116
2: digest:  sha265:e38a0314ea4bca42802bbc315637d9db9251158494e85ece4c0d789e2ab0b191
3: id:      79279c04-8945-4141-8b52-2cb92b78cf43-microservice-v1
4: name:    microservice-v1
5: size:    75855
6: status:  successfully deployed

Step 3: Copy the value for name: from the successful response output and save it. You will need this value in the future. (In this case, the value to save is microservice-v1.)

You have created the edgeEngine Image for the starter-microservice.

Deploying the edgeEngine Container

To the deploy an edgeEngine Container based on the edgeEngine Image you created previously, take the following steps.

Step 1: Navigate to the root of the working directory, /starter-microservice

You'll see the file, start.json. This file has the information that the mimik-edge-cli tool needs to deploy the edgeEngine Container. You're going to add the necessary information to the file, start.json.

Step 2: Open the file, start.json in a text editor. In this case we'll use vi.

vi start.json

You'll the following output.

1: {
2:   "name": "{{containerName}}",
3:   "image": "{{imageName}}",
4:   "env": {
5:     "MCM.BASE_API_PATH": "{{YOUR_PATH}}",
6:     "MCM.WEBSOCKET_SUPPORT": "false"
7:   }
8: }

WHERE

{{containerName}} is the name you'll assign to the edgeEngine container
{{imageName}} is the name of thee edgeEngine Image defined in the output from the mimik-edge-cli image deploy command set.
{{YOUR_PATH}} is the custom defined path that will be assigned to the base route of the edgeEngine microservice

Step 3: Replace {{containerName}} & {{imageName}} with the name: value you copied earlier from the successful deployment response.

Step 4: Change the value associated with MCM.WEBSOCKET_SUPPORT to true, like so:

 "MCM.WEBSOCKET_SUPPORT": "true",

Step 5: In this case, the content of start.json is as follows:\

1: }
2:   "name": "microservice-v1",
3:   "image": "microservice-v1",
4:   "env": {
5:     "MCM.BASE_API_PATH": "/sample/v1/",
6:     "MCM.WEBSOCKET_SUPPORT": "true"
7:   }
8: }

Step 6: Save the file, start.json in the vi editor.

Step 7: Start the edgeContainer of our microservice using the mimik-edge-cli tool and our start.json file as the payload. Run command below in terminal window. Replace {EDGE_ACCESS_TOKEN} with your edge Access Token:

 mimik-edge-cli container deploy --payload start.json --token={EDGE_ACCESS_TOKEN}

You'll get output similar to the following:

1: created: 1620341668342
2: env: 
3:   MCM.BASE_API_PATH:     /bb6fba7d-6321-41c5-ac37-1a7a8a9a4ac0/sample/v1
4:   MCM.WEBSOCKET_SUPPORT: true
5: id:      bb6fba7d-6321-41c5-ac37-1a7a8a9a4ac0-microservice-v1-1.0.0.tar
6: image:   microservice-v1
7: imageId: bb6fba7d-6321-41c5-ac37-1a7a8a9a4ac0-microservice-v1
8: name:    microservice-v1-1.0.0.tar
9: state:   started

Step 8: Copy the value for MCM.BASE_API_PATH: to a safe place. MCM.BASE_API_PATH is the route to the edgeEngine microservice that you'll append to path of the microservice at localhost:8083

Running the edgeEngine microservice

Step 1: To run the edgeEngine microservice, you'll use curl to make an HTTP request using the following path�format:

 curl http://localhost:8083/<MCM.BASE_API_PATH>/

WHERE

<MCM.BASE_API_PATH> is the route to the edgeEngine microservice.

Step 2: In this case, we'll replace <MCM.BASE_API_PATH> with the value we copied earlier from the successful deployment of the edgeEngine container, like so:

 curl http://localhost:8083/bb6fba7d-6321-41c5-ac37-1a7a8a9a4ac0/sample/v1/

NOTE! Don't forget to append the character / to the end of the path to the edgeEngine microservice.

Upon successful execution of the curl command to call the microservice you'll get output similar to the following:

 Hello World

Congratulations! You've built an edgeEngine Image and deployed the Image and an edgeEngine Container using the mimik-edge-cli tool.

Creating a Simple Android Application that Uses an edge microservice

Getting edgeEngine Up and Running on Raspberry Pi

Disclaimer