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 create new feature extension software in the form of a Docker container, and if you have already developed a Docker container that runs on another server or device, you can easily run it on the camera by porting it according to this document. 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 Guidelines for choosing app configurations for different users

For ext format Container AdamApp, the container configuration can be specified in the Docker compose configuration file (docker-compose.yaml). In the docker-compose.yaml file, you can start multiple containers by specifying multiple service names.

Below is a conceptual diagram showing the difference in configuration between the conventional AdamApp and Container AdamApp.

The above is a conceptual diagram of running multiple containers within one extension software (one ext format binary), but since the new X Series cameras allow for multiple apps to be installed, it is also possible to run multiple independent apps simultaneously.

The following are guidelines for selecting the configuration depending on the application.

2.2 Configuration for developing apps with multiple containers

The docker_multi_images included in the SDK is a sample app that can be used as a reference if you choose use case 3 or 4 in Chapter 2.1. The docker_multi_images sample app consists of two Docker images.

• docker_multi_images image
  It exists to start and stop the application from the camera body and to respond to keep-alive messages. 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 is built with 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." It exposes nginx's TCP 80 port to the outside as TCP 8081 port and accepts http requests from external devices. When creating Container AdamApp, it must be built as a Docker image in advance.

If you want to run an existing container on an i-PRO camera, you can add the docker_multi_images image 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:

• Are there enough RAM/ROM/CPU resources?

• Does it comply with the i-PRO camera security policy?

• Is there only one container that uses the ADAM API?

These are explained below.

2.3.1 RAM / ROM / CPU resources

Please see here for resources on how the new X-Series cameras can be used to extend the functionality of your applications.

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

For more information on Container AdamApp's security policy, please see here.

Special porting considerations are discussed.

• 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 for temporary data, or to a separate mounted volume for persistent data.

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

• Images cannot be pulled from an external container registry directly from within the camera. The required images must be pulled and built on the development PC and included in the 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 subcontainers.

If you want to use camera functions, we recommend implementing them in the main image, and if you want to run general-purpose functions that are not camera-dependent directly on the camera, we recommend implementing them in the sub-image. Data sharing between the main image and sub-image will be explained in Chapter 3.4.

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
  Please specify the FUNC ID assigned by i-PRO.

3.2 サブイメージ (移植対象イメージ) の準備

既存のコンテナイメージを移植する場合はそのイメージをサブイメージとして作成します。

別途DockerfileやDocker Composeを利用してサブイメージをビルドします。ビルド時のアーキテクチャ (プラットフォーム) はarm64を指定してください。

以下は、docker_multi_images内に含まれるnginxのイメージの準備を例に説明します。

• docker_multi_images/web ディレクトリ以下にnginxのイメージに必要なファイルが含まれています。

• web ディレクトリ以下に移動します。

  cd [iPRO_CAMERA_SDKディレクトリ]/src/Aadamapp/[アプリディレクトリ]/web

• docker imageをビルドします。

  docker build -t web:0.0.1-arm64v8 .

• dockerイメージがビルドされ開発環境に存在することを確認します。

  docker images

  出力例

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

3.3 docker-compose.yaml の編集

docker-compose.yaml内にサブイメージに関する情報を記載します。 docker-compose.yamlの記述方法自体については、 https://docs.docker.jp/compose/compose-file/index.html などをご参照ください。

• services キーの子レベルにサブイメージの情報を追加します。 サンプルアプリではすでに記載されていますのでその内容を説明します。

• webサービスについての全体の記載は以下となります。

  

• images:
  ここには3.2で作成したイメージ名とタグを指定します。ここで指定したイメージが存在しない場合、アプリのビルドスクリプトは失敗します。

• networks:
  コンテナ間で通信したい場合、同じネットワークを指定する必要があります。

