Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 15 Next »

1. Introduction

With the i-PRO Camera SDK that supports Container AdamApp, you can run containers with various configurations in the i-PRO camera by describing the app configuration in a Docker compose configuration file. This allows you to develop camera application as docker application, and if you have already developed a Docker container running on PC or another device, you can easily port it to camera. This document explains how to create a Container AdamApp with multiple containers using the docker_multi_images sample app included in the SDK as an example.

2. Overview

2.1 Design docker container architecture

Please refer here for information on which to choose between the existing AdamApp, Container AdamApp and Cotainer AdamApp for Azure IoT Edge.

The container configuration depends on Docker compose configuration file (docker-compose.yaml).

Multiple containers also work by specifying multiple service names in the file.

Following diagram shows the difference between the conventional AdamApp(not the docker) and the example of Container AdamApp.

The above is the example of multiple containers within one camera application (one binary).

There are some options and the following are guidelines for selecting the architecture.

No.

Use Cases

Configure the app

Conceptual diagram

1

Port existing docker application for AI processing on PC or another device to i-PRO camera.

One app with one container.

Process to get video image and AI processing need to be replaced by ADAM API

2

Convert exiting AdamApp (conventional i-PRO camera app) to Container AdamApp

An existing app is simply containerized, creating one app with one container.

3

Port existing docker application without AI processing on PC or another device to i-PRO camera.

One app with two containers.

Main container for management by firmware and Sub container for existing container application.

In case existing docker application consist of multiple containers including third party OSS, those will be Sub container 1 and Sub container 2.

4

Port two existing docker applications that has no relation each other.

Two apps

5

Multiple containers that both need to use the ADAM API

Two apps

2.2 Configuration for multiple containers

The sample application “docker_multi_images” is the reference, especially for use case No.3 in Chapter 2.1. This sample app consists of two Docker images.

  • docker_multi_images image
    This is for starting/stopping the application by camera firmware and for internal keep-alive between application and firmware. In this document, it is called the "main image." Also, the container generated from this image is called the "main container." The sample application only runs an event loop and waits. It should be is built using i-PRO CAMERA SDK.

  • web image
    This image is based on the lightweight version of nginx published on DockerHub, with only the default configuration file (default.conf) replaced. This document calls it a "subimage." Also, a container generated from this image is called a "subcontainer." nginx's TCP 80 port is associated to TCP 8081 for http access from external device. It is necessary to build as docker image before creating Container AdamApp using i-PRO CAMERA SDK.

If you want to run an existing container on an i-PRO camera, you can add the docker_multi_images for management from the camera, and the existing container can be run on the camera with minimal changes.

2.3 Porting Considerations

When running an existing container on an i-PRO camera, you need to consider the following three points:

  • Camera resources RAM/ROM/CPU

  • Data storage

  • i-PRO camera security policy

  • Is only one container enough for using ADAM API?

2.3.1 RAM / ROM / CPU resources

Please see here for resources for CV52 cameras that support docker capabiility.

Please make sure the app you are porting can work within these limits.
RAM/CPU limits are enforced by cgroups. If RAM usage exceeds the limit, the app will be killed by the OOM Killer.

2.3.2 About our security policy

Followings are important points when porting. For more information on Container AdamApp's security policy, please see here.

  • Containers cannot be run with root privileges. The app runs in the camera with user privileges of uid 1000, gid 1000.

  • The container is mounted read only.
    You cannot write to the container. If an existing app is writing to the container, it will need to write to a tmpfs(RAM) for temporary data, or to a separate mounted volume for persistent data.

  • Options that relax security, such as --previledged, cannot be used.

  • Docker images cannot be pulled from an external container registry directly from within the camera. The required docker images must be pulled and built on the development PC and included in the Container AdamApp(ext file).

2.3.3 Restrictions on using ADAM API

If Container AdamApp contains multiple containers, the ADAM API can only be used from the main container, not from sub containers.

It is better that main image has feature related to camera functions and sub images have features not related to camera functions. Chapter 3.4 shows how to share the data between main and sub images.

3. Development Procedure

3.1 Create a project

Preparing the project directory

Copy iPRO_CAMERA_SDK/src/adamapp/docker_multi_images included in the SDK sample app and rename it to any name. It is recommended to use lowercase for all directory names to make it easier to understand if the directory name matches the image name of the main image.

Convert the string "docker_multi_images" contained in container/docker-compose.yaml to the name of the main image in one go.

There is no need to change the main image binary (multiImages). If you want to change it, you will also need to edit Configuration.txt and Makefile.

App information description

Open configuration.txt and edit the following items.

  • App Version Name
    This is the version information displayed on the camera browser management screen. It is easy to understand if you match it with the tag name of the main image.

  • App Name
    This will be the app name displayed on the camera browser management screen. It can be written in any language.

  • Resource Related Information
    Describes the ROM/RAM/CPU usage (declared value) used by the app. This is used to check whether the total of the values ​​declared by other apps at the time of installation exceeds the limit. If the total of the declared values ​​of all apps exceeds the limit, the app will fail to install.

  • License related information
    Default value is OK for starting development. When you completed, please request FUNC ID to i-PRO and relace this value.

3.2 Preparing the sub-image (the image to be ported)

If you want to port an existing container image, create it as a subimage.

The SDK build script does not build sub-images, so developers must prepare the images themselves in advance.

Build a sub-image using a separate Dockerfile or Docker Compose. Specify arm64 as the architecture (platform) when building.

