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.