Container Dev Loop
This guide walks you through the container dev loop on an Avocado OS device. You build a container image on your host with docker build, and avocado container dev ships only the changed layers to the running device and restarts the service there. There is no reflash and no OS rebuild between iterations.
The reference ships a dev runtime with a container-hello systemd service that runs docker.io/peridionick/hello-flask:py311 on port 8080. The container_dev block in avocado.yaml maps the host-side image peridionick/hello-flask:py311 to that service.
Nothing in this guide records a run: the Deploy and Verify sections describe the steps you perform and what the container dev mode guide says you should see. Hot reload through this reference has not been verified on any target yet.
Prerequisites
- Linux or macOS host with Docker (or Podman) running. The watcher reads tag events from the engine CLI, and the SDK needs Docker.
- The latest Avocado CLI. This reference requires
>=0.41.0. - A target from the reference's
supported_targets:qemux86-64(default) orimx93-frdm. - A device running the provisioned
devruntime that your host can reach over SSH asroot@<device>. avocado-ext-sshd-devon the device. Container dev mode bootstraps the device over SSH, so a target without an SSH server cannot be bootstrapped. The reference'shellooverlay adds an sshd drop-in for the key path, so the 0.1.0 package in the feed is enough.- Control (5600) and bulk read (5599) ports on your host reachable from the device. Opening only the control port is the usual reason a sync appears to stall.
Initialize
avocado init --reference container-dev-loop container-dev-loop
cd container-dev-loop
All remaining commands run from this directory on your host.
Install
avocado install -f
This syncs the SDK toolchain and the runtime extensions. The sdk.packages block in avocado.yaml declares the cross toolchain because avocado-ext-container-agent-dev is compiled for the target at build time. Without it the build fails inside a dependency's build script.
Build
avocado build
The build produces the dev runtime. It includes the project-local hello extension (the container-hello.service unit, enabled in both its sysext and confext), Docker, the container dev agent, the SSH server and the board support package. The hello extension declares docker.io/peridionick/hello-flask:py311 to be primed into /var at runtime build, with the intent that the device does not need a registry at first boot. Priming is not verified: the build log does not show the step. Until you have confirmed it on your build, give the device registry access at first boot so it can pull the image.
Deploy
Provision the device once. This erases the target media, so confirm the device first. List the profiles available for your target:
avocado provision --list
Then provision the dev runtime with a profile from that list:
avocado provision dev --profile <profile>
The dev permissions profile sets an empty root password and is not for production.
Boot the device and find its IP address from the console (ip addr). Substitute it for <device-ip> below.
Give the host SSH access
Container dev mode needs root@<device-ip> reachable over SSH with your key accepted. avocado-ext-sshd-dev 0.1.0 reads .ssh/authorized_keys, so the hello overlay installs /etc/ssh/sshd_config.d/10-authorized-keys.conf, which sets AuthorizedKeysFile /var/lib/ssh/authorized_keys.d/root. That file does not exist on a freshly provisioned device, so create it from the console as root and paste your public key:
mkdir -p /var/lib/ssh/authorized_keys.d
echo "<your public key>" > /var/lib/ssh/authorized_keys.d/root
chmod 600 /var/lib/ssh/authorized_keys.d/root
Check from your host:
ssh root@<device-ip> true
Then point the CLI at the device. The avocado container dev subcommands take no positional arguments:
export AVOCADO_CONTAINER_DEV_DEVICE=root@<device-ip>
Start the loop
avocado container dev up
up mints a per-project CA and tokens, starts the embedded registry, the watcher and the control WebSocket on your host, and writes the bootstrap to the device once over SSH. It then leaves the loop running. Run the remaining commands in a second terminal.
Verify
Check the service on the device:
ssh root@<device-ip> systemctl status container-hello.service
ssh root@<device-ip> docker ps
The container dev mode guide describes the unit as running and the container container-hello as listed by docker ps. Then request the page from your host:
curl http://<device-ip>:8080
The page is served by the hello-flask:py311 container and reports a container Python of 3.11.
Check the host side of the loop:
avocado container dev status
status reports registry, watcher and last-sync state.
To confirm a hot reload, rebuild the watched tag on your host:
docker build -t peridionick/hello-flask:py311 app
Per the container dev mode guide, the watcher sees the tag event, pushes only the changed layers, and the agent on the device pulls them and restarts container-hello. Watch it from the device:
ssh root@<device-ip> journalctl -u container-agent-dev -f
Docker builds on older daemons (before Docker 23) emit no tag event for BuildKit builds, and a --platform cross-build never does. In those cases trigger the sync yourself:
avocado container dev sync
The app/ directory holds a minimal Dockerfile that layers one file on the published image, so the rebuild has a changed layer to ship. Replace it with your own application when you have one.
Reading logs: the container runs on the device, not on your host, so docker logs on your host reports no such container. Use ssh root@<device-ip> docker logs -f container-hello.
Customize
- Your own image: set
container_dev.images[].refinavocado.yamlto the tag you build, byte for byte, andserviceto the unit that runs it. Update the image indocker_imagesof thehelloextension and inoverlay/usr/lib/systemd/system/container-hello.serviceto match. - The service must recreate the container from the image tag on every start. The shipped unit does so with
docker rm -ffollowed bydocker run. A unit that restarts an existing container keeps running the old code. - Ports: change
-p 8080:8080in the unit. Override the dev loop ports withAVOCADO_CONTAINER_DEV_PORT(bulk read, default 5599) andAVOCADO_CONTAINER_DEV_WS_PORT(control, default 5600). - Architecture: when your host differs from the target, build with
docker build --platform <platform> -t <ref> app, usinglinux/amd64forqemux86-64andlinux/arm64forimx93-frdm, and then runavocado container dev sync. - Disk:
avocado container dev prunegarbage-collects the host registry store. - Stop the loop with
avocado container dev down. The device keeps running the last image it was given. - Only one runtime per config may carry a
container_devblock, andavocado-ext-container-agent-devmust not be part of a production runtime.