A Digi Container Package (DCP) is a tarball that includes an LXC or OCI (Docker/Podman) container image plus a manifest with information for the ConnectCore Container Manager daemon to manage it during its life cycle (version, runtime arguments, restart options…​)

Why use a DCP?

When you install a raw container artifact on the target, you need to specify different parameters, such as the runtime the daemon must use, the restart policy, and such. A DCP solves it at build time by packaging:

  • the container payload

  • runtime metadata

  • registration defaults

  • optional auxiliary files such as README or changelog for your records

This lets you distribute containers to a fleet of devices and be sure they will install and run consistently on all of them.

DCP structure

A DCP consists of:

File/Directory Description

manifest.json

Contains registration information and run parameters for the Container Manager daemon

payload/

Contains the LXC or Podman/Docker container tarball

checksums/

At build-time, this is filled with validation checksums

metadata/

Optional folder for custom metadata

Manifest file

The manifest.json describes the package and the default behavior that the Container Manager should apply on installation.

Example manifest.json
{
  "package_id": "redis-demo",
  "friendly_name": "Redis Demo",
  "version": "1.0",
  "runtime": "podman",
  "create_args": "--privileged --network host --tty",
  "registration_defaults": {
    "autostart": true,
    "monitor": true,
    "restart": {
      "enabled": true,
      "max_retries": 3,
      "window": 60,
      "retry_delay": 3
    }
  },
  "device_types": ["ccimx95-dvk"],
  "firmware_versions": "",
  "build_id": "",
  "description": "Redis demo image from docker.io",
  "labels": {}
}
Field Description

package_id

Unique identifier for the container

friendly_name

Descriptive name of the container

version

Version number of the container

runtime

Runtime to use for this container:

  • lxc, for LXC containers

  • podman for OCI-type (Podman/Docker) containers

create_args

Arguments for podman runtime (Podman/Docker) containers

registration_defaults

Set of fields to manage the container

autostart

Defines whether or not the container will start automatically after boot (or container installation)

monitor

Defines whether the daemon must periodically query the container for status

restart

Set of restart parameters

- enabled

Defines whether the daemon must restart the container in case it stops

- max_retries

Number of times the daemon should try to restart the container before giving up

- retry_delay

Seconds to wait between restart retries

- window

Time window (in seconds) to consider the daemon is doing a restart retry of this container

device_types

(unused) Set of platforms for which the container is compatible

firmware_versions

(unused) Range of firmware versions for which the container is compatible

build_id

(unused) A build identifier (e.g. a git commit SHA1, an internal build number) to correlate installed artifacts with build outputs

description

(unused) Description of the container

labels

(unused) A set of free-form strings used for classification and filtering

Payload

The payload must be a tarball with an LXC or OCI-type (Podman/Docker) container. To obtain a tarball from an existing OCI-type image on your host computer, use the command podman save (or docker save).

Generate a DCP

Generate a DCP from an existing container on your host

To generate a DCP from an existing container you need an LXC bundle (.tar.gz) or an OCI-type (Podman/Docker) image archive (.tar). See Payload.

  1. Create a manifest.json file (see Manifest file for reference).

  2. Run generate-dcp.py script from meta-digi-containers layer with the payload and the manifest file as arguments:

    $ python3 /usr/local/dey-5.0/sources/meta-digi/meta-digi-containers/scripts/generate-dcp.py \
  --manifest <your-path>/manifest.json \
  --payload <your-path>/<your-payload-file>

    This generates an artifact with a filename such as <your-container>-ccimx95-dvk.tar.gz.

Build a DCP from a demo template

The meta-digi-containers layer contains a number of demo templates in folder meta-digi-containers/containers/:

Demo name Description

chromium-demo

A demo that features full-featured Chromium web browser engine with an HTML demo.

flutter-demo

A graphical demo using Flutter.

lvgl-demo

A graphical demo using LVGL.

webkit-demo

A graphical demo that features WebKit browser engine with an HTML demo. (Not supported for the ConnectCore 95)

The layer provides a recipe dey-image-dcp that you can use to build one of the container demos. The recipe builds a DCP in two flavors by default:

  • an LXC container

  • an OCI-type (Podman/Docker) container

Before proceeding, make sure your project is configured for building containers.

To build one of the demos:

  1. Set variable DCP_NAME in your project’s conf/local.conf to the name of one of the preconfigured demos. For instance, for the lvgl-demo:

    conf/local.conf
    DCP_NAME = "lvgl-demo"

  2. Build the recipe:

    $ bitbake dey-image-dcp

This generates two artifacts on your deploy directory:

  • lvgl-demo-lxc-ccimx95-dvk.tar.gz

  • lvgl-demo-podman-ccimx95-dvk.tar.gz

Install a DCP

Refer to Step 4 - Deploy and run the container for instructions to deploy, install, and run a DCP on your device.

The size of a DCP (essentially a compressed .tar.gz) is not representative of the required installation space. As an example, a 300 MiB DCP may expand to an 800 MiB image archive and require an additional 800 MiB or more when imported into the container runtime. Including temporary extraction files, the installation process of such a DCP might require up to 2.5 GiB of free disk space.

Always verify enough storage is available before installation.