Skip to content

The Basics

This tutorial demonstrates the basics of application management and node management on a single node using the Edge Builder CLI. The following topics are covered:

Initialise the Edge Builder server components and CLI

To initialize the Edge Builder server components and CLI, complete the following steps:

  1. Set up the environment as described in Tutorials Setup

  2. SSH into the master node: 

    vagrant ssh master

  3. Start the Edge Builder server components using the following command: 

    sudo edgebuilder-server up -a 192.168.56.10
    When the server components are up, you should see all server components up and running via the docker ps command: 
    vagrant@master:~$ docker ps

CONTAINER ID   IMAGE                                    COMMAND                  CREATED          STATUS          PORTS                                                                                                                                                     NAMES
54216df43569   iotechsys/dev-eb-controller:1.2.0.dev    "./entrypoint.sh"        19 seconds ago   Up 16 seconds   0.0.0.0:8085->8085/tcp, :::8085->8085/tcp, 0.0.0.0:50000-50100->50000-50100/tcp, :::50000-50100->50000-50100/tcp, 0.0.0.0:1022->22/tcp, :::1022->22/tcp   eb-controller
28e962d77a00   chronograf:1.8.8-alpine                  "./custom-entrypoint…"   21 seconds ago   Up 19 seconds   0.0.0.0:8888->8888/tcp, :::8888->8888/tcp                                                                                                                 eb-chronograf
706d2b19acf4   postgres:alpine                          "./entrypoint.sh"        24 seconds ago   Up 21 seconds   5432/tcp                                                                                                                                                  eb-db
83f4b4298be4   influxdb:1.8.1-alpine                    "./custom-entrypoint…"   24 seconds ago   Up 21 seconds   0.0.0.0:8086->8086/tcp, :::8086->8086/tcp                                                                                                                 eb-influxdb
c2981b5cbce7   portainer/portainer-ce:2.1.0-alpine      "/portainer -H unix:…"   24 seconds ago   Up 20 seconds   0.0.0.0:8000->8000/tcp, :::8000->8000/tcp, 0.0.0.0:9000->9000/tcp, :::9000->9000/tcp                                                                      eb-portainer
5d4110072447   iotechsys/dev-eb-redis:1.2.0.dev         "redis-server /etc/r…"   24 seconds ago   Up 20 seconds   6379/tcp                                                                                                                                                  eb-redis
64901e67177b   iotechsys/dev-eb-webssh:1.2.0.dev        "wssh --address=0.0.…"   24 seconds ago   Up 21 seconds   0.0.0.0:8989->8989/tcp, :::8989->8989/tcp                                                                                                                 eb-webssh
34811b289512   grafana/grafana:7.4.2                    "/run.sh"                24 seconds ago   Up 21 seconds   0.0.0.0:3000->3000/tcp, :::3000->3000/tcp                                                                                                                 eb-grafana
ac79f2182e86   iotechsys/dev-eb-salt-master:1.2.0.dev   "/bin/sh -c 'sed -i …"   24 seconds ago   Up 20 seconds   0.0.0.0:4505-4506->4505-4506/tcp, :::4505-4506->4505-4506/tcp, 0.0.0.0:8099->8099/tcp, :::8099->8099/tcp                                                  eb-salt-master
6583228fa467   kapacitor:1.5-alpine                     "/entrypoint.sh kapa…"   24 seconds ago   Up 21 seconds   9092/tcp                                                                                                                                                  eb-kapacitor
6659e040296e   vault:1.7.1                              "./entrypoint.sh"        24 seconds ago   Up 21 seconds   8200/tcp                                                                                                                                                  eb-vault

  4. Log in to Edge Builder with the default user credentials using the following command: 

    edgebuilder-cli user login -u iotech -p EdgeBuilder123 -c "http://192.168.56.10:8085"
    You should see the following INFO message: 
    INFO: User "iotech" logged in successfully

  5. Confirm that you have a valid license in the Vagrant project directory (edgebuilder-vagrant)

  6. Add the license using the following command: 
    edgebuilder-cli license add -l DemoLicense -f /vagrant/EdgeBuilder_test_Evaluation.lic
    You should see the output similar to that shown below: 
    INFO: License added successfully
