Documentation

Appearance

Software Builds and cohorts #

A Software Build is the desired software unit for one Device Class. It selects one immutable version of every attached container and can also reference one managed OS image.

The Build keeps these artefacts in one release decision without merging their delivery mechanisms. Containers reconcile from the Build immediately. An OS image remains held for a staged rollout under Delivery.

Create a Build #

Open Engineering > Software, select the Device Class, and choose Builds. Choose Create build and complete the wizard:

  1. Containers: select one version for every attached container.
  2. OS: when managed OS updates are enabled, select an optional Dataplicity OS or organisation-owned RAUC image. Choose no OS image for a containers-only Build.
  3. Review: confirm every selected version and the OS choice, then record a changelog that explains the operator-visible reason for the release.

The new Build starts in staging. Creating it does not by itself make it the class default.

Choose the target #

Every device resolves one effective Build:

  • Class default: make a Build current. Devices in the class that match no cohort receive it.
  • Tag cohort: assign a Build to a named cohort defined by one or more device tags. A device must have every tag listed by that cohort.

Use the class default for the normal production baseline. Use cohorts for canaries, hardware revisions, sites, or bounded rollout waves. Create and apply the device tags before assigning the Build.

Understand highest matching Build #

A device can match several cohorts. Dataplicity evaluates all matching cohort assignments and selects the Build with the highest sequence number. The whole Build wins: its container versions and optional OS image stay together.

If no cohort matches, the current class Build is the fallback. A lower-numbered cohort assignment does not override a newer matching Build merely because its tags are more specific.

This rule makes targeting deterministic, but overlapping cohorts still deserve careful review. Before assigning a Build:

  1. identify devices matching each tag set
  2. check for devices matching more than one cohort
  3. compare the sequence numbers of every Build they would match
  4. confirm the resulting whole-Build selection

Promote and reverse application changes #

Making a Build current changes the desired default for containers. Assigning it to a cohort changes desired state for matching devices. Review device results before expanding the target.

To return containers to a previous known-good composition, make or assign a newer Build containing those known-good versions. Application rollback remains your responsibility at the data and protocol boundary: older containers must be able to read files, databases, settings, and messages changed by newer versions.

An OS rollback is separate. Changing a Software Build does not reverse a booted RAUC slot, and an automatic RAUC rollback does not silently change the container Build selection.

Next step #

For a containers-only Build, verify container deployment results and application health. If the Build includes an OS image, open Software delivery to start and monitor its staged rollout.