• restart:
  コンテナが終了したときにどのように復旧するかを指定します。ext形式Dockerの場合、メインコンテナはDockerの仕組みを使用せずにカメラファームウェアによって監視されるため、noを指定することで、適切に再起動します。一方サブコンテナはカメラファームウェアから監視されませんので、実動作に合わせて設定します。

• ports:
  サブイメージが外部から接続できるポートを公開する場合、[カメラ側]:[コンテナ側]の書式で記載します。

• volumes:
  ボリューム、バインドマウントを記載します。
  volumeはこのdocker-compose.yaml内で定義されているボリュームのみ指定できます。また、ここに定義されているvolume名は別途yamlファイルトップのvolumes: セクションにも記載する必要があります。
  バインドマウントできるディレクトリパスには制限があります。

• tmpfs:
  セキュリティポリシーによりコンテナ内には書き込めないため、/var以下などのアプリが一時的に保存するディレクトリがある場合はここに指定します。
  nginxの場合、 /var/cache/nginx、/var/run 以下に書き込みますので、これらをtmpfs として指定しています。

• 必須のパラメータ
  以下パラメータはi-RPOカメラのセキュリティポリシーを満たすために付与が必要です。 このままコピー&ペーストしてください。

      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"

• ルートレベルのvolumesの記載
  yamlファイルのルート (トップ) 以下のvolumes: セクションに、ボリューム名を記載します。

  

3.4 独自の機能を実装する

3.4.1 コンテナ間の通信やデータ共有

メインイメージ・サブイメージ間や、コンテナとカメラ間でデータをやり取りするには以下の方法があります。

• volumeを使用する。
  docker-compose.yamlに記載することでvolumeをコンテナ間で共有することができますのでこの中でデータをやり取りできます。ただしこの領域はFlashROM上となり、寿命に影響がありますので大量なデータのやり取りには向きません。

• 共有が許可されているtmpfsを使用する。
  ADAM_GetTmpDirPath() APIで取得できる領域はtmpfs上にあり、一時的なデータ保存用として利用できます。
  サブコンテナからこの領域にアクセスするためには、docker-compose.yamlのサブイメージの記述内のvolumes: に以下を追加します。

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

  ただし、サブコンテナからはADAM_GetTmpDirPath()を呼ぶことができませんので、別途volumeを使う方法などでメインコンテナからパスを通知する必要があります。

• HTTP経由で取得する。
  Dockerでは各コンテナに仮想のIPアドレスが割り当てられるため、こちらを利用して、カメラ外と同様にWebAPIを呼ぶことができます。また、docker-compose.yamlのhostnameキーでドメイン名を指定すると、この名前で通信を行うこともできます。
  メインコンテナでは、ADAMの仕組みとして、sendDataToAdamApplication WEB APIを使用して通信を行うことができます。この仕組みはカメラ本体がメインコンテナにデータを仲介する方法ですので、あて先はカメラ本体のIPアドレスとなります。
  また、同様にカメラのCGIを利用してカメラ本体の設定値などを取得することができます。
  

3.4.2 サンプルアプリの実装例

docker_multi_imagesサンプルアプリではコンテナ間ネットワークのDNS機能を使用し、メインコンテナからコンテナ名でサブコンテナへhttpリクエストを出すサンプルコードを実装しています。
${SDK_DIR}/adamapp/docker_multi_images/main.cpp の response_by_html関数内で以下の様にcurlでリクエストを行うsystem関数を呼び出しています。 ここで “web” は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);
	}

カメラブラウザの「ソフトウェア管理画面」に表示された、「Dockerマルチイメージ」アプリの「設定画面へ」ボタンを押下することで、このコードが呼び出され、webコンテナのindex.htmlの内容をそのままブラウザに表示します。

3.5 アプリのビルド

開発環境構築については下記を参照ください。

開発環境構築(Install development environment編) - Technology Partner - Confluence (atlassian.net)

アプリ開発方法やビルドについては下記を参照ください。

開発方法(how develop編) - Technology Partner - Confluence (atlassian.net)