Skip to main content

Provisioning

Avocado Linux provisioning encompasses the processes and methodologies for preparing target hardware to run Avocado OS. This reference covers provisioning concepts, target hardware considerations, and programming environment requirements for reliable deployment.

Concepts​

Provisioning transforms build artifacts into deployable images and handles the physical installation process onto target hardware. The provisioning pipeline includes image generation, bootloader configuration, partition layout, and hardware-specific optimizations.

Provisioning profiles​

Provisioning profiles define deployment strategies for different hardware interfaces and deployment scenarios. Available profiles depend on the specific target hardware - some targets may support SD card provisioning for development workflows, while others require specialized interfaces for on-board storage like eMMC. Virtual targets using QEMU or similar environments typically don't require physical hardware interfaces. Additionally, custom profiles can be created for hardware-specific provisioning procedures or specialized deployment scenarios.

Reliable provisioning​

Provisioning requirements​

Hardware provisioning workflows have varying requirements depending on the target hardware and deployment scenario. Some provisioning processes require physical hardware interfaces like USB connections for programming devices or accessing removable storage like SD cards. Others may provision virtual targets that need no physical hardware interaction. Many provisioning workflows include containers as part of their processes, while some require specialized kernel drivers or manufacturer-specific programming tools to interface with hardware programming modes.

Platform constraints​

These diverse provisioning requirements create challenges on macOS and Windows due to their virtualization architectures. Containerization platforms on these systems run inside lightweight hypervisors, creating VM-in-VM architectures that introduce additional abstraction layers between applications and physical hardware interfaces. Device enumeration becomes less reliable as hardware management is mediated through virtualization layers, requiring manual passthrough configuration that can fail or timeout during provisioning workflows. Manufacturer-specific programming interfaces that require kernel-level access or specialized driver stacks may not function consistently in virtualized environments.

Auto-mounting considerations​

On a Linux host, some desktop environments auto-mount mass storage devices, which can interfere with provisioning. Disable auto-mounting first — see Linux Auto-Mounting.

There are two reliable paths to provisioning hardware:

  • macOS — Avocado Desktop. Avocado Desktop bundles a build VM with USB passthrough, so it provisions real hardware directly on macOS without a native Linux machine. This is the recommended path on macOS and avoids the VM-in-VM frictions described above.
  • Linux — Avocado CLI. On a native Linux host, the Avocado CLI provisions hardware directly. Native Linux provides consistent device enumeration and reliable access for containers, kernel drivers, and manufacturer programming tools — running Linux directly on hardware rather than inside a VM on macOS or Windows.

Using the Avocado CLI with Docker Desktop on macOS or Windows is possible, but the virtualization layers make hardware enumeration and manufacturer programming interfaces less reliable for provisioning; prefer Avocado Desktop on macOS, or a native Linux host.