Quickstart (Azure)

Estimated time: 10-20 minutes

Try out Ferry in this quickstart by deploying a “hello world” script to a device that supports Ubuntu and Debian Linux systems. Ferry allows you to easily & securely deploy any software application (i.e. scripts, data pipelines, ML models) on physical devices. For this quickstart, we recommend that you use our hosted cloud account on Azure to see how easy it is to use Ferry for software deployments.

In this quickstart, you’ll learn how to:

• Set up Node Groups (i.e. sets of devices called Nodes)

• Register & provision a Node with Ferry using the Azure IoT Edge runtime

• Create & publish a Component for our hello_world application

• Deploy the Component to your device

Prerequisites

• A hardware device for Ferry to be able to deploy code to with:

  • System requirements: able to support Ubuntu / Debian Linux distributions.

  • An Internet connection for the device (most easily done with Ethernet, but Ferry also works with WiFi enabled devices).

  • SSH access to your hardware device.

  • The Linux user who runs the script must have permissions to run as sudo

We recommend Rapsberry Pi 2 onwards as suitable hardware targets to test Ferry on.

Setting up your Ferry account

• Create an account on Ferry by signing up here (opens in a new tab).

• Create your first Organization.

• When prompted to create a Cloud Account, select “Ferry Azure Account - for testing only”.

  • This allows you to be able to use Ferry’s Azure account for deploying code to your hardware device, which we offer to users for trying Ferry out. It is not designed to be used for production purposes!

  • You can link your own Cloud Account at any time within the Ferry dashboard

• Name your first Workspace

• Confirm the initialization of Cloud Account policies on your Workspace.

  • This allows Ferry to be able to interface with the IoT and cloud services with cloud providers for registering devices and deploying software applications to them

Setting up a Node Group

• In the navigation panel, select “Node Groups”.

• Create a “Node Group”.

  • Node Groups are a collection of hardware devices, called “Nodes”.

Provision your first device (aka ‘Node’)

• In the navigation panel, select “Nodes”.

• Create & name a “Node” for your hardware device. Specify that it belongs to the Node Group that you just created.

  • A Node in Ferry belongs to one Node Group at a time.

• When your Node is created in Ferry, it is given a one-time token. This is so Ferry can securely provision the Node with your Cloud Account and install the required software for future deployments.

• SSH into your hardware device (which should have an Internet connection), and run the following commands from the root directory. In this example we are assume you have an Ubuntu 22.04 OS on your device:

  • curl https://github.com/deployferry-io/installer/azure/ubuntu-22.04.git

  • cd installer

  • sudo sh install.sh -k <<YOUR_ONE_TIME_TOKEN>>

These commands will first download the installation package from Ferry for Azure, ensure that the Ferry installation script can be run, and then proceed to authenticate with Ferry to download the runtime for the hardware device (in this case Azure IoT Edge).

This step will take a few minutes to complete on your hardware device, depending on your device’s internet connectivity and memory bandwidth. Depending on the installer, you might be prompted to continue as it installs AWS IoT Edge on the device.

Behind the scenes, Ferry automates and handles: a) ensuring that the device has the right run-time and packages to run your applications; and b) ensures that your Node has all the right permissions and certificates to be able to communicate securely with your cloud account. You can read more about how we do that here.

If for whatever reason, the installation fails and the one-time token is no longer valid, you can refresh the token within the Node details screen.

Now your Node is ready to have applications deployed to it!

Publish your first Component

Now it’s time to create your first Component which you can deploy to your Node:

• Navigate to the Components screen

• Select “Create New Component”

• You’ll be navigated to the Ferry Marketplace screen. Select “Python Azure IoT Edge Component” → “Use template”. Give your component a name

• Then you’ll be navigated to the Component Details screen for your component. Go to the Versions tab and create a new version 1.0.0

You’ll be navigated to Ferry’s internal IDE for Component Versions. In Ferry, we version all Components so you can seamlessly rollback and deploy different versions of your software with ease and at any time.

Ferry provides a IDE for developers to be able to quickly write code, and deploy it to their devices. Very useful when you are trying to get data off devices or want to test code on a work-bench before deploying to production!

In the IDE, copy & paste the following code into main.py

import time

while True:
    print("Hello world!")
    time.sleep(5)

• Select “Save” to save the changes to the file

  • You can save files to return to them at any time

• Select “Publish” to commit the Component Version

  • Once a Component Version is published, it can’t be edited further. You can easily create a new Component Version by selecting “Duplicate” which will copy all files from any version you select to a new Component Version.

Behind the scenes, Ferry packages the files and stores them in the cloud account (in the case of Azure, a Blob Storage bucket).

Create your first Deployment

• On the Component Version you just published, select Deploy.

• You’ll be prompted to create a new deployment and give your a deployment a name.

• On the Deployment details screen:

  • Add your Component to the Deployment (”Deployment Components”). This will link your application to this deployment.

  • Add your Node Group to the Deployment (”Deployment Targets”). This will link your node group (and associated devices) as a target for this deployment.

  • Both your Component and Node Group will have state ‘pending deployed’

  • Select the “Deploy” option to initiate the deployment. If successful, the Component and Node Group will be updated to ‘deployed’.

And that’s it! Ferry will package the files stored in the cloud account, and deploy them your selected cloud account’s IoT services directly to your hardware device. Ferry provides advanced functionality for creating and editing existing Deployments - find out more about Smart Deployments here.

It can take a few minutes for the Deployment to be executed on the device. As long as your Node has Internet connectivity, it will periodically poll your cloud provider for new deployments or changes to existing deployments.

See the results

• With SSH access, you can see the deployment in action:

  • On your device, navigate to the /installer directory

  • Access root user via sudo su

  • Run docker ps to get the Docker processes on your device

  • Find the ID of your component, and run docker logs -f [COMPONENT_CONTAINER_ID]

  • You should be able to see repeated log entries that specify stdout as “Hello world!”