+-------------+--------------------------------------+---------------------------------+-----------+-----------+
| NAME        | ID                                   | FILENAME                        | MAX NODES | EXPIRY    |
+-------------+--------------------------------------+---------------------------------+-----------+-----------+
| DemoLicense | b65c2ba0-c78b-4031-aaf4-cc030d3d763d | EdgeBuilder_test_Evaluation.lic | 100       | unlimited |
+-------------+--------------------------------------+---------------------------------+-----------+-----------+
INFO: Viewing 1 result(s)

Add a node

In this section of the tutorial, we will add a node to Edge Builder. It is accessible on 192.168.56.11.

To add an edge node, complete the following steps:

  1. Confirm that the example node configuration file is avaliable using the cat command: 

    cat /vagrant/examples/single-node-config.json
    Expected output: 
    {
  "NodeConfig": [
      {
          "name": "node1",
          "description": "virtual node 1",
          "nodeaddress": "192.168.56.11",
          "username" : "vagrant",
          "password" : "vagrant",
          "serveraddress": "192.168.56.10",
          "labels" : ["label1", "label2"]
      }
  ]
}

  2. Add the node to Edge Builder using the following command: 

     edgebuilder-cli node add -f /vagrant/examples/single-node-config.json
    Expected output: 
    INFO: SSH Node(s) added successfully:
+-------+--------------------------------------+
| NODE  | ID                                   |
+-------+--------------------------------------+
| node1 | e01c540b-fa87-4721-b38c-5f0109210381 |
+-------+--------------------------------------+
INFO: Viewing 1 result(s)

  3. Confirm that the node has been added using the following command: 

    edgebuilder-cli node view --all
    Expected output: 
    INFO: Finding all nodes...
INFO: *** Node View Results ***
+-------+----------+------------+--------------+----------------+--------------------------------------+
| NAME  |  STATUS  | DEBUG MODE | METRICS MODE | DESCRIPTION    | ID                                   |
+-------+----------+------------+--------------+----------------+--------------------------------------+
| node1 | Deploying| Off        | Local        | virtual node 1 | e01c540b-fa87-4721-b38c-5f0109210381 |
+-------+----------+------------+--------------+----------------+--------------------------------------+
INFO: Viewing 1 result(s)

    Note

    • The node status is initially shown as Deploying. After a few minutes, you can re-issue the command and the status will have changed to Up
    • You can also use the watch command with the node view above to automatically track the status changes

Create an app definition

In this section of the tutorial, we create an app definition which will be used to create and deploy apps.

  1. Confirm that the example app definition configuration file is available using the cat command: 

    cat /vagrant/examples/app-def-config.json
    Expected output: 
    {
  "AppDefinitionConfig": [
    {
      "Name": "SimpleWebServer",
      "Description": "Node docker-compose appDefinition",
      "FilePath": "/vagrant/examples/docker-compose.yaml",
      "Type": "docker-compose",
      "Labels": ["appLabel1","appLabel2"]
    }
  ]
}

  2. Confirm that the example docker compose file, which defines a simple web server that prints a greeting, is available using the following command: 

    cat /vagrant/examples/docker-compose.yaml
    Expected output: 
    version: "3"

services:
simple-webserver:
image: nginx
ports:
    - 55555:80
volumes:
    - /home/vagrant/src:/usr/share/nginx/html

  3. Add the app definition to Edge Builder using the following command: 

     edgebuilder-cli appDefinition add -f /vagrant/examples/app-def-config.json
    Expected output: 
    INFO: AppDefinition(s) added successfully:
+-----------------+--------------------------------------+----------------------+
| NAME            | ID                                   | LABELS               |
+-----------------+--------------------------------------+----------------------+
| SimpleWebServer | e9b9dc0d-2760-4ee3-b36a-23148dd3bf7e | appLabel1, appLabel2 |
+-----------------+--------------------------------------+----------------------+
INFO: Viewing 1 result(s)

  4. Confirm that the app definition has been added using the following command: 

    edgebuilder-cli appDefinition view --all
    Expected output: 
    INFO: Finding all appDefinitions...
