Link Search Menu Expand Document

Install via Compose Files bundle

The simplest way to install the NuvlaEdge Engine software on an edge device is to follow this installation method. If you are looking for an automated and/or scalable method, please visit the USB Stick page.

  1. login into
  2. from the edge panel, add a new nuvlabox, and either
    1. download the compose files from Nuvla, or
    2. copy the NuvlaEdge UUID, and on your device, run export NUVLABOX_UUID=<UUID you copied> and download the compose files from here
  3. copy the given docker-compose -p nuvlabox ... command from Nuvla, and on your device, in the same folder as the compose files from step 2., paste and run the command
  4. after a few seconds, you should see your new NuvlaEdge edge device becoming green in Nuvla, and if you run docker ps in your device, you should find (amongst others) something like:
     9ca2441396d0   eclipse-mosquitto:1.6.12                    "sh -c 'sleep 10 && …"   3 days ago    Up 3 days             1883/tcp                                    data-gateway.1.pgukfkffcn6ahooafaovzn6eq
     072743d2229a   nuvladev/agent:master                       "./"               3 weeks ago   Up 3 days (healthy)>80/tcp                      nuvlabox_agent_1
     478817a492f2   nuvladev/compute-api:master                 "./"               3 weeks ago   Up 3 days (healthy)>5000/tcp, :::5000->5000/tcp   compute-api
     7d71e78eaf2b   nuvlabox/vpn-client:1.0.0                   "./"    3 weeks ago   Up 3 days                                                         vpn-client
     c2ef3b427eae   nuvlabox/system-manager:2.1.5               "./"               3 weeks ago   Up 3 days (healthy)>3636/tcp                    nuvlabox_system-manager_1
     d561b3bbdc7f   nuvla/job-lite:2.18.0                       "/app/"          3 weeks ago   Up 3 days (Paused)                                                nuvlabox-job-engine-lite
     f92b151430e3   nuvlabox/security:1.2.0                     "./"               3 weeks ago   Up 3 days                                                         nuvlabox_security_1
     24226c6f802c   nuvlabox/peripheral-manager-network:1.1.4   "python"      3 weeks ago   Up 3 days                                                         nuvlabox_peripheral-manager-network_1
     abd12f371adb   nuvlabox/peripheral-manager-usb:2.0.4       "peripheral-manager-…"   3 weeks ago   Up 3 days                                                         nuvlabox_peripheral-manager-usb_1
     3b9114d398cd   nuvlabox/on-stop:1.0.1                      "./ pause"         3 weeks ago   Up 3 days (Paused)                                                nuvlabox-on-stop

If this is not the case, please consult the Troubleshooting page.

Halt the NuvlaEdge

In an edge environment, halting your devices is sometimes necessary. Halting does not mean you will delete the NuvlaEdge nor its local data, but rather stop its services temporarily.

When rebooting your edge device, the NuvlaEdge will resume by itself, alongside your device’s Docker service, so you don’t need to do anything.

When manually halting the NuvlaEdge, you must find (or re-download) the original compose files in your edge device, and run docker-compose -p nuvlabox <compose files> down. Then to resume, simply run docker-compose -p nuvlabox <compose files> up -d. Please note that <compose files> must correspond to the list of compose files you have used during the first installation. In our case, looking at the docker ps output from above, <compose files> should be replaced by -f docker-compose.yml -f docker-compose.usb.yml -f (e.g., to halt the NuvlaEdge we’d then run docker-compose -p nuvlabox -f docker-compose.yml -f docker-compose.usb.yml -f down)

Upgrade/Downgrade the NuvlaEdge

NOTE: automated migrations are not currently supported accros major versions (e.g. v1 to v2). If you must upgrade from a NuvlaEdge Engine v1 to v2, or vice versa, please contact us.

From Nuvla

The NEE can be updated directly from Nuvla. On the user interface, in each NuvlaEdge panel, you’ll find an action called “Update NuvlaEdge” (as depicted below)


By clicking on it, you can specify which version of the NuvlaEdge Engine you want to upgrade/downgrade to. Please note that this is an asynchronous action that can take a few minutes, depending on your edge device’s network.


You can also SSH into your edge device, and find the original project folder where you saved your Compose files.

If you’ve initially installed the NuvlaEdge Engine according to the instructions above, then you should see all of its components by running:

$ docker-compose -p nuvlabox -f docker-compose.yml -f docker-compose.usb.yml -f ps

You should get something like this:

                 Name                            Command              State                        Ports                  
compute-api                               ./                 Up (healthy)>5000/tcp,:::5000->5000/tcp
deployment_agent_1                        ./                 Up (healthy)>80/tcp                  
deployment_peripheral-manager-network_1   python        Up                                                     
deployment_peripheral-manager-usb_1       peripheral-manager-usb   Up                                                     
deployment_security_1                     ./                 Up                                                     
deployment_system-manager_1               ./                 Up (healthy)>3636/tcp                
nuvlabox-job-engine-lite                  /app/            Paused                                                 
nuvlabox-on-stop                          ./ pause           Paused                                                 
vpn-client                                ./      Up       
  • Cherry picking a NuvlaEdge Engine component to be upgraded/downgraded: let’s say, as an example, that we want to upgrade the NuvlaEdge Engine’s Agent component. Then:
    1. open the docker-compose.yml file and find the agent service
    2. replace the corresponding Docker image tag (nuvlabox/agent:X.Y.Z) with the target version number. Save the file
    3. execute docker-compose -p nuvlabox -f docker-compose.yml -f docker-compose.usb.yml -f up -d agent

    This is valid for any NuvlaEdge Engine component

  • Upgrade/Downgrade the entire NuvlaEdge Engine installation: let’s say we want to upgrade your existing NuvlaEdge Engine installation to the latest release in GitHub. Then:
    1. halt the NuvlaEdge, as explained above
    2. backup the Compose files from the project folder you are in into a different folder (just in case you need to rollback)
    3. download the Compose files from the target release in GitHub
    4. resume the NuvlaEdge Engine installation by running docker-compose -p nuvlabox -f docker-compose.yml -f docker-compose.usb.yml -f up -d
      1. if your goal is also to add a new peripheral manager to the existing NuvlaEdge, then simply add its compose file to this command. For example, to also start managing Bluetooth peripherals, run docker-compose -p nuvlabox -f docker-compose.yml -f docker-compose.usb.yml -f -f docker-compose.bluetooth.yml up -d
      2. if your goal is also to remove an existing peripheral manager from the NuvlaEdge installation, then remove its compose file from this command, and add --remove-orphans. For example, to also stop managing Network peripherals, run docker-compose -p nuvlabox -f docker-compose.yml -f docker-compose.usb.yml up -d --remove-orphans

Uninstall the NuvlaEdge

NOTE: this action is permanent, unless you keep a copy of the NuvlaEdge’s API Key/Secret credential. This credential can be found at /var/lib/docker/volumes/nuvlabox_nuvlabox-db/_data/.activated.

To completely and permanently uninstall the NuvlaEdge from your edge device, simply find your original compose files in the edge device, and run docker-compose -p nuvlabox down -v. The -v will remove the NuvlaEdge local data volume, so all of its data will be lost.

To re-install a new NuvlaEdge from scratch in the same edge device, you’ll need to go through the installation from the start of this page. If you have the API Key/Secret from the NuvlaEdge you’ve just deleted, then you also have the choice to recover it, even from a different device, via the configuration variables NUVLABOX_API_KEY and NUVLABOX_API_SECRET. See the NuvlaEdge Engine configuration for more details.

Table of contents