IOx

Overview

This document describes how to use docker tooling to develop a C based application which is packaged as a Container image. The application contains a simple C program that prints the current system time at 1 second intervals - 10 times.

Goals

Demonstrate various development tasks and concepts to implement a C based Container application package using docker tooling.
Application build process using docker build environment.

Sample Code

This sample application code is maintained here.

Clone this repo and use branch master. Find the application under directory 'simple-c-app'.

Code Snippet

Copy$ git clone https://github.com/CiscoIOx/docker-demo-apps.git -b master
$ cd docker-cpp-app/simple-c-app

Some parts of the code may be reproduced in this document to give more context. But always use the above git repo and branch for the latest code.

Procedure Overview

Implementing a simple C application
Creating a docker image to setup the build environment
Run the image locally and compile C application
Creating a docker image with application binary contents
Testing the application locally using docker tools
Creating an IOx application package from the docker image
Deploying and testing on the target platform

Procedure

This section describes above steps with more details.

Before going through the tutorial, get familiar with cisco provided artifacts for an IOx app development.

Here, we have used 2 Dockerfiles for creating a C application package:

One Dockerfile for creating a docker image for the build environment. This is used for compiling a C application. This Dockerfile basically pulls a docker base image and installs the toolchain.
Other Dockerfile is for creating a docker image for deployment. This Dockerfile basically pulls a docker base image and copies the application binaries.

Note that the application examples are demonstrated for IR800 platform, but the same procedure will be applicable for all other supported IOx platforms. Developer needs to use the right docker base image as per the IOx platform. Refer for images supported platforms & corresponding base images

Implementing a simple C application

Writing a simple C application which prints the current system time at 1 second intervals - 10 times.

Creating a project directory

Code Snippet

Copy$ mkdir simple-c-app
$ cd simple-c-app

Writing a C application

Here is the sample code:

Code Snippet

Copy$ mkdir -p dev/src
$ cd dev/src
$ vi display-date-time.c

/*
 * Sample code for basic C app which prints the current system date and time
 * for 10 times with 1 sec delay
 */

# include <stdio.h>
# include <time.h>

/*
 * Display the current system date and time
 */
void display_date_time()
{
    time_t tvar;
    /* Returns the current time of the system as a time_t object
     * which is usually time since an epoch, typically the Unix epoch
     */
    time(&tvar);
    /* Print the date and time after converting a time_t object
     * to a textual representation using ctime()
     */
    printf("Today's date and time : %s",ctime(&tvar));
}

/*
 * Print the current system date and time
 */
void main()
{
    /*  
     * Print the current system date and time for 10 times with 1 sec delay
     */
    int i = 0;
    while(i<10)
    {   
        /* Call the function to display the date and time */
        display_date_time();
        /* Sleep for a second for each iteration */
        sleep(1);
        i++;
    }   
}

Writing a loop application

Docker type applications are not based on /sbin/init to make the container alive and to start the init scripts. So, we need to use some loop application which will run in the background to make the container alive. This will be used in a Dockerfile as an application entry point. You will understand more details in the subsequent sections how to use this loop application.

Here is a simple loop application:

Code Snippet

Copy$ vi loop_app.c
/*
 * Sample code for basic C app which loops forever
 */

# include <stdio.h>
# include <unistd.h>

/*
 * Create a loop
 */
int main()
{
    /* loop */
    while(1)
    {   
        /* Sleep for a second for each iteration */
        sleep(10000);
    }
    return 0;
}

$ ls
display-date-time.c  loop_app.c
$

Note that you can also use a simple shell script to create a loop app instead of using this C based loop application.

Creating a docker image to setup the build environment

Write a Dockerfile

This Dockerfile does the following tasks:

Pulls the docker base image
Installs the docker toolchain to compile the C application

Here is a Dockerfile:

Code Snippet

Copy$ cd simple-c-app/dev
$ vi Dockerfile
FROM devhub-docker.cisco.com/iox-docker/ir800/base-rootfs

COPY src /opt/src/
RUN opkg update
RUN opkg install iox-toolchain
RUN opkg install gdb

Creating a docker image

Now let us build an image from this Dockerfile.

Code Snippet