INFO: *** AppDefinition View Results ***
+-----------------+--------------------------------------+-----------------------------------+----------------+----------------------+
| NAME            | ID                                   | DESCRIPTION                       | TYPE           | LABELS               |
+-----------------+--------------------------------------+-----------------------------------+----------------+----------------------+
| SimpleWebServer | e9b9dc0d-2760-4ee3-b36a-23148dd3bf7e | Node docker-compose appDefinition | docker-compose | appLabel2, appLabel1 |
+-----------------+--------------------------------------+-----------------------------------+----------------+----------------------+
INFO: Viewing 1 result(s)

Deploy an app on a node

In this section of the tutorial, you deploy the simple web server edgebuilder-cli node add -f /vagrant/examples/single-node-config.json server app that we defined in the previous part of this tutorial.

To deploy the app, complete the following steps:

  1. Create the app on the node using the following command: 

    edgebuilder-cli app create -d SimpleWebServer -n node1
    Expected output: 
    INFO: Creating app(s):
+------------------------------------------------------+--------------------------------------+----------+--------------------------------------+--------+
| APP NAME                                             | APP ID                               | STATUS   | NODE ID                              | LABELS |
+------------------------------------------------------+--------------------------------------+----------+--------------------------------------+--------+
| SimpleWebServer_f9c71531-5353-4cdc-a4f1-bb1958257f88 | f9c71531-5353-4cdc-a4f1-bb1958257f88 | Creating | d38f0673-1bba-4130-8f19-6f71c8ba5ac4 |        |
+------------------------------------------------------+--------------------------------------+----------+--------------------------------------+--------+
INFO: Viewing 1 result(s)

  2. Confirm that the app is in the created state using the following command: 

    edgebuilder-cli app view --all
    Expected output: 
    INFO: Finding all apps...
INFO: *** App View Results ***
+------------------------------------------------------+---------+--------------------------------------+-----------------+-------+--------+
| NAME                                                 | STATUS  | ID                                   | APP_DEFINITION  | NODE  | LABELS |
+------------------------------------------------------+---------+--------------------------------------+-----------------+-------+--------+
| SimpleWebServer_f9c71531-5353-4cdc-a4f1-bb1958257f88 | Created | f9c71531-5353-4cdc-a4f1-bb1958257f88 | SimpleWebServer | node1 |        |
+------------------------------------------------------+---------+--------------------------------------+-----------------+-------+--------+
INFO: Viewing 1 result(s)

    Note

    • The app status is initially shown as Creating. After a few seconds, you can re-issue the command and the status will have changed to Created
    • You can also use the watch command with the app view above to automatically track the status changes

  3. Start the app using the following command, where <appname/id> is the ID of your app: 

    edgebuilder-cli app start -a <appname/id>
    Expected Output: 
    INFO: Finding apps: ["66b935ae-93d8-4e98-9452-fd48c36661a4"]
INFO: Starting 1 app(s)

    Note

    • You can find the ID of your app using the app view --all command.

  4. To view the status of the app we deployed, use the app view command again 

    edgebuilder-cli app view --all
    Expected output: 
    INFO: Finding all apps...
INFO: *** App View Results ***
+------------------------------------------------------+---------+--------------------------------------+-----------------+-------+--------+
| NAME                                                 | STATUS  | ID                                   | APP_DEFINITION  | NODE  | LABELS |
+------------------------------------------------------+---------+--------------------------------------+-----------------+-------+--------+
| SimpleWebServer_f9c71531-5353-4cdc-a4f1-bb1958257f88 | Running | f9c71531-5353-4cdc-a4f1-bb1958257f88 | SimpleWebServer | node1 |        |
+------------------------------------------------------+---------+--------------------------------------+-----------------+-------+--------+
INFO: Viewing 1 result(s)

    Note

    • It might take a few seconds for the status of the app to move from Starting to Running

  5. With the app running it can be verified via this curl command: 

    curl http://192.168.56.11:55555
    If the app is running, you should see the following: 
    I am edge node1

