6. Tutorial: Deploying FactoryTX

This article contains the following sections:

Introduction

There are two supported methods for FTX edge deployment:

  • An edge industrial PC appliance (the Intel NUC)
  • A Virtual Machine file in VMDK (Virtual Machine Disk) or QEMU format for use with Oracle VirtualBox

The Resin.io platform is recommended because it provides infrastructure for managing edge devices. It includes an operating system that is off-limits so you cannot brick your device, and lets you deploy arbitrary containers/applications on top of that operating system. It also handles phoning home for updates, the compression of images for fast remote upgrades, VPN support if you SSH in to a given device, and a Web-based portal for device management, version control, etc.

The graphic below shows how FTX can be installed on edge devices to pull data from the factory floor and transmit it to Sight Machine via various cloud environments, using the Resin.io platform to manage the process.

FactoryTX Installation Flow

Follow the steps in the next sections to complete the FactoryTX deployment.

For more information about deploying FactoryTX on an edge device or running it on a customer network, see  Appendix: FactoryTX Configuration Reference.

Determining the Edge Device Target

You must specify if the target is an appliance or a VM. This is based solely on the customer engagement. You need to determine this up front before continuing with the deployment.

Logging in to Resin

Browse to https://resin.io/. You can log in using a free account that you create, or by linking to your Google or GitHub account. We recommend that each site create a user that individuals can be added to as collaborators.

Creating an Application

Applications are specific to a given customer and deployment target (VM vs. NUC).

To create an application:

  1. When you log in to Resin, the Applications page displays all running applications for that Resin.io instance, including their current status (offline, updating, live, etc.).
    If you do not have any current applications, the Applications page will be empty.
  2. In the upper-left corner, in the Device Type drop-down menu, select one of the following endpoints:
  • NUC
  • QEMU X86 64bit
  1. Under Application Name, type a name. The general naming scheme for an application will be: customerRepoDevice. Spaces and special characters are not allowed, so camelCase is preferred. For example: FtxQemu
  2. Click Create New Application.

Adding a New Device

After you create an application, you must create a device running that application.

To add a new device:

  1. On your new application page, click Add Device.
  2. On the Add a New Device page, click Download resinOS to get a prebuilt disk image that will phone home and register the edge device that you selected.
  3. Use the form to configure and download resinOS for your new device.

Running on an Intel NUC

NOTE: This procedure requires a USB drive.

You will need to burn the image file that you downloaded from resinOS to a USB drive so you can use it on the NUC. To do this, you should use Etcher, an image burner tool by Resin.io, to flash installable images onto USB.

To run on a Intel NUC:

  1. Download and install Etcher at http://etcher.io, and then follow the steps in the Etcher interface to burn the resinOS image (i.e., <your_image_filename.img>) onto a USB drive.
  2. Insert the USB key and power up the NUC.
  3. On the Add a New Device page, follow the instructions.

  1. If resinOS cannot boot from the correct boot partition, reset the BIOS to the default, and then check the following items in the BIOS:
  • Boot option:
  • Hard drive BBS priority:
  • Boot Override: Select UEFI: USB or USB drive for first booting time.
  1. Go to the Resin.io Applications page and verify that the new NUC device is added. You should see an image similar to:
  2. When the device is powered down, and on the Applications page the Status is Post Provisioning, remove the USB drive and press the NUC power button.
  3. The status will change to Online or Downloading. Wait for the status to be Online.

Running a Virtual Device Using Oracle VirtualBox

You will need to convert the image file into a format that Oracle VirtualBox can use.

To run a virtual device using Oracle VirtualBox:

  1. Use the .img file and convert it to VMDK:
    qemu-img convert <your_image_filename.img> -O vdi outputImage.vdi
  2. Resize the .vdi file to use appropriate space:
    vboxmanage modifyhd <your_image_filename.vdi> --resize 2288

    NOTE: The last parameter is space in MB; this is ~2GB.
  3. Start Oracle VirtualBox.
  4. Follow the instructions and use Linux Ubuntu 64-bit.
  5. Set the memory size to 1024MB.
  6. Use the existing .vdi file as your virtual hard disk.
  7. Go to theResio.io Applications page and verify that the new VM device is added.

Running a Virtual Device Using QEMU

If you need to install QEMU for your platform, go here for more information: https://www.qemu.org/download/

QEMU is a lightweight virtualization service. We recommend QEMU for the development or testing of FactoryTX, but for production deployments, we recommend using VMWare or VirtualBox.

To run a virtual device using QEMU:

  1. Install qemu-kvm and Virtual Machine Manager (AKA, virt-manager), the tool that allows you to use a graphical interface to interact with KVM. Go to: https://help.ubuntu.com/community/KVM/VirtManager
  2. In virt-manager, click Import Existing Disk Image > Browse > Browse Local to locate the Resin *.img file (raw file format).
  3. Accept the default memory and CPU settings.
  4. Define the VM name, and then click Finish.
  5. Go to the Resin.io Applications page and verify that the new VM device is added.

Setting Up a FactoryTX Network Configuration

FactoryTX will be easiest to deploy when you are using DHCP (automatic network configuration) over a wired Ethernet connection and you have access an outbound Internet connection. If this is the case, you can use the same deployment image/USB to deploy multiple devices.

If you are running a Virtual Machine, default network settings are usually sufficient, assuming that the host OS is already on the correct network. You can make any advanced or specific settings within the VM manager (e.g., VirtualBox or VMWare). In order to connect to the Web interface from outside of the host system, you may need to create a “bridged” network to the VM.

If you have other needs, such as using static IPs, configuring WiFi, or using an outbound proxy, we recommend consulting the Resin.io documentation directly: https://docs.resin.io/