Copy$ docker build -t ir800-tools .

Check if the image is successfully created using following command:

Code Snippet

Copy$ docker images
REPOSITORY                                             TAG                 IMAGE ID            CREATED             SIZE
ir800-tools                                            latest              68edd7af2f74        2 minutes ago       156.9 MB
$

Run the image locally and compile C application

Let us run the image locally to compile C application.

Note that here we are volume mounting the directory (-v ${PWD}/apps:/opt/share) from host pc in to docker container. This will help to get the compiled binary files to host machine.

Code Snippet

Copy$ cd simple-c-app/
$ docker run -v ${PWD}/apps:/opt/share -it ir800-tools /bin/sh
sh-4.3# cd /opt/src/
sh-4.3# ls -l
-rw-r--r--    1 root     root           885 Oct 14 18:42 display-date-time.c
-rw-r--r--    1 root     root           209 Oct 27 20:42 loop_app.c
sh-4.3# which gcc
/usr/bin/gcc
sh-4.3# ls -l /usr/bin/gcc
lrwxrwxrwx    1 root     root            21 Oct 14 22:17 /usr/bin/gcc -> x86_64-poky-linux-gcc
sh-4.3# 
sh-4.3# gcc display-date-time.c -o display-date-time   
sh-4.3# ls -l
-rwxr-xr-x    1 root     root         11461 Oct 27 22:47 display-date-time
-rw-r--r--    1 root     root           885 Oct 14 18:42 display-date-time.c
-rw-r--r--    1 root     root           209 Oct 27 20:42 loop_app.c
sh-4.3# gcc loop_app.c -o loop_app   
sh-4.3# ls -l
-rwxr-xr-x    1 root     root         11461 Oct 27 22:47 display-date-time
-rw-r--r--    1 root     root           885 Oct 14 18:42 display-date-time.c
-rwxr-xr-x    1 root     root         10881 Oct 27 22:47 loop_app
-rw-r--r--    1 root     root           209 Oct 27 20:42 loop_app.c
sh-4.3# cp display-date-time ../share/
sh-4.3# cp loop_app ../share/
sh-4.3# cd ../share/
sh-4.3# pwd
/opt/share
sh-4.3# ls -l
-rwxr-xr-x    1 root     root         11461 Oct 27 22:48 display-date-time
-rwxr-xr-x    1 root     root         10881 Oct 27 22:48 loop_app
sh-4.3# exit
exit
$
$ ls -l apps/
total 24
-rwxr-xr-x 1 root root 11461 Oct 27 15:48 display-date-time
-rwxr-xr-x 1 root root 10881 Oct 27 15:48 loop_app

Creating a docker image with application binary contents

Now we are ready with the application binaries. Next step is creating a docker image with these application binaries.

Write a Dockerfile

This Dockerfile does the following tasks:

Pulls the docker base image
Copies the application binary contents on to base image
Specifies the application entry point

Here is a Dockerfile content:

Code Snippet

Copy$ cd simple-c-app/
$ vi Dockerfile
FROM devhub-docker.cisco.com/iox-docker/ir800/base-rootfs

COPY apps /opt/apps/
RUN opkg update
CMD ["/opt/apps/loop_app"]

Creating a docker image

Now let us build an image from this Dockerfile.

Code Snippet

Copy$ docker build -t ir800-base-image .

Check if the image created successfully

Code Snippet

Copy$ docker images
REPOSITORY                                             TAG                 IMAGE ID            CREATED             SIZE
ir800-base-image                                       latest              f30f597cf282        34 seconds ago      21.89 MB
$

Testing the application locally using docker tools

Code Snippet

Copy$ docker run -it ir800-base-image /bin/sh
/ # cd /opt/apps/
/opt/apps # ls -l
-rwxr-xr-x    1 root     root         11461 Oct 27 22:48 display-date-time
-rwxr-xr-x    1 root     root         10881 Oct 27 22:48 loop_app
/opt/apps # ./display-date-time 
Today's date and time : Thu Oct 27 22:54:04 2016
Today's date and time : Thu Oct 27 22:54:05 2016
Today's date and time : Thu Oct 27 22:54:06 2016
Today's date and time : Thu Oct 27 22:54:07 2016
Today's date and time : Thu Oct 27 22:54:08 2016
Today's date and time : Thu Oct 27 22:54:09 2016
Today's date and time : Thu Oct 27 22:54:10 2016
Today's date and time : Thu Oct 27 22:54:11 2016
Today's date and time : Thu Oct 27 22:54:12 2016
Today's date and time : Thu Oct 27 22:54:13 2016
/opt/apps # 
/opt/apps # exit