The following explains how to prepare the nginx image included in docker_multi_images as an example.

  • The docker_multi_images/web directory contains the files required for the nginx image.

  • Navigate to the web directory.

    cd [iPRO_CAMERA_SDK directory]/src/Aadamapp/[app directory]/web

  • Build the docker image.

    docker build -t web:0.0.1-arm64v8 .

  • Verify that the Docker image is built and exists in your development environment.

    docker images

    Example output

    $ docker images
    REPOSITORY                TAG                         IMAGE ID       CREATED         SIZE
    web                       0.0.1-arm64v8               78a72756f85e   16 hours ago    16.6MB

3.3 Editing docker-compose.yaml

Write information about the sub-image in docker-compose.yaml.
For information on how to write docker-compose.yaml, please see here etc.

The docker-compose.yaml you edit here will be executed in the camera when the app starts. You cannot use the build command in the file.

  • Add the sub-image information to the child level of the services key. This is already written in the sample app, so we will explain the contents here.

  • The complete description of the web service is as follows:

    image-20240909-101606.png

  • images:
    Here you specify the image name and tag created in 3.2. If the image specified here does not exist, the app build script will fail.

  • networks:
    If you want containers to communicate with each other, they must specify the same network.

  • restart:
    Specifies how to recover when the container is terminated. In the case of ext format Docker, the main container is monitored by the camera firmware without using Docker mechanisms, so specifying "no" will restart it appropriately. On the other hand, subcontainers are not monitored by the camera firmware, so set it according to the actual operation.

  • ports:
    If the sub-image exposes a port that can be connected from outside, describe it in the format of [camera side]:[container side].

  • volumes:
    Describes volumes and bind mounts.
    Only volumes defined in this docker-compose.yaml can be specified for volume. In addition, volume names defined here must also be separately listed in the volumes: section at the top of the yaml file.
    There are restrictions on directory paths that can be bind mounted.

  • tmpfs:
    Security policies prevent writing to containers, so if there are directories under /var where apps temporarily store data, specify them here.
    In the case of nginx, it writes to /var/cache/nginx and /var/run, so these are specified as tmpfs.

  • Required parameters
    The following parameters must be added to satisfy the security policy of the i-RPO camera. Please copy and paste as is.

        read_only: true
        user:
          1000:1000
        cap_drop:
          - "net_raw"
        security_opt:
          - "label=type:ipro-container.process"
          - "no-new-privileges"
        labels:
          com.i-pro.app-type: "ext"
          com.i-pro.device-category: "CV5x-A"
          com.i-pro.device-vendor: "i-PRO"
  • Listing root-level volumes
    Enter the volume name in the volumes: section under the root of the yaml file.

    image-20240801-032019.png

3.4 Implementing your own functionality

3.4.1 Communication and data sharing between containers

There are the following methods to exchange data between the main image and sub-image, or between a container and a camera.

  • Use volume.
    By writing this in docker-compose.yaml, you can share volumes between containers, so you can exchange data within them. However, this area is on FlashROM, and it affects the lifespan, so it is not suitable for exchanging large amounts of data.

  • Use a tmpfs that allows sharing.
    The area obtained with the ADAM_GetTmpDirPath() API is on tmpfs and can be used to store temporary data.
    To access this area from a subcontainer, add the following to volumes: in the subimage description in docker-compose.yaml.

          - type: bind
            target: "/dev/shm/Adamapp"
            source: "/dev/shm/Adamapp"
            read_only: false
            consistency: default

    However, since ADAM_GetTmpDirPath() cannot be called from a subcontainer, you must notify the path from the main container using a separate volume, etc.

  • Retrieved via HTTP.
    In Docker, each container is assigned a virtual IP address, which can be used to call the WebAPI in the same way as outside the camera. Also, if you specify a domain name in the hostname key of docker-compose.yaml, you can communicate using this name.
    In the main container, communication can be performed using the sendDataToAdamApplication WEB API as an ADAM mechanism. This mechanism is a method in which the camera body mediates data to the main container, so the destination is the IP address of the camera body.
    Similarly, you can use the camera's CGI to obtain the camera's settings and other information.

The IP address of the camera in the virtual environment can be found from within the container by referencing /etc/hosts from within the container and setting the least significant byte of the last entry to 1.

When accessing via WebAPI, you must specify the camera's user name and password.

3.4.2 Example implementation of sample app

The docker_multi_images sample app uses the DNS function of the inter-container network to implement sample code that sends an HTTP request from the main container to a sub-container by container name.
The response_by_html function in ${SDK_DIR}/adamapp/docker_multi_images/main.cpp calls the system function that makes a request with curl as follows. Here, “web” is the service name written in docker-compose.yaml.

	char cmd[256];

	snprintf( cmd, 256, "curl http://web/index.html > /tmp/local/index.html");
	if( system(cmd) != 0 ) {
		ADAM_DEBUG_PRINT(ADAM_LV_ERR, "system error (%s)\n", cmd);
	}

By pressing the "Go to Settings Screen" button for the "Docker Multi-Image" app displayed on the "Software Management Screen" of the camera browser, this code will be called and the contents of index.html of the web container will be displayed directly in the browser.

3.5 Building the app

Please refer to the following for information on building a development environment.

Construct a development environment(Container AdamApp) - Technology Partner FAQ (En) - Confluence (atlassian.net)

Please see below for information on how to develop and build apps.

How to develop(Container AdamApp) - Technology Partner FAQ (En) - Confluence (atlassian.net)

 

  • No labels