Impinj® ItemSense™ Installation Guide

This document describes the installation process for ItemSense.
Starting with ItemSense 2018r1, the software is provided in a setup package file with a name similar to itemsense-0.1.XX-setup.run.

Earlier versions of ItemSense, including ItemSense 2017r1, were provided in an archive file format with a name similar to is.IT-BTIC-BUT.0.1.XX.tar.bz2. Where the process differs there are links referring to the Legacy Installation Guide.

Table of Contents

Introduction

The ItemSense software is provided in a setup package for customers who are installing the software within their company managed network. In this package there are a number of files, but the primary components of ItemSense are delivered as a series of docker containers. This part of the document describes the process for installing ItemSense using the setup package.

Note that this guide assumes a good grasp of the Linux command line.

Prerequisites for ItemSense

Before starting the ItemSense installation process, the following steps must be completed:

  • Obtain an ItemSense Instance ID from your Impinj representative
  • Download the ItemSense setup package from the link in the welcome email
  • Install the following software on the server where ItemSense will be installed
    • Linux operating system with ONLY these specific versions:
    • Ubuntu version 16.04 with the latest kernel for this distribution, or
    • Centos version 7 with the latest kernel version for this distribution
    • Docker, version 1.12 or later
    • Docker Compose, version 1.14 or later
  • Ensure that all of the RAIN RFID readers are configured with an NTP server. See Clock Synchronization and NTP Configuration for more details
  • Ensure that the user installing ItemSense is a real Linux user and has a home directory, as ItemSense will install under that user's home directory
  • Ensure that the host has the required ItemSense ports open. See Requirements for more details

Instructions for installing docker can be found here and instructions for installing Docker Compose can be found here.

Install ItemSense 2018r1

Pre-checks

Run the following commands in a terminal on the target server to confirm if the server is in the correct state to begin installation:

  1. Check that nothing is listening on port 80, 3010, 443 or 5672.

    For example, this command should not show any output:

    sudo netstat -tlnp | grep ':80\W\|:3010\W\|:443\W\|:5672\W'

  2. If this is a clean install and not an upgrade from an earlier ItemSense version, check that no previous docker images already exist.

    sudo docker images

    If this command shows some ItemSense docker images already exist, follow the uninstall instructions below to remove them

  3. Check that docker is installed and is at the version specified in the prerequisites:

    docker -v

    Example output:

    Docker version 1.12.1, build 23cf638
    
  4. Check that docker-compose is installed and is at the version specified in the prerequisites:

    docker-compose -v

    Example output:

    docker-compose version 1.14.0, build c7bdf9e
    
  5. Check that there is at least 8GB of available disk space:

    df -h ~

    Example output:

    Filesystem      Size  Used Avail Use% Mounted on
    /dev/sdb1        99G  7.0G   87G   8% /home
    

    Details:

    • The setup package itself will require around 1GB of space. This package can potentially be removed once the installation is complete
    • The setup package will require around 3GB of temporary space to extract the compressed images. This space will be reclaimed automatically at the end of the installation
    • The docker images will require around 3GB of space once installed
    • The containers/ folder will require a minimum of 200MB to install. It will grow over time as ItemSense runs and item records are stored in the database

Installation Instructions

For older versions of ItemSense, refer to the Legacy Installation Guide.

To install ItemSense 2018r1, you will need to have already downloaded the setup package. This file will be named similar to the following: itemsense-0.1.XX-setup.run As the file is roughly 1.1GB it may take a while to download, depending on your connection.

When the setup package file has been obtained:

  1. Copy the file to the target server.

    scp itemsense-0.1.XX-setup.run USERNAME@TARGET_SERVER:.

    Where:

    • USERNAME should be replaced with the user on the target server.
    • TARGET_SERVER should be replaced with the hostname or IP address of the server on which you intend to install ItemSense.
  2. When the file transfer to the target server has completed, log on to the target server and navigate to the location where you placed the file. If you followed the command above, the file will be in the home directory of the user used to transfer the file on to the target server.

    Note: No matter where you place the setup package, ItemSense will always be installed to the home directory of the login name defined by the environment variable $SUDO_USER. This variable is set by the sudo command anytime it is invoked.

    The following command can be executed to see the value of $SUDO_USER.

    sudo bash -c 'echo $SUDO_USER'

  3. Make sure the setup package file is executable:

    chmod +x itemsense-0.1.XX-setup.run

  4. From the same directory as the ItemSense setup package, run the setup package with the argument "install" or "upgrade" depending on the type of installation you are performing.

    During installation you will be asked to confirm if you would like to continue with the installation. Select 'y' to continue with the installation or 'n' to back out of the installation.

    Note: this script must be run either as the root user or with sudo. If run as the root user, ItemSense will be installed in the root user's home directory (typically /root).

    sudo ./itemsense-0.1.XX-setup.run install

    Example output:

    Note: Some verbosity has been omitted, denoted below by a standalone ellipsis (...) line

    [is_support@localhost ~]$ sudo ./itemsense-0.1.XX-setup.run install
    Verifying archive integrity...  100%   All good.
    Uncompressing ItemSense 2018r1 Build XX Setup Package  100%
    About to install ItemSense at path /home/is_support, Ready to proceed (y/n)? y
    INFO: Generating Prod compose file: /home/is_support/itemsense-prod-3.yml
    INFO: Unpacking docker container images
    
    ...
    
    Loaded image: isreg/imc:1.0.454
    
    ...
    
    Loaded image: isreg/is-mariadb:10.0.28
    
    ...
    
    Loaded image: isreg/itemsense:master-84c42
    
    ...
    
    Loaded image: nginx:1.10.3-alpine
    INFO: Firmware images
    INFO: Installing nginx container configuration
    INFO: Start the new docker compose file
    Creating issupport_nginx_1     ... done
    Creating issupport_is-rabbit_1 ... done
    Creating issupport_itemsense_1 ... done
    Creating issupport_imc_1       ... done
    Creating issupport_is-db_1     ... done
    INFO: Installation action complete using path: /home/is_support
    INFO: Endpoints test: Wait up to 300 secs, re-test every 5 secs
    INFO: 0: Testing  control endpoint http://127.0.0.1/itemsense/control/admin/ping
    INFO: 0: Testing  control endpoint 127.0.0.1/itemsense/control/admin/ping
    INFO: 0: Testing  control endpoint http://localhost/itemsense/control/admin/ping
    INFO: 0: Testing  control endpoint localhost/itemsense/control/admin/ping
    INFO: 0: Testing  control endpoint http://[::1]/itemsense/control/admin/ping
    INFO: 0: Testing  control endpoint [::1]/itemsense/control/admin/ping
    INFO: 0: Testing  data endpoint http://127.0.0.1/itemsense/data/admin/ping
    INFO: 0: Testing  data endpoint 127.0.0.1/itemsense/data/admin/ping
    INFO: 0: Testing  data endpoint http://localhost/itemsense/data/admin/ping
    INFO: 0: Testing  data endpoint localhost/itemsense/data/admin/ping
    INFO: 0: Testing  data endpoint http://[::1]/itemsense/data/admin/ping
    INFO: 0: Testing  data endpoint [::1]/itemsense/data/admin/ping
    
    ...
    
    INFO: ItemSense endpoints test passed
    INFO: Testing for imc endpoint
    INFO: 0: Sending query to imc endpoint
    INFO: ...Found imc endpoint
    INFO: ItemSense install operation complete at path /home/is_support
    
  5. In a browser, navigate to the IMC using the server IP address or host name and port 3010:

    http://TARGET_SERVER:3010/

    Note: after ItemSense starts it can take a minute or so before the IMC will be available