Package descriptor file

Package descriptor file specifies requirements for the application. For docker type of applications, creating a package descriptor file is optional. ioxclient creates a default package descriptor file while creating IOx docker application package. If the developer want to add custom entries in a package descriptor file, he can add those entries using docker's LABEL directive. Ioxclient uses those labels, add it in a package descriptor file during creation of an IOx docker application package.

Refer ioxclient page to learn how to use docker Label's and package.yaml.

Here is a sample application descriptor (package.yaml) file looks like:

Note: If you are using application descriptor file for non x86 architecture, Refer the docker images table for appropriate value of "cpuarch" in yaml file

Ex: For ie4k platform use the 'cpuarch' as 'ppc' in following yaml file

Code Snippet

Copy$ vi package.yaml

descriptor-schema-version: "2.2"

info:
  name: SampleNodeApp
  description: "Simple Docker Style C Application"
  version: "1.0"
  author-link: "http://www.cisco.com"
  author-name: "Cisco Systems"

app:
  # Indicate app type (vm, paas, lxc etc.,)
  cpuarch: "x86_64"
  type: docker
  resources:
    profile: c1.small

    network:
      -   
        interface-name: eth0
        ports:
            tcp: [8000]
            udp: [10000]

# Specify runtime and startup
  startup:
    rootfs: rootfs.tar
    target: ["/opt/apps/loop_app"]

Few things to notice:

Descriptor schema version is 2.2. This is the minimum version that supports docker style apps.
The required port (8000) to be opened is specified under network->ports.
rootfs.tar is the name of the file containing the docker image (output of docker save command). More details in the next sections.
Command to be run when starting up the app is ["/opt/apps/loop_app"]. Note that here loop_app is a loop application binary which is used to make the container alive. This is because container is not based on /sbin/init so that application will stop if we don’t use the loop application.

Creating an IOx application package

Now that we have created the required docker image (ir800-base-image), it is time to create an IOx application package from these artifacts.

ioxclient (>= 1.4.0) provides a convenience command that generates an IOx application package from a docker image and package.yaml file.

Refer this page for ioxclient usage: ioxclient

Create an empty directory ex. 'app_package' and execute the ioxclient command in this directory

Make sure the profile for target platform is created and activated before creating package

Let us use this command.

Code Snippet

Copy$ mkdir app_package
# ls
app_package  apps  dev  Dockerfile
$ cd app_package/
$ ioxclient docker package -a ir800-base-image .
Currently active profile :  default
Command Name: docker-package
No package type specified, but auto flag is set
cpu arch is x86, generating docker app x86_64
Generating docker style app
The Image is better left in it's pristine state
Parsing Package Metadata file :  /home/<user>/projects/test_sde/simple-c-app/app_package/.package.metadata
Wrote package metadata file :  /home/<user>/projects/test_sde/simple-c-app/app_package/.package.metadata
Checking if package descriptor file is present..
Validating descriptor file /home/<user>/projects/test_sde/simple-c-app/app_package/package.yaml with package schema definitions
Parsing descriptor file..
Found schema version  2.2
Loading schema file for version  2.2
Validating package descriptor file..
File /home/<user>/projects/test_sde/simple-c-app/app_package/package.yaml is valid under schema version 2.2
Created Staging directory at :  /tmp/875893130
Copying contents to staging directory
Checking for application runtime type
Couldn't detect application runtime type
Creating an inner envelope for application artifacts
Excluding  package.tar
Generated  /tmp/875893130/artifacts.tar.gz
Calculating SHA1 checksum for package contents..
Parsing Package Metadata file :  /tmp/875893130/.package.metadata
Wrote package metadata file :  /tmp/875893130/.package.metadata
Root Directory :  /tmp/875893130
Output file:  /tmp/737154401
Path:  .package.metadata
SHA1 : 66bfd809f7e0eb8da0cab18e8d9b53eb2e7d1938
Path:  artifacts.tar.gz
SHA1 : 3ae9e6468bb934d26fa840ca250398907c1c5751
Path:  package.yaml
SHA1 : 96a1484d1a6c505cc2fad0c2f7ec8abba57ce342
Generated package manifest at  package.mf
Generating IOx Package..
Package docker image ir800-base-image at /home/<user>/projects/test_sde/simple-c-app/app_package/package.tar
$