Restart and Stop an app

In this section of the tutorial, we illustrate restarting the app and stopping it

  • Restart the app using the following command, where <appname/id> is the ID of your app: 

    edgebuilder-cli app restart -a <appname/id>
    Expected output: 
    INFO: Finding apps: ["66b935ae-93d8-4e98-9452-fd48c36661a4"]
INFO: Restarting 1 app(s)

  • Confirm that the app has re-started using the following command: 

    edgebuilder-cli app view --all
    Expected output: 
    INFO: Finding all apps...
INFO: *** App View Results ***
+------------------------------------------------------+---------+--------------------------------------+-----------------+-------+--------+
| NAME                                                 | STATUS  | ID                                   | APP_DEFINITION  | NODE  | LABELS |
+------------------------------------------------------+---------+--------------------------------------+-----------------+-------+--------+
| SimpleWebServer_f9c71531-5353-4cdc-a4f1-bb1958257f88 | Running | f9c71531-5353-4cdc-a4f1-bb1958257f88 | SimpleWebServer | node1 |        |
+------------------------------------------------------+---------+--------------------------------------+-----------------+-------+--------+
INFO: Viewing 1 result(s)

  • Stop the app using the following command, where <appname/id> is the ID of your app: 

    edgebuilder-cli app stop -a <appname/id>
    Expected output: 
    INFO: Finding apps: ["66b935ae-93d8-4e98-9452-fd48c36661a4"]
INFO: Stopping 1 app(s)

  • Confirm that the app has stopped using the following command: 

    edgebuilder-cli app view --all
    You should see the following output with the app STATUS set to Stopped : 
    INFO: Finding all apps...
INFO: *** App View Results ***
+------------------------------------------------------+---------+--------------------------------------+-----------------+-------+--------+
| NAME                                                 | STATUS  | ID                                   | APP_DEFINITION  | NODE  | LABELS |
+------------------------------------------------------+---------+--------------------------------------+-----------------+-------+--------+
| SimpleWebServer_f9c71531-5353-4cdc-a4f1-bb1958257f88 | Stopped | f9c71531-5353-4cdc-a4f1-bb1958257f88 | SimpleWebServer | node1 |        |
+------------------------------------------------------+---------+--------------------------------------+-----------------+-------+--------+
INFO: Viewing 1 result(s)

Remove an app from a node

In this section of the tutorial, you remove the simple web server app from the edge node.

To remove an app from an edge node, complete the following steps:

  1. Remove the app from the node using the following command, where <app_id> is the ID of your app: 

    edgebuilder-cli app rm -a <app_id> -y
    Expected output: 
    INFO: Processing apps: ["7ac6a51b-4e18-43c3-82e3-99c6a0ec1be5"]
INFO: Attempting to remove 1 app(s)
INFO: Removal request for 1 app(s) accepted for processing by Edge Builder. Use 'app view' command to get updated status

  2. Confirm that the app is removed successfully by trying to view the app 

    edgebuilder-cli app view -a <app_id>
    Expected output: 
    WARN: app "7ac6a51b-4e18-43c3-82e3-99c6a0ec1be5" not found
WARN: 0 results to view

Remove a node

To remove an edge node, complete the following steps:

  1. Remove the edge node node1 using the following command: 

    edgebuilder-cli node rm -n node1 -y
    Expected output: 
    INFO: Processing nodes: ["node1"]
INFO: Attempting to remove 1 node(s)
INFO: Removal request for 1 node(s) accepted for processing by Edge Builder. Use 'node view' command to get updated status

  2. Confirm that the node has been removed using the following command: 

    edgebuilder-cli node view -n node1
    Expected output: 
    INFO: Finding nodes: ["node1"]
WARN: node "node1" not found
INFO: 0 results to view