Integrate Dataplicity with your Linux image

You do not need Dataplicity OS to use Dataplicity. Keep the distribution, BSP, kernel, bootloader, service manager, and application runtime that fit your product. Dataplicity OS is one worked integration; your qualified Linux image is a first-class deployment.

This page collects the minimum image contract. Use Dataplicity OS when you prefer a ready-made CM5 starting point.

Choose the agent mode

Mode	Use it for	Minimum runtime
Rescue only	Device identity, Remote Shell, Wormhole, and file retrieval	Python 2.7 or newer, outbound HTTPS, accurate time
Rescue plus supervisor	Streams, settings, actions, Class Software, and managed RAUC integration	Python 3.8 or newer with pip and venv

Published modern management packages cover x86_64, aarch64, and armv7. Qualify the exact architecture, Python ABI, agent release, and image together.

A container runtime is optional. Put docker, podman, or nerdctl on PATH only when the product uses Class Software.

Network and operating requirements

The image must provide:

• trusted CA certificates, DNS, and outbound HTTPS;
• an accurate clock, normally through NTP;
• a writable persistent state location;
• service ordering that waits for the network and persistent storage;
• enough process, storage, and memory capacity for the selected agent mode.

Normal Dataplicity access needs no inbound port. See Firewall requirements for restricted customer networks.

Filesystem and service layout

The modern full-agent convention is:

/opt/dataplicity/venv
    Rescue, supervisor, and fixed dp-converge helper

/var/lib/dataplicity
    Device identity, state, cache, features, config/current,
    image-update state, and persistent managed-container storage

/etc/dataplicity/agent.yaml
    Agent configuration; symlink into persistent state on A/B images

/usr/local/bin/
    dataplicity, prelude-agent, dp-provision, dp-supervisor,
    dp-converge, and dp-rauc-ready entry points

On a conventional single-root image, /var/lib/dataplicity can be an ordinary directory. On an A/B image it must be a separate persistent mount outside both root filesystem slots.

Keep /opt/dataplicity/venv in every signed rootfs slot. An OS rollback then restores the matching agent runtime. Do not move executables onto the persistent data partition.

If Class Software is used on an A/B product, keep the container store, config/current, and content-addressed cache on the persistent mount as well.

Linux users and privileges

The rescue service runs as dataplicity. The supervisor runs as dpagent. Grant container-runtime group membership only when the product uses that runtime.

Managed RAUC uses the fixed /opt/dataplicity/venv/bin/dp-converge privileged helper for install, mark-good, and reboot. Do not replace this boundary with blanket passwordless sudo or a configurable executable path.

Provision each device

In the Dataplicity app, select Add device and run the complete generated command on the target image. The command contains organisation-specific provisioning material; never put it in a public image or repository.

For production:

1. bake the agent packages into the image or make them available to a controlled first-boot step;
2. provision each physical unit independently during factory, first-boot, or site commissioning;
3. preserve the resulting identity under /var/lib/dataplicity;
4. remove temporary provisioning material;
5. confirm the unique device in inventory.

Clone the base image before registration, not after. See Installing for mass production.

Add RAUC only when you need managed OS images

Most Dataplicity devices do not need RAUC. If your product already has another OS update mechanism, keep it unless you deliberately choose to qualify RAUC.

For Dataplicity-managed RAUC delivery, the image also needs:

• two real A/B root filesystem slots;
• RAUC connected to the actual bootloader;
• bounded boot-attempt counting and automatic fallback;
• a product-specific compatible value;
• a public verification CA baked into the RAUC keyring;
• the Dataplicity runtime in every slot;
• /var/lib/dataplicity and managed application state outside the slots;
• physical failed-boot and power-loss qualification.

Use dataplicity rauc-ready to check what userspace can prove. Use Build OS firmware and configure RAUC signing to create the signing trust and connect it to a Device Class.

Custom Yocto, Buildroot, and unusual platforms

Custom embedded Linux is expected integration work, not a second-class support path. Email support@dataplicity.com with:

• distribution or build system and release;
• CPU architecture and Python version;
• init/service manager;
• read-only and persistent filesystem layout;
• container runtime, when used;
• OS updater and bootloader design;
• network and certificate constraints.

We can help map the agent runtime, CA certificates, users, permissions, services, connectivity, persistent paths, and RAUC integration to the product.

Qualification checklist

Before a fleet rollout:

1. install on the exact production-equivalent image and hardware;
2. confirm DNS, HTTPS, and time synchronisation;
3. verify the device enrols and reconnects after cold boot and network delay;
4. confirm its identity does not change;
5. test Remote Shell with the intended Linux permissions;
6. verify the supervisor and container deployment when used;
7. test agent and OS upgrades while preserving state;
8. repeat qualification when the base image, architecture, service policy, or boot chain changes.