Upgrade ItemSense

Upgrade to the latest 2018r1 (from an existing version of 2018r1) using separate hosts

These instructions stand up a separate instance of ItemSense and run a migration script to copy over configuration. This is the preferred method for upgrading ItemSense as it minimizes the chance of errors.

Note: Historical item, health, and job data will be lost using this upgrade method. If you need to retain your historical item data across the upgrade, then please follow the instructions for upgrade on the same host. API token data will also be lost using this upgrade method. If you use this upgrade method, all issued API tokens will need to be re-generated and re-issued.

Prerequisites

  • ItemSense 2018r1 build XXX is installed and is up and running (on TARGETSERVERXXX)
  • ItemSense 2018r1 build YYY has been installed (according to the installation steps above) and is up and running (at TARGETSERVERYYY)
  • node.js version 6.9.4 or later has been installed (go to https://nodejs.org/en/download/ to download and install it)

Instructions

  1. Install the latest version of the is-tool node package on any host that has network access to both ItemSense instances.

    npm install -g is-tool

    The is-tool has its own set of documentation and prerequisites that can be found here: https://www.npmjs.com/package/is-tool

  2. Save the configuration from the original instance. The is-tool saves the configuration in the file specified by filename. If you do not specify a filename, the is-tool generates one. The TARGET_SERVER_XXX value must be replaced with the hostname or the IP address of the server on which the original version of ItemSense 2018r1 is installed.

    is-tool save -i TARGET_SERVER_XXX -u admin -p admindefault <filename>

  3. Load the saved configuration to the new 2018r1 instance.

    is-tool load <filename> -i TARGET_SERVER_YYY -u admin -p admindefault --addpassword

    Where: * TARGET_SERVER_YYY value must be replaced with the hostname or IP address of the server on which the new ItemSense 2018r1 is installed.

    Note: the --addpassword option resets all user passwords (with the exception of the admin user) to default01. These user accounts will need to update their passwords on the new instance from this default placeholder.

    Example output:

    Reading my-saved-configuration
    Loading configuration...
    Loading facilities
    Loading readerDefinitions
    Loading readerConfigurations
    Loading recipes
    Loading zoneMaps
    Loading users
    
        
    
  4. Migrate the current zone map configuration from the old instance to the new.

    This configuration is not backed up by the is-tool, and must be migrated manually.

    1. Obtain the current zone map configuration from TARGET_SERVER_XXX

      This can be obtained via the IMC (http://TARGET_SERVER_XXX:3010) by navigating to the Zone Map tab, and for each facility, making a note of the current zone map. Note that a facility may not have a current zone map, in which case there is no migration required for that facility.

      Alternatively the current zone map configuration can be obtained using the API:

      curl -u<username>:<password> http://TARGET_SERVER_XXX/itemsense/control/v1/currentZoneMap/show/{facilityName}

      If there is no current zone map set for that facility, the API will return the following data in the HTTP response (and there is no migration necessary for that facility):

      {"name":null,"status":"WAITING_FOR_ZONE_MAP"}
      
    2. Set this current zone configuration in the new instance

      Again this can be done via the IMC or the API

      Via the IMC, navigate to the Zone Map tab, and select each facility in turn, and set the current zone map obtained in the previous step.

      Via the API (note that ItemSense infers the correct facility from the zone map name):

      curl -X POST -u<username>:<password> http://TARGET_SERVER_YYY/itemsense/control/v1/currentZoneMap/select/{zoneMapName}

  5. At this point all configuration has been migrated to the 2018r1 instance but the readers are still provisioned against the old instance.

    Connect to the new ItemSense 2018r1 instance via the ItemSense Management Console (IMC) at http://TARGET_SERVER_YYY:3010

    • Add a network
      • Find a network to add by looking at the Address field of a reader definition
      • Go to the Scanner Configuration page of the IMC: (three dots in upper right)→Admin→Scanner config
    • Register readers
      • readers→SCANNER→DISCOVER READERS
      • Select only the readers flagged with the triangle exclamation point
      • Click on "REGISTER SELECTED READERS"
    • Upgrade reader firmware
      • (three dots in upper right)→Admin and then selected the "SOFTWARE UPDATES" tab
      • Select "Reader Firmware" under "Software to Install"
      • Select your set of readers to update
      • Click "START INSTALLATION"
    • Now the readers are registered, upgraded, and ready to start jobs

Upgrade to the latest version of 2018r1 (from an existing version of 2018r1) on the same host

This installs the new release of ItemSense over an existing instance. This is a riskier procedure than than upgrading via separate hosts, but does have the advantage of allowing you to retain item, health and job data. If retaining historical data is not a concern for you then please follow the instructions for an upgrade using separate hosts.

Prerequisites

  • ItemSense 2018r1 build XXX has been installed and is up and running (at TARGET_SERVER)

  • The latest ItemSense 2018r1 YYY setup package has been downloaded

  • Check that there is at least 5GB of available disk space on TARGET_SERVER to hold the new installation binaries and backups during the installation

    df -h ~

    Example output:

    Filesystem      Size  Used Avail Use% Mounted on
    /dev/sdb1        99G  7.0G   87G   8% /home
    

    Note: The space requirement could vary significantly depending on the size of the containers/ folder, detailed below

    Details:

    • The setup package itself will require around 1GB of space. This package can potentially be removed once the installation is complete

    • The setup package will require around 3GB of temporary space to extract the compressed images. This space will be reclaimed automatically at the end of the installation

    • During the upgrade the old docker images will be removed and the associated disk space of around 3GB will be reclaimed. Then the newly installed docker images will require around 3GB of space. To view the current size of the docker images use the following command

      sudo docker images

      Example output:

      REPOSITORY                TAG                 IMAGE ID            CREATED                  SIZE
      isreg/itemsense           master-7f2d5        0f723c002e5e        Less than a second ago   761MB
      isreg/imc                 1.0.456             19e4e0b61c86        Less than a second ago   1.08GB
      isreg/is-rabbitmq-runit   3.5.7r3             c3b540cf1b9b        2 weeks ago              372MB
      nginx                     1.10.3-alpine       f94d6dd9b576        12 months ago            54MB
      isreg/is-mariadb          10.0.28             9624719527fa        16 months ago            340MB
      
    • The containers/ folder requires a minimum of 200MB at install time. It will grow over time, potentially to several gigabytes, as ItemSense runs and item records are stored in the database. To view the current size of the containers/ folder use the following command

      sudo du -sh containers/

      Example output:

      202M    containers/
      

      Note: The upgrade process will automatically make one backup of the containers/ folder. There will need to be at least enough space available for one backup. If the fist (Optional) step below is followed to create a manual backup of the containers/ folder then twice the amount of space will be needed.

Instructions

  1. (Optional) In case the upgrade fails, backup your configuration and database. This is a precaution only, and the backed up data will not be needed after a successful upgrade

    1. Install node.js version 6.9.4 or later (go to https://nodejs.org/en/download/ to download and install it)

    2. Install the latest version of is-tool Node package. This tool can be installed on any host that has network access to the ItemSense host.

      npm install -g is-tool

      The is-tool has its own set of documentation and prerequisites that can be found here: https://www.npmjs.com/package/is-tool

    3. Save the configuration from the existing 2018r1 instance. The is-tool saves the configuration in the file specified by filename. If you do not specify a filename, the is-tool generates one.

      is-tool save -i TARGET_SERVER -u admin -p admindefault <filename>

    4. The previous step saves all of the ItemSense configuration, except for:

      • the current zone map configuration: to back this up manually, see the current zone map backup and restore step in the Upgrade using separate hosts section above

      • user passwords: these are not exported by the is-tool for security reasons

      • API tokens: these can be backed up manually via the API:

        curl -u<username>:<password> http://TARGET_SERVER/itemsense/authentication/v1/listTokens/{user}

    5. Stop ItemSense. You must be in the home directory of the user that installed ItemSense, which is the location of the ItemSense docker-compose YAML file.

      sudo docker-compose -f itemsense-prod-3.yml down

      Example output:

      Stopping issupport_is-db_1     ... done
      Stopping issupport_imc_1       ... done
      Stopping issupport_nginx_1     ... done
      Stopping issupport_itemsense_1 ... done
      Stopping issupport_is-rabbit_1 ... done
      Removing issupport_is-db_1     ... done
      Removing issupport_imc_1       ... done
      Removing issupport_nginx_1     ... done
      Removing issupport_itemsense_1 ... done
      Removing issupport_is-rabbit_1 ... done
      
    6. Back up the ItemSense database. The database is stored in: <ItemSense home folder>/containers/is-db

      sudo cp -r ~/containers/is-db ~/IS_DB_BACKUP

    7. Restart ItemSense

      sudo docker-compose -f itemsense-prod-3.yml up -d

    8. Take note of the registered networks for scanning, as these won't be migrated.

      • Connect to the existing ItemSense version via the ItemSense Management Console at: http://TARGET_SERVER:3010
      • Go to the Scanner Configuration page: (three dots in upper right)→Admin→Scanner config
      • Take a note of the networks that require migrating i.e. networks containing the readers that are being managed by the existing ItemSense version
    9. Copy the latest ItemSense 2018r1 setup package on to the ItemSense host:

      scp itemsense-0.1.YYY_setup.run USERNAME@TARGET_SERVER:.

      Where:

      • USERNAME should be replaced with the user on the target server.
      • TARGET_SERVER should be replaced with the hostname or IP address of the server on which ItemSense is installed
      • YYY should be replaced to match the filename of the latest downloaded ItemSense setup package
    10. When the file transfer to the target server has finished, log on to the target server and navigate to the location of the file. Using the command above, the file will be in the home directory of the user used to transfer the file on to the target server.

    11. Make sure the setup package file is executable:

      chmod +x itemsense-0.1.YYY_setup.run

    12. Upgrade the existing docker containers using the 2018r1 setup package.

      During installation you will be asked to confirm if you would like to continue with the installation. Select 'y' to continue with the installation or 'n' to back out of the installation.

      sudo ./itemsense-0.1.YYY_setup.run upgrade

      Example output:

      Note: Some verbosity has been omitted, denoted below by a standalone ellipsis (...) line

      [is_support@localhost ~]$ sudo ./itemsense-0.1.922-setup.run upgrade
      Verifying archive integrity...  100%   All good.
      Uncompressing ItemSense 2018r1 Build YYY Setup Package  100%
      INFO: Found existing ItemSense installation: "2018r1 Build XXX" at path /home/is_support
      About to upgrade ItemSense at path /home/is_support, Ready to proceed (y/n)? y
      INFO: Stopping and removing previous installation
      Stopping issupport_is-db_1     ... done
      Stopping issupport_imc_1       ... done
      Stopping issupport_itemsense_1 ... done
      Stopping issupport_is-rabbit_1 ... done
      Stopping issupport_nginx_1     ... done
      Removing issupport_is-db_1     ... done
      Removing issupport_imc_1       ... done
      Removing issupport_itemsense_1 ... done
      Removing issupport_is-rabbit_1 ... done
      Removing issupport_nginx_1     ... done
      INFO: Removing container images from local docker registry
      INFO: ...Removing nginx:1.10.3-alpine
      Untagged: nginx:1.10.3-alpine
      
      ...
      
      INFO: ...Removing isreg/is-mariadb:10.0.28
      Untagged: isreg/is-mariadb:10.0.28
      
      ...
      
      INFO: ...Removing isreg/is-rabbitmq-runit:3.5.7r3
      Untagged: isreg/is-rabbitmq-runit:3.5.7r3
      
      ...
      
      INFO: ...Removing isreg/imc:1.0.450
      Untagged: isreg/imc:1.0.450
      
      ...
      
      INFO: ...Removing isreg/itemsense:master-36121
      Untagged: isreg/itemsense:master-36121
      
      ...
      
      INFO: Backing up previous binaries
      INFO: Re-integrating previous data files for migration
      INFO: Generating Prod compose file: /home/is_support/itemsense-prod-3.yml
      INFO: Unpacking docker container images
      
      ...
      
      Loaded image: isreg/imc:1.0.454
      
      ...
      
      Loaded image: isreg/is-mariadb:10.0.28
      
      ...
      
      Loaded image: isreg/is-rabbitmq-runit:3.5.7r3
      
      ...
      
      Loaded image: isreg/itemsense:master-84c42
      
      ...
      
      Loaded image: nginx:1.10.3-alpine
      INFO: Firmware images
      INFO: Installing nginx container configuration
      INFO: Start the new docker compose file
      Creating issupport_is-db_1     ... done
      Creating issupport_nginx_1     ... done
      Creating issupport_itemsense_1 ... done
      Creating issupport_is-rabbit_1 ... done
      Creating issupport_imc_1       ... done
      INFO: Installation action complete using path: /home/is_support
      INFO: Waiting for data migrations to resolve
      INFO: Restoring IMC config data
      INFO: Restoring ItemSense config store
      INFO: Restarting ItemSense to import config
      Restarting issupport_imc_1       ... done
      Restarting issupport_is-rabbit_1 ... done
      Restarting issupport_nginx_1     ... done
      Restarting issupport_is-db_1     ... done
      Restarting issupport_itemsense_1 ... done
      INFO: Upgrade action complete
      INFO: Endpoints test: Wait up to 300 secs, re-test every 5 secs
      INFO: 0: Testing  control endpoint http://127.0.0.1/itemsense/control/admin/ping
      INFO: 0: Testing  control endpoint 127.0.0.1/itemsense/control/admin/ping
      INFO: 0: Testing  control endpoint http://localhost/itemsense/control/admin/ping
      INFO: 0: Testing  control endpoint localhost/itemsense/control/admin/ping
      INFO: 0: Testing  control endpoint http://[::1]/itemsense/control/admin/ping
      INFO: 0: Testing  control endpoint [::1]/itemsense/control/admin/ping
      INFO: 0: Testing  data endpoint http://127.0.0.1/itemsense/data/admin/ping
      INFO: 0: Testing  data endpoint 127.0.0.1/itemsense/data/admin/ping
      INFO: 0: Testing  data endpoint http://localhost/itemsense/data/admin/ping
      INFO: 0: Testing  data endpoint localhost/itemsense/data/admin/ping
      INFO: 0: Testing  data endpoint http://[::1]/itemsense/data/admin/ping
      INFO: 0: Testing  data endpoint [::1]/itemsense/data/admin/ping
      
      ...
      
      INFO: ItemSense endpoints test passed
      INFO: Testing for imc endpoint
      INFO: 0: Sending query to imc endpoint
      INFO: ...Found imc endpoint
      INFO: ItemSense upgrade operation complete at path /home/is_support
      
    13. At this point all configuration has been migrated to the 2018r1 instance but the readers are still provisioned against the old instance.

      Connect to the new ItemSense 2018r1 instance via the ItemSense Management Console (IMC) at http://TARGET_SERVER:3010

      • Add a network
        • Find a network to add by looking at the Address field of a reader definition
        • Go to the Scanner Configuration page of the IMC: (three dots in upper right)→Admin→Scanner config
      • Register readers
        • readers→SCANNER→DISCOVER READERS
        • Select only the readers flagged with the triangle exclamation point
        • Click on "REGISTER SELECTED READERS"
      • Upgrade reader firmware
        • (three dots in upper right)→Admin and then selected the "SOFTWARE UPDATES" tab
        • Select "Reader Firmware" under "Software to Install"
        • Select your set of readers to update
        • Click "START INSTALLATION"
      • Now the readers are registered, upgraded, and ready to start jobs
    14. If the upgrade was successful, clean up the backups created:

      sudo rm -rf ~/IS_DB_BACKUP

      rm is-save*

Upgrade from 2017r1 to 2018r1 using separate hosts

These instructions stand up a separate instance of ItemSense and run a migration script to copy over configuration. This is the preferred method for upgrading ItemSense as it minimizes the chance of errors.

Note: Historical item, health, and job data will be lost using this upgrade method. If you need to retain your historical item data across the upgrade, then please follow the instructions for installation on the same host.

Prerequisites

  • ItemSense 2017r1 Limited Availability Build 544 or newer has been installed and is up and running

    Note: Upgrades from ItemSense versions prior to 2017r1 Limited Availability Build 544 are unsupported.

  • ItemSense 2018r1 has been installed (according to the installation steps pertaining to the specific build) and is up and running

  • node.js version 6.9.4 or later has been installed (go to https://nodejs.org/en/download/ to download and install it)

Instructions

  1. Install the latest version of the is-tool Node package on any host that has network access to both instances of ItemSense.

    npm install -g is-tool

    The is-tool has its own set of documentation and prerequisites that can be found here: https://www.npmjs.com/package/is-tool

  2. Save the configuration from the 2017r1 instance. The is-tool saves the configuration in the file specified by filename. If you do not specify a filename, the is-tool generates one. The SERVER_2017r1 value must be replaced with the hostname or the IP address of the server on which ItemSense 2017r1 is installed.

    is-tool save -i SERVER_2017r1 -u admin -p admindefault <filename>

  3. Load the saved 2017r1 configuration to the 2018r1 instance. The SERVER_2018r1 value must be replaced with the hostname or IP address of the server on which ItemSense 2018r1 is installed.

    is-tool load <filename> -i SERVER_2018r1 -u admin -p admindefault

    Example output:

    Reading my-saved-2017r1-configuration
    Loading configuration...
    Loading facilities
    Loading readerDefinitions
    Loading readerConfigurations
    Loading recipes
    Loading zoneMaps
    Loading users
    
  4. At this point all configuration has been migrated to the 2018r1 instance but the readers are still provisioned against the 2017r1 instance. You will need to go through the provisioning flow to associate the defined readers with the new 2018r1 instance.

    • Add a network
      • Find a network to add by looking at the Address field of a reader definition
      • Go to the Scanner Configuration page of the IMC: (three dots in upper right)→Admin→Scanner config
    • Register readers
      • readers→SCANNER→DISCOVER READERS
      • Select only the readers flagged with the triangle exclamation point
      • Click on "REGISTER SELECTED READERS"
    • Upgrade reader firmware
      • (three dots in upper right)→Admin and then selected the "SOFTWARE UPDATES" tab
      • Select "Reader Firmware" under "Software to Install"
      • Select your set of readers to update
      • Click "START INSTALLATION"
    • Now the readers are registered, upgraded, and ready to start jobs

Upgrade from 2017r1 to 2018r1 on the same host

This installs the new release of ItemSense over an existing instance. This is a riskier procedure but does have the advantage of allowing you to retain item, health and job data. If retaining historical data is not a concern for you then please follow the instructions for an upgrade using separate hosts.

Prerequisites

  • ItemSense 2017r1 Limited Availability Build 544 or newer has been installed and is up and running

    Note: Upgrades from ItemSense versions prior to 2017r1 Limited Availability Build 544 are unsupported.

  • ItemSense 2018r1 setup package has been obtained

  • ItemSense is running on TARGET_SERVER

  • node.js version 6.9.4 or later has been installed (go to https://nodejs.org/en/download/ to download and install it)

Instructions

  1. (Optional) As a precaution in case the upgrade fails, backup your configuration and database.

    1. Install the latest version of the is-tool Node package on any host that has network access to the ItemSense instance.

      npm install -g is-tool

      The is-tool has its own set of documentation and prerequisites that can be found here: https://www.npmjs.com/package/is-tool

    2. Save the configuration from the old instance. The is-tool saves the configuration in the file specified by filename. If you do not specify a filename, the is-tool generates one.

      is-tool save -i TARGET_SERVER -u admin -p admindefault <filename>

    3. Stop ItemSense and the database container. You must be in the home directory of the user that installed ItemSense, which is the location of the ItemSense docker-compose YAML file.

      sudo docker-compose -f itemsense-prod-1.6.0.yml down

      Example output:

      Stopping is_support_is-db_1     ... done
      Stopping is_support_itemsense_1 ... done
      Removing is_support_is-db_1     ... done
      Removing is_support_itemsense_1 ... done
      Removing network is_support_default
      
    4. Back up the ItemSense database. The database is stored in: <ItemSense home folder>/containers/is-db

      sudo cp -r ~/containers/is-db ~/IS_DB_BACKUP

  2. Take note of the registered networks for scanning, as these won't be migrated.

    • Connect to the existing ItemSense version via the ItemSense Management Console at: http://TARGET_SERVER:3010
    • Go to the Scanner Configuration page: (three dots in upper right)→Admin→Scanner config
    • Take a note of the networks that require migrating i.e. networks containing the readers that are being managed by the existing ItemSense version
  3. Copy the ItemSense setup package file to the target server.

    scp itemsense-0.1.XX_setup.run USERNAME@TARGET_SERVER:.

    Where:

    • USERNAME should be replaced with the user on the target server
    • TARGET_SERVER should be replaced with the hostname or IP address of the server on which ItemSense is to be installed
  4. When the file transfer to the target server has completed, log on to the target server and navigate to the location where you placed the file. If you followed the command above, the file will be in the home directory of the user used to transfer the file on to the target server.

  5. Upgrade Docker Compose to version 1.14 or later. Instructions for installing Docker Compose can be found here.

  6. Make sure the setup package file is executable:

    chmod +x itemsense-0.1.XX_setup.run

  7. Upgrade the existing docker containers using the setup package.

    During installation you will be asked to confirm if you would like to continue with the installation. Select 'y' to continue with the installation or 'n' to back out of the installation.

    sudo ./itemsense-0.1.XX_setup.run upgrade

    Example output:

    Note: Some verbosity has been omitted, denoted below by a standalone ellipsis (...) line

    [is_support@localhost ~]$ sudo ./itemsense-0.1.XX-setup.run upgrade
    Verifying archive integrity...  100%   All good.
    Uncompressing ItemSense 2018r1 Build XX Setup Package  100%
    INFO: Found existing ItemSense installation: "2017r1 General Availability Build 850-5" at path /home/is_support
    About to upgrade ItemSense at path /home/is_support, Ready to proceed (y/n)? y
    INFO: Stopping and removing previous installation
    Stopping issupport_is-db_1     ... done
    Stopping issupport_itemsense_1 ... done
    Removing issupport_is-db_1     ... done
    Removing issupport_itemsense_1 ... done
    Removing network issupport_default
    INFO: Removing container images from local docker registry
    INFO: ...Removing isreg/is-mariadb:10.0.28
    Untagged: isreg/is-mariadb:10.0.28
    
    ...
    
    INFO: ...Removing isreg/itemsense:PI-7473-build-850-plus-plus-0682d
    Untagged: isreg/itemsense:PI-7473-build-850-plus-plus-0682d
    
    ...
    
    INFO: Backing up previous binaries
    INFO: Re-integrating previous data files for migration
    INFO: Generating Prod compose file: /home/is_support/itemsense-prod-3.yml
    INFO: Unpacking docker container images
    
    ...
    
    Loaded image: isreg/imc:1.0.454
    
    ...
    
    Loaded image: isreg/is-mariadb:10.0.28
    
    ...
    
    Loaded image: isreg/is-rabbitmq-runit:3.5.7r3
    
    ...
    
    Loaded image: isreg/itemsense:master-84c42
    
    ...
    
    Loaded image: nginx:1.10.3-alpine
    INFO: Firmware images
    INFO: Installing nginx container configuration
    INFO: Start the new docker compose file
    Creating issupport_nginx_1     ... done
    Creating issupport_is-rabbit_1 ... done
    Creating issupport_imc_1       ... done
    Creating issupport_itemsense_1 ... done
    Creating issupport_is-db_1     ... done
    INFO: Installation action complete using path: /home/is_support
    INFO: Waiting for data migrations to resolve
    INFO: Restoring IMC config data
    INFO: Restoring ItemSense config store
    INFO: Restarting ItemSense to import config
    Restarting issupport_is-db_1     ... done
    Restarting issupport_itemsense_1 ... done
    Restarting issupport_is-rabbit_1 ... done
    Restarting issupport_imc_1       ... done
    Restarting issupport_nginx_1     ... done
    INFO: Upgrade action complete
    INFO: Endpoints test: Wait up to 300 secs, re-test every 5 secs
    INFO: 0: Testing  control endpoint http://127.0.0.1/itemsense/control/admin/ping
    INFO: 0: Testing  control endpoint 127.0.0.1/itemsense/control/admin/ping
    INFO: 0: Testing  control endpoint http://localhost/itemsense/control/admin/ping
    INFO: 0: Testing  control endpoint localhost/itemsense/control/admin/ping
    INFO: 0: Testing  control endpoint http://[::1]/itemsense/control/admin/ping
    INFO: 0: Testing  control endpoint [::1]/itemsense/control/admin/ping
    INFO: 0: Testing  data endpoint http://127.0.0.1/itemsense/data/admin/ping
    INFO: 0: Testing  data endpoint 127.0.0.1/itemsense/data/admin/ping
    INFO: 0: Testing  data endpoint http://localhost/itemsense/data/admin/ping
    INFO: 0: Testing  data endpoint localhost/itemsense/data/admin/ping
    INFO: 0: Testing  data endpoint http://[::1]/itemsense/data/admin/ping
    INFO: 0: Testing  data endpoint [::1]/itemsense/data/admin/ping
    
    ...
    
    INFO: ItemSense endpoints test passed
    INFO: Testing for imc endpoint
    INFO: 0: Sending query to imc endpoint
    INFO: ...Found imc endpoint
    INFO: ItemSense upgrade operation complete at path /home/is_support
    
  8. At this point all configuration has been migrated to the new instance but the readers are still provisioned against the old instance. You will need to go through the provisioning flow to associate the defined readers with the new instance.

    • Add a network
      • Find a network to add by looking at the Address field of a reader definition
      • Go to the Scanner Configuration page of the IMC: (three dots in upper right)→Admin→Scanner config
    • Register readers
      • readers→SCANNER→DISCOVER READERS
      • Select only the readers flagged with the triangle exclamation point
      • Click on "REGISTER SELECTED READERS"
    • Upgrade reader firmware
      • (three dots in upper right)→Admin and then selected the "SOFTWARE UPDATES" tab
      • Select "Reader Firmware" under "Software to Install"
      • Select your set of readers to update
      • Click "START INSTALLATION"
    • Now the readers are registered, upgraded, and ready to start jobs
  9. If the upgrade was successful, clean up the backups created:

    sudo rm -rf ~/IS_DB_BACKUP

    rm is-save*

Upgrade earlier versions of ItemSense

If you are runnning a version of ItemSense that is older than 2017r1, please contact Impinj Support: support@impinj.com.

Uninstall ItemSense Via Automated Process

For older versions of ItemSense, refer to the Legacy Installation Guide.

To uninstall ItemSense via the automated process, follow these steps:

  1. Go to the directory where you put the ItemSense installer file.

  2. Do one of the following steps to remove all or part of an ItemSense installation:

    • Run the installer with the remove subcommand and -p option to remove the ItemSense software and purge all configuration and stored Item data:

      sudo ./itemsense-0.1.XX_setup.run remove -p

      Example output:

      Note: Some verbosity has been omitted, denoted below by a standalone ellipsis (...) line

      [is_support@localhost ~]$ sudo ./itemsense-0.1.XX-setup.run remove -p
      Verifying archive integrity...  100%   All good.
      Uncompressing ItemSense 2018r1 Build XX Setup Package  100%
      About to completely remove ItemSense containers and data at path /home/is_support, Ready to proceed (y/n)? y
      INFO: Stopping and deleting containers
      Stopping issupport_imc_1       ... done
      Stopping issupport_is-db_1     ... done
      Stopping issupport_itemsense_1 ... done
      Stopping issupport_is-rabbit_1 ... done
      Stopping issupport_nginx_1     ... done
      Removing issupport_imc_1       ... done
      Removing issupport_is-db_1     ... done
      Removing issupport_itemsense_1 ... done
      Removing issupport_is-rabbit_1 ... done
      Removing issupport_nginx_1     ... done
      INFO: Removing container images from local docker registry
      INFO: ...Removing nginx:1.10.3-alpine
      Untagged: nginx:1.10.3-alpine
      
      ...
      
      INFO: ...Removing isreg/is-mariadb:10.0.28
      Untagged: isreg/is-mariadb:10.0.28
      
      ...
      
      INFO: ...Removing isreg/is-rabbitmq-runit:3.5.7r3
      Untagged: isreg/is-rabbitmq-runit:3.5.7r3
      
      ...
      
      INFO: ...Removing isreg/imc:1.0.454
      Untagged: isreg/imc:1.0.454
      
      ...
      
      INFO: ...Removing isreg/itemsense:master-84c42
      Untagged: isreg/itemsense:master-84c42
      
      ...
      
      INFO: ItemSense remove_and_purge operation complete at path /home/is_support
      
    • Run the installer with the remove subcommand, omitting the -p option, to remove only the ItemSense software while retaining configuration and stored Item data for offline inspection:

      sudo ./itemsense-0.1.XX_setup.run remove

      Example output:

      Note: Some verbosity has been omitted, denoted below by a standalone ellipsis (...) line

      [is_support@localhost ~]$ sudo ./itemsense-0.1.XX-setup.run remove
      Verifying archive integrity...  100%   All good.
      Uncompressing ItemSense 2018r1 Build XX Setup Package  100%
      About to stop and remove containers at path /home/is_support, Ready to proceed (y/n)? y
      INFO: Stopping and deleting containers
      Stopping issupport_is-db_1     ... done
      Stopping issupport_nginx_1     ... done
      Stopping issupport_itemsense_1 ... done
      Stopping issupport_is-rabbit_1 ... done
      Stopping issupport_imc_1       ... done
      Removing issupport_is-db_1     ... done
      Removing issupport_nginx_1     ... done
      Removing issupport_itemsense_1 ... done
      Removing issupport_is-rabbit_1 ... done
      Removing issupport_is-rabbit_1 ... done
      Removing issupport_imc_1       ... done
      INFO: Removing container images from local docker registry
      INFO: ...Removing nginx:1.10.3-alpine
      Untagged: nginx:1.10.3-alpine
      
      ...
      
      INFO: ...Removing isreg/is-mariadb:10.0.28
      Untagged: isreg/is-mariadb:10.0.28
      
      ...
      
      INFO: ...Removing isreg/is-rabbitmq-runit:3.5.7r3
      Untagged: isreg/is-rabbitmq-runit:3.5.7r3
      
      ...
      
      INFO: ...Removing isreg/imc:1.0.454
      Untagged: isreg/imc:1.0.454
      
      ...
      
      INFO: ...Removing isreg/itemsense:master-84c42
      Untagged: isreg/itemsense:master-84c42
      
      ...
      
      INFO: ItemSense remove operation complete at path /home/is_support
      

      After this procedure if you intend to install ItemSense again under the same user account then you will have to move the containers directory to a new location.

      sudo mv containers containers_bak

      Otherwise the install and upgrade options will be met with errors.

      Example install output with errors:

      [is_support@localhost ~]$ sudo ./itemsense-0.1.XX-setup.run install
      Verifying archive integrity...  100%   All good.
      Uncompressing ItemSense 2018r1 Build XX Setup Package  100%
      ERROR: Found existing ItemSense installation: "2018r1 Build XX" at path /home/is_support
      ERROR: Please remove the old install first or issue the upgrade command instead
      ERROR: ItemSense install operation exited with status 1 at path /home/is_support
      

      Example upgrade output with errors:

      [is_support@localhost ~]$ sudo ./itemsense-0.1.XX-setup.run upgrade
      Verifying archive integrity...  100%   All good.
      Uncompressing ItemSense 2018r1 Build XX Setup Package  100%
      INFO: Found existing ItemSense installation: "2018r1 Build XX" at path /home/is_support
      INFO: Unable to locate a supported docker compose file
      ERROR: Cannot proceed.
      ERROR: ItemSense upgrade operation exited with status 1 at path /home/is_support
      

Uninstall ItemSense Via Manual Process

To manually uninstall ItemSense, follow these steps:

  1. Ensure that it is not running:

    sudo docker ps

    If you see five containers listed like the following:

    CONTAINER ID        IMAGE                             COMMAND                  CREATED             STATUS              PORTS               NAMES
    92c5deb387df        isreg/is-mariadb:10.0.28          "docker-entrypoint.s…"   9 minutes ago       Up 8 minutes                            issupport_is-db_1
    f204d672c815        isreg/imc:1.0.454                 "/etc/sv/is-webapp/r…"   9 minutes ago       Up 8 minutes                            issupport_imc_1
    a72a57677292        nginx:1.10.3-alpine               "nginx -g 'daemon of…"   9 minutes ago       Up 8 minutes                            issupport_nginx_1
    9cb2f98c7b86        isreg/itemsense:master-84c42      "/sbin/my_init"          9 minutes ago       Up 8 minutes                            issupport_itemsense_1
    3f33714ace0a        isreg/is-rabbitmq-runit:3.5.7r3   "/sbin/my_init"          9 minutes ago       Up 8 minutes                            issupport_is-rabbit_1
    

    Then navigate to the installation directory of ItemSense (which is your install user's home directory where the itemsense-prod-3.yml file is located) and run:

    sudo docker-compose -f itemsense-prod-3.yml down

    Example output:

    Stopping issupport_is-db_1     ... done
    Stopping issupport_imc_1       ... done
    Stopping issupport_nginx_1     ... done
    Stopping issupport_itemsense_1 ... done
    Stopping issupport_is-rabbit_1 ... done
    Removing issupport_is-db_1     ... done
    Removing issupport_imc_1       ... done
    Removing issupport_nginx_1     ... done
    Removing issupport_itemsense_1 ... done
    Removing issupport_is-rabbit_1 ... done
    
  2. Check that nothing is listening on port 80, 3010, 443 or 5672.

    For example, this command should not show any output:

    sudo netstat -tlnp | grep ':80\W\|:3010\W\|:443\W\|:5672\W'

  3. Remove the containers directory and the itemsense-prod-3.yml file from the installation directory.

    sudo rm -rf containers/ itemsense-prod-3.yml

  4. Find the ItemSense docker images

    sudo docker images

    Example output:

    REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
    isreg/itemsense           master-84c42        f20712d51c12        2 days ago          760MB
    isreg/imc                 1.0.454             badc8d282f75        2 days ago          1.08GB
    isreg/is-rabbitmq-runit   3.5.7r3             c3b540cf1b9b        2 weeks ago         372MB
    nginx                     1.10.3-alpine       f94d6dd9b576        12 months ago       54MB
    isreg/is-mariadb          10.0.28             9624719527fa        16 months ago       340MB
    
  5. Remove the ItemSense docker images.

    sudo docker rmi IMAGEID

    Where IMAGEID is the IMAGE ID listed in your output for step 4 above. Example output:

    Untagged: isreg/is-mariadb:10.0.26
    Deleted: sha256:a508035a211d57375900f72245b393bffddbe2872137882e89ca9da2122b19bc
    Deleted: sha256:3072cba1a714165df54ed726529c4a2e0b404468ec8fa38ac5061c8e85079f40
    Deleted: sha256:efb58d19e00aeb18010fb9601c5f62f09cf610419476daaaed06ee9beae0470e
    Deleted: sha256:efabfc431d66b9b0a7859801c6dd2f7ba605641c7d05d34a43ec17f828873897
    Deleted: sha256:9ec14a42a06dfd7850171fb132321ecff0127d01301558bd600a1cd3125ee4df
    Deleted: sha256:3e0c9f3e156f9023da43a81a3895be481aaf033276f89ea43e38636b198ad1de
    Deleted: sha256:999296679db0f300dc45049abd06b5fb2fa36e9bf2bc6e36a41ac1113f20769b
    Deleted: sha256:c4ab196dba32b87c738314772804c0ec7de555813569eb9003c011a95b484960
    Deleted: sha256:9f97ab89b9ab488e27508fd6aa77b2708cff70e951b9b722f4829b9e4d04b4d3
    Deleted: sha256:a84d248cd3348a36c71d1225af4cc665e7df9e4942b65c20908d2d7503b5eb9e
    Deleted: sha256:aeb73b812583e391c7fe4c9c3eb844a5caa92ec279efc75e59b0fddb42e0d496
    Deleted: sha256:c541a7d71d798e2324344f2835d45516e5175d2ba328982e222f39d1df0f1bdf
    Deleted: sha256:eba5b35e8997700eef3477910f12fcad1785e546007c15522520f09a1a4abd08
    Deleted: sha256:247b8d8b7534f9957c42f44dcc2c53303baa1715be93d76d495543d747f895a3
    Deleted: sha256:2f71b45e4e254ddceb187b1467f5471f0e14d7124ac2dd7fdd7ddbc76e13f0e5
    

Clock Synchronization and NTP Configuration

The integrity of ItemSense's item data relies heavily on network clock synchronization. In order for readers to generate reliable reports, all of the readers being utilized in a job must be synchronized with each other, and with ItemSense.

In fact, if a reader's clock is too far out of sync with the ItemSense host's clock, that reader's reports will be ignored and a health event will be triggered (See Health API).

This means that it is necessary, prior to collecting tag data from ItemSense for the first time, to ensure that all of the RAIN RFID reader clocks are configured with an NTP server with which they should synchronize.

By default, all readers use DHCP to discover their NTP server. However, it is possible to add up to six statically configured NTP servers. Note that configuring the NTP server of the reader can't yet be done via ItemSense. Please refer to the Impinj RShell Reference Manual for more information on how to configure NTP on a reader. This guide can be found on support.impinj.com.

A recommended pattern is to set up the ItemSense host as an NTP server and specify it as the NTP server for each reader along with an appropriate backup NTP server if necessary. Then, the ItemSense server must synchronize its clock with another NTP server. This could be inside or outside the network.

Note: The instructions specified in the following two sections are specific to the Ubuntu Linux distribution. While the commands should work on a Linux distribution other than Ubuntu, it may be necessary to modify the commands slightly for your distribution.

Set up the ItemSense server as an NTP server

Perform the following steps to set up the ItemSense server as an NTP server:

  1. Log into the ItemSense server.

  2. Configure NTP. Use the following steps to edit the NTP configuration file.

    1. Open the NTP configuration file:

      sudo vi /etc/ntp.conf

    2. Add as many NTP servers as possible. A minimum of two is recommended. Servers are listed from top to bottom in order of priority.

      Example:

      server 0.ubuntu.pool.ntp.org
      server 1.ubuntu.pool.ntp.org
      server 2.ubuntu.pool.ntp.org
      server 3.ubuntu.pool.ntp.org
      
      server ntp.ubuntu.com
      
      server 127.127.1.0
      

      Note: The last server address (127.127.1.0) is used if the other servers aren't available. It tells NTP to synchronize with itself. This is required for an offline installation of ItemSense with no other NTP servers on the network.

    3. Allow other machines to synchronize with this one by adding or removing restrictions:

      restrict <network base address> mask <mask> <one or more flags>

      Example:

      restrict 10.200.35.0 mask 255.255.255.0 nomodify notrap
      

      This will allow servers on the 10.200.35.0 network to synchronize with this ItemSense server but deny modification (via the protocol) of the NTP settings. For details about this, see the manual page for ntp.conf.

    4. Save and exit the ntp.conf file.

  3. (Optional) Edit the DHCP configuration file to prevent Ubuntu from requesting NTP servers from DHCP. Use the following steps to edit the file.

    1. Open the DHCP configuration file:

      sudo vi /etc/dhcp/dhclient.conf

    2. Remove the ntp-servers parameter and its trailing comma from the request command:

      request subnet-mask, broadcast-address, time-offset, routers, domain-name, domain-name-servers, domain-search, host-name, dhcp6.name-servers, dhcp6.domain-search, netbios-name-servers, netbios-scope, interface-mtu, rfc3442-classless-static-routes, ntp-servers, dhcp6.fqdn, dhcp6.sntp-servers;
      
    3. Save the DHCP configuration file and exit.

    4. Remove the generated NTP DHCP configuration file if it exists:

      sudo rm /var/lib/ntp/ntp.conf.dhcp

  4. Set NTP to be allowed in the Ubuntu firewall:

    sudo ufw allow ntp

  5. Restart the NTP service:

    sudo service ntp restart

  6. Verify that ntpd comes back up:

    sudo pgrep ntpd

    There should be a response with a process ID number.

  7. Verify that NTP is working properly:

    ntpq -pn

    The command displays information about the peer servers specified in the NTP configuration file. Sample output is shown below. A * or + symbol at the beginning of the line indicates that the peer can be used for synchronization. If no peer is marked by a * or a +, NTP is not operating properly.

    Information displayed when NTP is working properly

Configure a reader to use the ItemSense server as its NTP server

Perform the following steps on the ItemSense server to configure a reader to use ItemSense as its NTP server:

  1. Log in to the reader RShell command prompt using SSH.

  2. Disable NTP:

    config network ntp disable

  3. (Optional) Prevent the reader from dynamically configuring its NTP servers through DHCP:

    config network ntp dynamicservers disable

  4. Delete any configured NTP servers:

    config network ntp delall

  5. Add the ItemSense IP address as a statically configured NTP server:

    config network ntp add <ItemSense IP>

  6. Re-enable NTP:

    config network ntp enable

  7. Check that the reader synchronizes (this can take a little while):

    show network ntp