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
- Refer Minified docker base images from Cisco repository section to find complete list of cisco hosted base os images.
- 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.
FROM devhub-docker.cisco.com/iox-docker/ir800/base-rootfs:latest
- 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.
- 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.
# 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.
#!/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.
FROM 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.
$ 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.
$ 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.
descriptor-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:
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.
bash$ 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.
bash$ 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://
Refer profiles and app management for more ioxclient details. Note: Here we are using default attributes for application activation.
bash$ 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.
bash$ ioxclient app console helloworld_app