IOx

Tutorial: Build sample LXC type IOx app using Docker toolchain

In this tutorial, we will go through quick start guide on how to build a sample lxc type application using docker development environment and package it to an IOx application. For more details on what are the different types of IOx application supported, refer this section.

Requirements

  • The command "ioxclient docker package" when used to package for lxc type app, requires linux development environment (linux_386, linux_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. Let's 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.c.

c
Copy# include <stdio.h>
# include <stdlib.h>
# include <unistd.h>
# include <string.h>
# include<signal.h>

static FILE *fp = NULL;
static char *fullpath = NULL;

static void sig_handler(int signo)
{
  if (signo == SIGINT || signo == SIGKILL || signo == SIGTERM) {
      printf("received signal = %d\n", signo);
      if (fp)
          fclose(fp);
      /* use fullpath */
      if (fullpath)
          free(fullpath);
      exit(0);
  }
}

int main()
{
    signal(SIGINT, sig_handler);
    signal(SIGKILL, sig_handler);
    signal(SIGTERM, sig_handler);
    char* log_dir = getenv("CAF_APP_LOG_DIR");
    size_t dir_len = strlen(log_dir);
    const char *logfile = "helloworld.log";
    /* + 2 because of the '/' and the terminating null character */
    fullpath = malloc(dir_len + strlen(logfile) + 2);
    if (fullpath == NULL) {
        return -1;
    }
    sprintf(fullpath, "%s/%s", log_dir, logfile);
    //sleep(10);
    fp;
    fp = fopen(fullpath, "w+");
    while(1) {
        fprintf(fp, "Hello World from IOx App!!!\n");
        sleep(2);
        fflush(fp);
    }
    fclose(fp);
    /* use fullpath */
    free(fullpath);

}

For LXC type of application, we need to start the application as part of system init script. Hence we need to add an application init script to /etc/init.d and configure to start automatically. Copy below contents into a file called init_app.sh in the same directory as helloworld.c.

bash
Copy#!/bin/sh
# chkconfig: 123 69 68
# description: Hello World application init script

# Source function library.
. /etc/init.d/functions

start() {
    echo -n "Start hello world application"
    source /data/.env
    /var/helloworld/helloworld &
}

stop() {
    kill -9 `pidof helloworld`
}

case "$1" in 
    start)
       start
       ;;
    stop)
       stop
       ;;
    restart)
       stop
       start
       ;;
    status)
       # code to check status of app comes here 
       # example: status program_name
       ;;
    *)
       echo "Usage: $0 {start|stop|status|restart}"
esac

exit 0

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.c.

Code Snippet
CopyFROM devhub-docker.cisco.com/iox-docker/ir800/base-rootfs as builder
RUN opkg update
RUN opkg install iox-toolchain
RUN mkdir -p /var/helloworld/
COPY helloworld.c /var/helloworld/
WORKDIR /var/helloworld/
RUN gcc helloworld.c -o helloworld

FROM devhub-docker.cisco.com/iox-docker/ir800/base-rootfs
RUN mkdir -p /var/helloworld/
COPY --from=builder /var/helloworld/helloworld /var/helloworld
RUN chmod +x /var/helloworld/helloworld
COPY init_app.sh /etc/init.d/
RUN chmod +x /etc/init.d/init_app.sh
RUN update-rc.d init_app.sh defaults

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 .

Verify application dependencies in docker image - optional

You can verify if the docker image now has all the application's dependant libraries or modules by running docker container locally in developement environment. Execute below command to run docker container and getting access to shell session inside the container. For this tutorial, make sure that application binary is copied under /var/helloworld/ directory and init script init_app.sh is copied under /etc/init.d/ dir.

Code Snippet
Copy$ docker  run -it helloworld:1.0 /bin/sh

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. Copy below contents into a file called package.yaml in the same directory as helloworld.c.

NOTE:

  • "rootfs" is always "rootfs.img" for docker built apps.
  • "target" is the boot-up script. This can be an OS boot init exec or a user customized startup script.
Code Snippet
Copydescriptor-schema-version: "2.4"

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

app:
  type: lxc
  cpuarch: x86_64
  resources:
    profile: custom
    cpu: 200
    memory: 64
    disk: 2

    network:
      -
        interface-name: eth0
  # Specify runtime and startup
  startup:
    rootfs: rootfs.img
    target: /sbin/init

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. Refer to Section "Configuring ioxclient" in "ioxclient Reference" for details.

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 .

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 or https://:443. 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 by logging the string at /data/logs/helloworld.log. 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