SDKs and platforms

How do you deploy one app to a fleet of Raspberry Pi and Jetson boards?

Build one arm64 container image with the Offline Protocol SDK, and give each board three things when you deploy it, host networking for local discovery, a persistent volume for its identity and held messages, and a correct clock. On WendyOS, wendy.json declares those needs and wendy run deploys the image to each board. On other Linux boards, the published service image takes the same grants from Docker.

TL;DR

Build one arm64 image with the Offline Protocol SDK on a glibc base such as python:3.12-slim. Deploy it to every board with host networking, a persistent volume and its own store key, and set the clocks. WendyOS does this with wendy.json and wendy run.

Learning objectives

After reading this article you will be able to:

  • Build one container image that runs an Offline Protocol app on every 64-bit Arm board in a fleet
  • Give each board its own identity, persistent state, network access and correct time
  • Deploy, check and update the app across boards with WendyOS or Docker

One image for every board

A fleet of 64-bit Arm boards, such as NVIDIA Jetsons, Raspberry Pis and Qualcomm Dragonwing boards, can share one container image. The Offline Protocol Python package has a manylinux_2_34_aarch64 wheel, so the image needs a glibc-based userland with glibc 2.34 or newer. Debian’s python:3.12-slim meets it; Alpine does not, because it uses musl. This is the Dockerfile Wendy Labs used for its three-board build:

FROM python:3.12-slim
ENV PYTHONUNBUFFERED=1
WORKDIR /app
RUN pip install --no-cache-dir 'offline-protocol-sdk[lan]==0.33.0'
COPY app.py .
CMD ["python", "app.py"]

Pin the SDK version, so every board runs the same protocol release. The lan extra adds discovery on the local network. Settings that differ between boards, such as a board’s name or a fixed peer list, come from environment variables, so the image itself stays the same everywhere.

There are two ways to put Offline Protocol in the image. The app can run the SDK in its own process, as Wendy’s app does with ProtocolManager. Or each board can run the Offline Protocol service as its own container, and every app on the board reaches it over its local API or calls services on other boards through its HTTP front on loopback. How to call an HTTP service on another device without internet covers the second.

Board identity, volumes and store keys

Each board generates its own key the first time it starts, and its address is derived from that key. The SDK keeps the key and every message still waiting for delivery on disk, sealed under a store key. Two things keep a board the same board across deploys:

  • A persistent volume mounted where the SDK keeps its state. Without it, a replaced container starts with a new identity and an empty queue.
  • The same store key, passed in from a secret store. A board needs its own key, generated once, for example with openssl rand -hex 32.

Wendy’s tutorial lets each board create its store key on first boot and keep it on the volume, which keeps a demo to one command. For production, hand the key in from a secret store and keep it off the volume, so another app that mounts the volume cannot unseal it.

Network access and clocks for each board

Two more grants decide whether boards find each other:

  • Host networking. The SDK finds other boards with multicast DNS, and multicast does not leave a container’s private network. With host networking, the app shares the board’s own network and listens for peer streams on TCP port 7878. Boards on another subnet need a fixed list of peer addresses instead of discovery.
  • A correct clock. Encryption checks the time, so a board with a wrong clock sees valid keys as invalid. On a network with no internet there is no time server to correct it.

For Bluetooth LE, the container also needs BlueZ: the system D-Bus socket on a plain Docker host, or the bluetooth entitlement in bluez mode on WendyOS.

Deploying to a fleet with WendyOS

WendyOS, Wendy Labs’ operating system for robots and edge AI devices, turns those grants into one file. The app’s wendy.json lists what it may use, and the device grants exactly that:

{
  "appId": "sh.wendy.examples.table-talk",
  "version": "0.1.0",
  "platform": "linux",
  "entitlements": [
    { "type": "network", "mode": "host" },
    { "type": "persist", "name": "table-talk-data", "path": "/data" }
  ]
}

Before deploying, wendy device sync-time fetches a signed timestamp on the laptop and multicasts it to every WendyOS board on the local network, and each board checks the signature itself. Then each board takes one command, with its own name:

wendy run --device wendyos-pi.local --env BOARD_NAME=pi
wendy run --device wendyos-jetson.local --env BOARD_NAME=jetson

wendy run builds the image, sends a board only the image chunks it is missing, and restarts the app, over USB-C, the local network or Wendy Cloud. For larger fleets, a Wendy build host builds one image and delivers it to several devices. wendy device logs streams each board’s output, and WendyOS updates the operating system over the air, rolling back on its own if an update fails. Wendy Labs deployed one app this way to a Jetson Orin Nano, a Raspberry Pi 5 and a Dragonwing IQ9 with no internet, as Offline Protocol on WendyOS shows.

Deploying to a fleet with Docker

On Linux boards without WendyOS, the published service image, ghcr.io/offline-protocol/offline-protocol-service, runs on linux/arm64 and linux/amd64. Each board’s container gets the same grants: the host’s network namespace, inbound TCP on 7878, a persistent volume at /var/lib/offline-protocol, the board’s store key from a secret store, and the D-Bus socket for Bluetooth LE. Pin the image by digest rather than tag, so every board runs exactly the same build. Can I run Offline Protocol on a server or in Docker? lists every grant.

Checking a fleet after a deploy

A board shows it is part of the fleet through the SDK’s events: a neighbor discovered, a secure session established, messages received and delivery receipts for the messages it sent. Log them, and a board’s output answers whether it found the others. With the service, offline-protocol-verify drives the running service and waits for the events that prove a message was held, carried and delivered, which makes a quick check after each deploy.

Frequently asked questions

Can one container image run on a Jetson, a Raspberry Pi and a Dragonwing board?

Yes, when all of them are 64-bit Arm. Wendy Labs deployed one image from one Dockerfile to a Jetson Orin Nano, a Raspberry Pi 5 and a Dragonwing IQ9, and the same app ran on all three. Build it on a glibc base image, such as python:3.12-slim, because the SDK's wheels do not support Alpine's musl.

Why does each board need a persistent volume?

The SDK keeps the board's identity and the messages it is still waiting to deliver on disk. Containers are replaced on every deploy, so without a volume a board gets a new address each time and loses its held messages.

Do boards need to be told each other's addresses?

No. With host networking and the lan extra, boards on the same network segment find each other over multicast DNS and open encrypted sessions on their own. For boards on different subnets, give each a list of peer addresses instead.

Why do the boards' clocks matter?

Encryption checks the current time, so a board with a wrong clock sees valid keys as invalid and sessions do not form. On a network with no time server, WendyOS sets every board's clock with wendy device sync-time.

How do I update the app without changing a board's identity?

Deploy the new image with the same volume and the same store key. The identity and held messages live on the volume, sealed under the key, so the board keeps its address and delivers what it was holding.

Sources

Build it with Offline Protocol

The Python page covers the gateway profile, the configuration fields and the events an app on each board handles.

Read Python and Linux gateways