The package.tar is an IOx application package that can be used to deploy on an IOx platform.

Here is a simple-c-app directory structure on Host PC after successful building of IOx application package:

Code Snippet

Copy$ cd simple-c-app
$ tree 
.
├── apps
│   ├── display-date-time
│   └── sample_app
├── app_package
│   ├── package.tar
│   └── package.yaml
├── dev
│   ├── Dockerfile
│   └── src
│       ├── display-date-time.c
│       └── loop_app.c
└── Dockerfile

4 directories, 8 files
$

Deploying and testing on the target platform

Ensure that your target platform supports docker style applications. Refer to Platform Matrix for details about your platform. This tutorial uses IR829 as the target IOx platform.

We will use ioxclient to demonstrate deployment and lifecycle management of this application. You can do the same using Local Manager or Fog Director.

Add your device to ioxclient

Code Snippet

Copy$ ioxclient  profiles create
Active Profile :  default
Enter a name for this profile : ir800demo
Your IOx platform's IP address[127.0.0.1] : <IOx device IP>
Your IOx platform's port number[8443] :
Authorized user name[root] : root
Password for root :
Local repository path on IOx platform[/software/downloads]:
URL Scheme (http/https) [https]:
API Prefix[/iox/api/v2/hosting/]:
Your IOx platform's SSH Port[2222]: 2022
Activating Profile  ir800demo

Install the app on the target platform

Code Snippet

Copy$ ioxclient app install demoapp app_package/package.tar
Currently active profile :  ir800demo
Command Name: application-install
Saving current configuration
Installation Successful. App is available at : https://<IOx device IP>:8443/iox/api/v2/hosting/apps/demoapp 
Successfully deployed

Activate the app

Code Snippet

Copy$ ioxclient app activate demoapp
Currently active profile :  ir800demo
Command Name: application-activate
App demoapp is Activated

Start the app

Code Snippet

Copy$ ioxclient app start demoapp
Currently active profile :  ir800demo
Command Name: application-start
App demoapp is Started

Access the app console

Code Snippet

Copy$ ioxclient app console demoapp
Currently active profile :  ir800demo
Command Name: application-console
Saving current configuration
Console setup is complete..
Running command : [ssh -p 2022 -i demoapp.pem appconsole@<IOx device IP>]
The authenticity of host '[<IOx device IP>]:2022 ([<IOx device IP>]:2022)' can't be established.
ECDSA key fingerprint is 54:a3:8c:f1:2d:69:1a:bf:da:8e:1a:8f:a2:62:bb:dd.
Are you sure you want to continue connecting (yes/no)? yes
/ # cd /opt/apps
/opt/apps # ls
display-date-time  loop_app
/opt/apps # ./display-date-time
Today's date and time : Thu Oct 27 23:50:28 2016
Today's date and time : Thu Oct 27 23:50:29 2016
Today's date and time : Thu Oct 27 23:50:30 2016
Today's date and time : Thu Oct 27 23:50:31 2016
Today's date and time : Thu Oct 27 23:50:32 2016
Today's date and time : Thu Oct 27 23:50:33 2016
Today's date and time : Thu Oct 27 23:50:34 2016
Today's date and time : Thu Oct 27 23:50:35 2016
Today's date and time : Thu Oct 27 23:50:36 2016
Today's date and time : Thu Oct 27 23:50:37 2016
/opt/apps # 
/opt/apps # exit

Summary

As part of this tutorial we saw:

Using docker tools and base image to build a C app.
Packaging a docker image into an IOx application package.
Deploying this package to an IR800 router and testing the application functionality.