Loading the FactoryTX Software into Resin for Deployment

On your local machine, you need to download the code base for the FactoryTX code repository (i.e., github.com/sightmachine/factorytx2).

This will require the open source version control tool Git. Our instructions are for the command line tool, but you may prefer a GUI. If you need to install Git on your local system, visit: https://git-scm.com/download/

You will also need to add SSH keys to Resin, which will let you deploy code securely from your local system. You can add an SSH key via: https://dashboard.resin.io/preferences/sshkeys

Since Resin can use your GitHub SSH keys, if you have an existing SSH configuration working with GitHub, the easiest method is to configure GitHub SSH and then import it into Resin. For information about setting up SSH on GitHub, see: https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/

To load the FactoryTX software into Resin for deployment:

  1. Run:
    git clone git@github.com:sightmachine/factorytx2.git

Adding the Resin Application as a Remote

You need to add the Resin application as a remote inside your deployment Git repository.

To add the Resin application as a remote:

  1. In the upper-right of the Resin.io maintenance page, there is a snippet to add the remote application to your Git repository.
  2. Copy this text, and then add it as a remote inside your deployment Git repository.
    cd factorytx2
    git remote add resin <your Resin user name>@git.resin.io:<your Resin user name>/<your Resin application name>.git
  3. To check if you did this correctly, you can list your remotes:
    ± % git remote -v origin git@github.com:sightmachine/factorytx2.git (fetch)
    origin git@github.com:sightmachine/factorytx2.git (push)
    resin <your Resin name>@git.resin.io:<your Resin name>/<your Resin application name>.git (fetch)
    resin <your Resin name>@git.resin.io:<your Resin name>/<your Resin application name>.git (push)


    NOTE: This effectively means you can push code to two different remote locations: origin, which is the GitHub repository for committing changes back to Sight Machine, or resin, which will execute a build pipeline and automatically update all the devices in that application with the new software.

Pushing Software to Resin

You can deploy FactoryTX repository code to all devices in the application.

To push software to Resin:

  1. To push the master branch of FTX to the master branch of Resin, run:
    git push resin master
  2. If you want to deploy changes from any other software branch on your local machine, use the following syntax:
    git push resin task/local_branch:master

    where local_branch is the local branch that you are working on. This will effectively push your local branch to the master on the Resin remove, which kicks off the build pipeline.
  3. If everything goes well, you should get a series of logs from the Dockerfile, which ends with a unicorn. Dockerfile is a text document that contains all the commands a user could call on the command line to assemble an image.

Verifying that Changes Deployed Properly

After pushing the software, you can view the status and release history.

To verify that changes deployed properly:

  1. In Resin, on the Releases screen, view the deployments.
  2. After a release completes, it deploys to the devices within that application. On the Devices screen, the device list displays the commit for which the device is updated through.

Setting Login Credentials

The FactoryTX user interface requires a user name and password. You can either disable authentication or set your own user name and password.

To set login credentials:

  1. In Resin, go to the device Summary page, and then on the left, click Environment Variables.
  2. To disable authentication, on the Device Environment Variables page, do the following:
  • Add the variable FTX_NOAUTH.
  • Set it to TRUE.
  • Click Add.
  1. To enable authentication, on the Device Environment Variables page, you need to set two environment variables. Do the following:
  • Add the variable FTX_USERNAME (the string to be used as the user name).
  • Add the variable FTX_PW_HASH (hash of your password string).
  • NOTE: If you want admin/admin as your user name and password, do the following:
    • Set FTX_USERNAME to: admin
    • Set FTX_PW_HASH to: pbkdf2:sha256:50000$z2SStOsN$bb86fa0489dd4c360ba97e15a7744a95bc952fa77170
      bf05cbd1abaa6ae1e3c3
    • Click Add.
  1. To create a hash for your custom password, use this Python method:
    $ python
    >>> from werkzeug.security import generate_password_hash
    >>> generate_password_hash('custom_password')
    'pbkdf2:sha256:50000$Y7Ig4Cbd$ae385722a29068a64ac8d06dfa93dc0872c0b995f62ac6e
    71c87eb5531baed97'

Setting Up Remote Debugging

Resin devices allow you to view of logs from the device, as well as SSH into the device, to debug.

There are also command-line interface (CLI) tools available if you prefer not to use the Web interface. For more information, see: https://docs.resin.io/tools/cli/

NOTE: For Resin CLI to use SSH and logs, you will need to edit your SSH configuration to have the following directive:

<span class="c32">Host *.resindevice.io</span>
     IdentityFile ~/.ssh/SSH_IDENTITY_KEY_FOR_RESIN

To set up remote debugging:

  1. In Resin, click the name of a device in the list to select it.
  2. You can view the logs in the upper-right, or under Terminal, attach to the container in the lower-right.

Connecting to the FactoryTX User Interface

At this point in the deployment process, you should be able to connect to the user interface. This will enable the direct configuration of the system. To access this, you will need a connection to the device’s local network.

To connect to the FactoryTX user interface:

  1. In Resin, to get the local IP of the system, go into the device list for your application.
  2. Type that IP address into a Web browser. For example: http://192.168.1.186:8090/

Finding Additional Resources

This tutorial has showed you how to set up FactoryTX in Resin.io.

There are a number of helpful resources available, should you have any additional questions.

Resource

Links

Resin.io

Documentation:

https://docs.resin.io/introduction/

Support:

https://resin.io/support/

Git/GitHub

Documentation:

https://guides.github.com/

Support:

https://help.github.com/

Dockerfile/
Containers

Documentation:

https://docs.docker.com/

https://docs.docker.com/engine/reference/builder/

More about Linux Containers:

https://www.redhat.com/en/topics/containers