Documentation

Appearance

How do I migrate an existing Linux installed base to Dataplicity? ​

Treat migration as an incremental adoption project, not a fleet rewrite.

The usual brownfield path is to install Dataplicity beside the product software you already run, prove connectivity and support on representative devices, then add Device Classes, product data, software management, and Customer Portal capabilities only where they remove real work.

Do not begin by redesigning the product ​

A brownfield estate already contains valuable decisions:

  • a Linux distribution and image process;
  • service supervision;
  • application deployment;
  • hardware integrations;
  • field networking behaviour;
  • support procedures;
  • customer-specific quirks;
  • sometimes years of operational knowledge.

Do not throw those away merely to adopt a fleet platform.

If the existing product works, the first migration objective is simple:

Connect representative devices securely and prove that Dataplicity improves support and fleet visibility without changing product behaviour.

1. Segment the installed base first ​

Before installation, identify the real estate you have rather than the estate you think you have.

Useful dimensions include:

  • hardware model and CPU architecture;
  • Linux distribution and version;
  • agent/package-manager availability;
  • storage and memory constraints;
  • network type: Ethernet, Wi-Fi, cellular, private APN;
  • customer firewall/proxy requirements;
  • application/runtime model: systemd, Docker, Podman, supervisor, custom launcher;
  • existing OTA/update mechanism;
  • privilege model;
  • product generation and remaining service life.

You do not need perfect inventory before starting, but you need enough to choose representative test devices and avoid treating one lab unit as proof for every deployed generation.

2. Prove the minimum integration ​

Pick a small set of representative devices and install Dataplicity without changing the product application.

For each type, prove:

  1. the agent installs cleanly;
  2. the device connects through its real customer network;
  3. it reconnects after reboot;
  4. engineering remote access works as intended;
  5. the existing product application is unaffected;
  6. CPU, memory, storage, and network overhead are acceptable;
  7. uninstall/recovery is understood.

Use What runs on my device? and How Dataplicity works behind firewalls as qualification inputs.

3. Keep the existing runtime where it already works ​

Dataplicity does not require an established product application to move into a Dataplicity-managed container.

If the estate already uses:

  • systemd services;
  • Docker or Podman;
  • Greengrass;
  • balena-managed workloads;
  • a proprietary supervisor;
  • RAUC, Mender, SWUpdate, or another firmware/update system;

keep that architecture initially.

Add Dataplicity around it for fleet/support capability. Move application or software lifecycle responsibility only if doing so creates a clear operational advantage.

4. Introduce Device Classes after you understand the estate ​

Once representative devices are connected, model actual product families with Device Classes.

Do not make one giant class called legacy unless those devices really share a stable product contract.

A useful class boundary normally corresponds to a product model or generation that shares:

  • hardware expectations;
  • software compatibility;
  • streams/settings/actions;
  • customer UI;
  • release strategy.

This becomes the bridge from a bag of remotely accessible Linux machines to a managed product fleet.

5. Add product data and controls selectively ​

Do not instrument everything because you can.

Start with the values and actions that materially improve operations:

  • software/application version;
  • connection state;
  • important process health;
  • product mode/status;
  • key sensor values;
  • safe remote diagnostics;
  • reboot where appropriate;
  • connectivity/DNS/NTP tests;
  • product-specific settings or actions that already have a safe local validation path.

For high-value controls, review the current device data and control contract and business-logic boundary.

6. Run old and new systems in parallel where necessary ​

Brownfield migrations often fail when teams demand an artificial cutover date for systems that do not need one.

It is reasonable to run Dataplicity beside:

  • an existing telemetry backend;
  • a legacy VPN;
  • an established OTA system;
  • existing customer software;
  • a field-service process.

Then retire each old component only after the Dataplicity path has been proven and the replacement is materially better.

Parallel operation is especially useful where devices are intermittently online or customer access to sites is difficult.

7. Roll out in cohorts, not all at once ​

A sensible rollout sequence is:

  1. lab/reference devices;
  2. internal/staff-controlled sites;
  3. a small customer cohort;
  4. one hardware/software generation;
  5. broader fleet cohorts;
  6. edge cases and long-tail legacy systems last.

Track install success, reconnection behaviour, resource impact, support outcomes, and any customer-network exceptions.

If a device generation behaves differently, stop treating it as the same cohort.

8. Add Customer Portal only when the customer boundary is ready ​

The Customer Portal is not required for an internal fleet migration.

For an OEM, introduce it after:

  • device identity is stable;
  • customer/site ownership is understood;
  • the product data/control contract is trustworthy;
  • support and engineering access are clearly separated from customer access.

Then allocate devices to customers/sites and build the customer-facing product experience without exposing the engineering workspace.

See Build your first connected product.

9. Preserve rollback and exit paths ​

Before broad rollout, know how to:

  • disable or uninstall the Dataplicity agent;
  • recover a device if installation exposes an incompatibility;
  • preserve your existing updater and product application;
  • export or retain important customer/domain data outside the platform where required;
  • avoid making core device operation dependent on Dataplicity availability.

A migration is safer when adoption is reversible.

Supported Linux and unusual builds ​

Dataplicity is intended to work across normal Linux product environments, including mainstream Ubuntu, Raspberry Pi OS, Debian, and Arch deployments.

For unusual Yocto images, highly stripped distributions, proprietary build systems, or otherwise custom Linux products, qualify the actual image rather than assuming it behaves like a general-purpose distribution. Dataplicity's approach is to work with unusual Linux environments where practical, but a bespoke build may require engineering work or reveal dependencies that are not present by default.

Do that qualification on representative hardware before committing the fleet.

Migration is complete when operations improve ​

The goal is not “100% of devices have an agent installed.”

A successful migration means you can demonstrate improvements such as:

  • fewer site visits;
  • faster remote diagnosis;
  • better fleet inventory and version visibility;
  • safer controlled changes;
  • clearer customer/device ownership;
  • less bespoke platform code;
  • better evidence after incidents and maintenance.

If a feature does not improve the operating model, there is no need to migrate that responsibility merely for architectural purity.