IOx

Tutorial: Build sample PaaS type IOx app using Docker toolchain

In this tutorial, we will go through quick start guide on how to build a sample PaaS type application using docker development environment and package it to an IOx application.

Requirements

  • Supported development environment architecture for ioxclient tool
    • amd64
    • darwin_386 (MACOS 10)
    • darwin_amd64
    • linux_386
    • linux_amd64
    • windows_386
    • windows_amd64
  • Minimum Docker version 'Docker CE 17.05' (API 1.29). This tutorial utilizes the multistage build feature which is introduced in the docker CE 17.05.
  • If you are using the IOx SDE VM, upgrade the docker version to 17.05 or more. Refer the Docker documentation.
  • Docker daemon up and running

Setup Docker development environment for IOx

Refer this section to setup docker daemon on your development machine for authentication with Cisco hosted DevHub repository.

Create Dockerfile

  1. Refer Minified docker base images from Cisco repository section to find complete list of cisco hosted base os images.
  2. For a given platform and architecture, it is recommended to choose corresponding cisco provided docker base rootfs image from cisco devhub repositroy, as this will create minimal footprint for final IOx app package. Use the path in "Docker base image" column to pull docker images with tags as needed. For example, cisco hosted docker base os image with "latest" tag for IR829 platform can be pulled using the below command in Dockerfile.
Code Snippet
CopyFROM devhub-docker.cisco.com/iox-docker/ir800/base-rootfs:latest

  1. Refer this section to find out various packages hosted as part of cisco devhub repository and how to install those packages on top of cisco hosted docker image.

  2. Lets create a simple c based hello world application which just logs the string "Hello World from IOx App" every few seconds to a persistent log file named helloworld.log.

IOx exposes location of peristent log directory for apps via environment variable CAF_APP_LOG_DIR. Default location of this dir is /data/logs. Refer this section for more environment variables exposed by IOx to applications.

Printing to console can overflow the buffer and hang the target application. It is recommended not to print infinitely to console.

Copy below contents into a file called helloworld.py.

Code Snippet
Copyimport time

while True:
    print "helloworld"
    time.sleep(10)

Here is the Dockerfile you would need for x86_64 architecture, building hello world application and starting by default as part of system init script. Here we are utilizing multi stage docker builds to avoid including build tools in the final image and there by reducing the overall footprint of the IOx application. Refer this page for more details on multi-stage docker builds.

Copy below contents into a file called Dockerfile in the same directory as helloworld.py.

Code Snippet
CopyFROM devhub-docker.cisco.com/iox-docker/ir800/base-rootfs as builder
RUN opkg update
RUN mkdir -p /var/helloworld/
COPY helloworld.py /var/helloworld/

Build Docker image

Now build docker image named helloworld with version 1.0 using previously created dockerfile. Prepend sudo if the docker build command fails due to permission restrictions.

Code Snippet
Copy$ docker build -t helloworld:1.0 .

Create IOx package descriptor file

IOx package descriptor file contains metadata about the application, minimum resource requirements for running the application. Refer this section for more detailed description of various attributes and schema for package descriptor contents. Note: For LXC type application, kernel-version attribute is mandatory. Copy below contents into a file called package.yaml in the same directory as helloworld.c.

Code Snippet
Copydescriptor-schema-version: "2.4"

info:
  name: hello world 
  description: "Hello world PaaS type application"
  version: "1.0"
  author-link: "http://www.cisco.com"
  author-name: "Cisco Systems"

app:
  type: paas
  cpuarch: x86_64

  resources:
    profile: custom
    cpu: 200
    memory: 64
    disk: 2

    network:
      -
        interface-name: eth0
  # Specify runtime and startup
   startup:
    runtime: python
    runtime-version: 2.7
    target: app.py

NOTE: if multiple network interfaces are required, the below package.yaml syntax is used:

Code Snippet
Copy    network:
      -
        interface-name: eth0

      -
        interface-name: eth1

      -
        interface-name: eth2

Create final IOx application package

Download and install latest version of ioxclient for your development environment from this location. Setup ioxclient device profile by configuring device IP, credentials and SSH port.

Code Snippet
Copybash$ ioxclient profiles create

Use below ioxclient command to build final IOx application package named package.tar. Need to pass same docker image name and version that has been previously used to build the image. Prepend sudo if the ioxclient command fails due to permission restrictions.

Code Snippet
Copybash$ ioxclient docker package helloworld:1.0 .

Install the Cartridges

Download the cartridges from the Downloads and install them using ioxclient. Install Yocto 1.7.2 Base Rootfs Cartridge and Python 2.7.3 Language Runtime Cartridges.

Code Snippet
Copybash$ ioxclient  cartridge install <cartridge>

Deploy/Activate/Start the application

Now you can deploy the application onto a physical or virtual IOx device using either of the clients ioxclient or Local Manager or Fog Director. You can access device Local Manager UI using the URL path https://:8443. Lets use ioxclient to deploy this application to a device. Execute below ioxclient commands to setup device profile, install, activate and start the application. Refer profiles and app management for more ioxclient details. Note: Here we are using default attributes for application activation.

Code Snippet
Copybash$ ioxclient app install helloworld_app package.tar

bash$ ioxclient app activate helloworld_app

bash$ ioxclient app start helloworld_app

Verify the application is running

Now lets console into the application and confirm that application is running successfully. Use below ioxclient command to console into the application. Login as root into the application and password is not required.

Code Snippet
Copybash$ ioxclient app console helloworld_app
Next