Five easy ways to install AGILE (running the default stack)

From AGILE IoT Wiki
Jump to: navigation, search

Prerequisites

Thanks to its dockerized design, AGILE prerequisites are very simple: docker, docker-compose, git

  • to run AGILE: docker version 1.10.0 (or later) and docker-compose version 1.10.0 (or later)
  • to build AGILE from source: docker version 17.05.0 (or later) and docker-compose version 1.10.0 (or later). Building on earlier versions of docker is also possible after disabling the 2-stage build process in dockerfiles.
  • In our examples git is also used. However, this can be circumvented with the direct download of the compose stack description file (https://raw.githubusercontent.com/Agile-IoT/agile-stack/master/docker-compose.yml) or compressed code archives.

Installation

AGILE supports different use cases, and correspondingly several installation methods:

  1. resinOS-based gateway with local management
  2. Raspbian based standalone gateway
  3. Docker and docker-compose based installation
  4. resin.io and resinOS-based remotely-managed option for scaling
  5. Building and installing from source


resinOS based gateway with local management

Select this option if a robust OS is required, one of the supported GW platforms are used, but remote cloud based management is not needed. AGILE will be running on the gateway machine, but docker-compose will be run from a local management machine. The management machine can be any PC, it is only used to configure the GW at deployment, and later, if necessary, to update services.

npm i -g resin-cli
  • (optional) Configure the dowloaded SD image (only required if connecting to WiFi)

resin local configure resin.img
  • Burn image to microSD (we recommend Etcher.io)
  • Clone agile-stack

git clone https://github.com/agile-iot/agile-stack && cd agile-stack
  • Configure the stack by creating and editing the .env file
cp .env.example .env
  • After powering on the GW with the microSD card, Initialise AGILE

docker-compose up -d

Raspbian based standalone gateway

This installation method is only available for Raspberry Pi (1, 2, 3, 3+), this type of deployment is useful for those who are used to Raspbian, would like to run other services next to AGILE, and are not afraid of logging in to the gateway with SSH.

  • download a Raspbian based SD image from AGILE SD images.
  • Burn image to microSD (we recommend Etcher.io)
  • Connect the Pi to your LAN. In case you use WiFi, edit files directly on SD card to add credentials. You can add credentials to wpa_supplicant.conf on the boot partition following [this guide].
  • Insert the SD in the Pi and power it up
  • Connect to http://agilegw.local:8000
  • If you LAN does not support Bonjour (i.e. `ping agilegw.local` is not working), further steps are needed to access the GW:
    • Find the actual IP of the gateway device. Depending on the configuration of your (W)LAN, you can get this from your router's management interface or using the nmap program. You can also get it by connecting a keyboard and a screen directly to the Pi.
    • Connect with SSH to your gateway with user:pi and password:agileiot
    • Update AGILE_HOST variable in the agile configuration (/home/pi/agile-cli/agile.conf) with an accessible IP address or domain name of the gateway, and restart AGILE by issuing the (agile restart) command.

Docker and docker-compose based installation

Useful for any other platform not supported by the above methods (e.g. Linux based PCs, OS X), or when deploying AGILE code on an existing server. It is also useful for testing the AGILE stack without a dedicated gateway (i.e. on a laptop).

  • clone the AGILE Stack
git clone https://github.com/Agile-IoT/agile-stack.git
  • Clone the AGILE CLI (Command Line Interface)
git clone https://github.com/Agile-IoT/agile-cli.git
  • Set up the CLI
cd agile-cli
cp agile.config.examples/agile.config.local agile.config
  • (optional) customize the configuration, e.g. by setting the AGILE_ARCH to x86_64
  • (optional) install the AGILE CLI
sudo ./agile install
  • Start agile
./agile start

For more details, see the AGILE CLI Readme

resin.io and resinOS-based remotely-managed option for scaling

Below we provide a complete guide for deploying a managed version of your gateway fleet. This is useful for large-scale deployments and includes management, monitoring and remote update features. It is recommended when Cloud-based management of your AGILE devices is required. We will use a free resin.io account for this. Resin.io brings the benefits of Linux containers to the IoT, allowing you to develop iteratively, deploy safely, and manage at scale.

Note: A Raspberry Pi 3 B or B+ device is recommended.

1 resin.io homepage

  • You will need to 'Sign Up' for a free account

2 Sign up and login at resin.io

  • Here is your resin.io dashboard (of course, yours will likely be lacking any applications at this point -- we will change that in a bit!)

3 resin dashboard

  • Create a new application by giving it a name (without spaces), selecting the device in which you will deploy the AGILE stack (in our case a Raspberry Pi 3 -- you can have as many devices of this type which will automatically pick up your code changes, deploy them, and be managable and monitored through the Cloud) and optin in for the 'Starter' application type

4 Create new starter application

  • Now let's add our first device by clicking 'Add device'. At this point, also make sure that you have the device ready to be plugged in, and separately, an SD card with enough space (usually 8GB+) which you can plug onto your Mac or PC

5 Add device to your resin application

  • Time to select how your target device(s) will connect to the Internet to contact the resin.io servers through its secure VPN connection. Ethernet or stable WiFi are recommended (if your WiFi has issues, you can always fall back to Ethernet as you see below). The AGILE stack comprises a fair few microservices and will take a while (up to a couple hours) particularly on patchy networks or low-bandwidth networks. You don't need to change anything else on this screen however if you prefer to (also) use the devices for development and enable local SSH access, you can opt-in for the Development image instead of the Production image. Click "Download resinOS" and you are good to go

6 Define resinOS image settings such as WiFi SSID

  • If you are used to 'burning' images on SD cards for use in Pi's or embedded devices, you probably are used to the pain. Instead of trying your luck with "dd", download Etcher from https://etcher.io for your platform, install it and open it

7 Download Etcher from etcher.io

  • Etcher will automatically identify the type of image that needs burning, it will auto-select your SD card (which you should insert on your Mac/PC reader at this point) and allow you to do a zero-effort SD card burn, with verification, within seconds

8 Use Etcher to burn resinOS managed image to SD card

  • Your resin.io-enabled resinOS image that is configured for your new application and network is ready. Plug the SD card into your Raspberry Pi, plug an Ethernet cable that is connected to the Internet (if you want a wired connection -- otherwise ensure of course that you are either using a Pi that has WiFi or have plugged in a compatible WiFi dongle into one of its ports) and power up the device. Within a few seconds, the device should appear on your resin.io dashboard like you see below

9 Plug in your Raspberry Pi 3 and watch it appear in the dashboard

  • You will now need to go to your command prompt (CLI), Terminal on Mac and do the following...

Note: We are assuming that your system has Git installed, and that you are familiar with the above process from the previous guides in this Wiki -- but each step is still explained briefly. Clone the AGILE IoT Stack from our remote repository:

git clone git@github.com:Agile-IoT/agile-stack.git

Enter the repository folder:

cd agile-stack

Go back to your resin.io dashboard, and at the top-right find the textbox with your git remote. Use the copy key to copy all of it and paste it in the terminal. An example is provided below. This change is important. You will not be able to add another account's 'remote'...

git remote add resin [YOUR_RESIN_USERNAME]@git.resin.io:[YOUR_RESIN_USERNAME]/[YOUR_RESIN_APPLICATION_NAME].git

As the multi-container version of the AGILE IoT Stack differs slightly from our master branch, we need to change to the resin-multi branch like so:

git checkout resin-multi

Time to copy the sample configuration file (.env.example) to our current configuration (.env) with the below command (you won't need to change this if you are using ARM architecture, i.e. a Raspberry Pi device):

cp .env.example .env

Always good to locally commit our changes with the below two commands:

git add .
git commit -m 'config update'

This command will initiate the deployment process. Note the flag (-f):

git push resin -f resin-multi:master

  • At this point, your command prompt will show a remote compilation/build process triggered so that your code is ready to be pushed to all devices connected with this resin.io application. This should take a few seconds and accesses all separate microservices through their remote repositories

10 Push to your application resin repository

  • The unicorn will indicate the process was successful. The last two steps can be repeated for any further changes to the Stack that you might want to apply locally. Just pull the latest stack with git pull (or apply your own changes) and push to resin again

11 Push complete

  • Back on the resin.io dashboard, you should be able to see the provisioning process triggered. There is a lot happening at this point (as you will also be able to see in the logs). We suggest you grab a coffee while all microservices are deployed to the device(s), booted, and communicating with each other

12 Watch the provisioning process in your device view

  • After a few sips (or perhaps a few more depending on your device, network type and connection quality...) your AGILE IoT Gateway is up and accessible through the network. Have a look around, from the ability to individually access containers via SSH remotely (it doesn't matter if your device is deployed on the other side of the world...) to monitoring its logs, enabling public access (securely via VPN) to enabling a public URL endpoint for accessing the AGILE Stack (we are working on making sure more AGILE services are accessible through this means!)

13 Granular control of all AGILE microservices

Building and installing from source

  • Clone agile-dev
git clone https://github.com/Agile-IoT/agile-dev.git
  • Configure agile-dev for local build
cd agile-dev/agile-stack
cp .env.example .env

Change the AGILE_HOST variable to localhost and disable the DOCKER_HOST variable. If on x86_64, update the AGILE_HOST variable as well.

  • Build
 everything
docker-compose build
  • Start the AGILE framework
dcker-compose up -d

For more details, see the https://github.com/Agile-IoT/agile-dev/blob/master/README.md