Skip to main content

Create a custom Modalix image

Palette Image Builder (PIB) creates a custom eLxr image for Modalix. It is provided as a separate Docker container maintained in the Palette SDK repository. Install it with sima-cli; the main SDK container is not required.

One project produces two deployment formats:

  • .swu: a signed update bundle for a running board.
  • .img.gz: a full disk image for initial provisioning or recovery.

1. Install PIB​

With sima-cli and Docker installed, run:

sima-cli neat install sdk/pib
pib doctor

The installer downloads the matching x86_64 or ARM64 container and installs the pib command on Linux, macOS, or Windows. Open a new terminal if it updates PATH. PIB runs in Linux containers; Docker must be running and permit privileged access for image assembly. ARM64 emulation is included and configured automatically on x86 Docker hosts.

Use a local project folder with at least 10 GiB free for minimal, or 20 GiB for palette, and similar space in Docker storage. The build needs access to the Debian/eLxr and SiMa package repositories. The generated board image is ARM64.

sdk/pib selects the latest published main package. To select another SDK branch or release, use the same syntax as the SDK, for example sima-cli neat install sdk/pib. See the installation reference for manual Docker installation and host details.

2. Create an image project​

pib init my-image --flavor minimal
cd my-image

Use --flavor palette if you need the desktop and larger package set. The image's platform release comes from the selected container. Your project contains:

my-image/
├── image.yaml # version and customizations
├── custom-debs/ # your ARM64 or architecture-independent Debian packages
├── overlay/ # files to add to the root filesystem
├── hooks/ # optional post-install scripts
├── keys/ # your signing identity and public trust material
├── configs/ # release-specific board defaults; normally leave unchanged
└── out/ # generated artifacts

Run subsequent commands from this project directory. To open a shell with its files mounted, run pib shell; run pib directly inside that shell, then exit to return to the host.

For a runnable example with a sample application package, configuration overlay, and service-enablement hook, use pib init my-image --example custom-image instead. The example walkthrough shows the complete sequence; CI builds that same checked-in image.yaml on both architectures. The example is included in the container, so no checkout is needed.

3. Set up signing once​

For development, create a test CA and signing identity:

pib keys init --cn 'My Company Development'

Move keys/ca.key to a secure offline location after setup. The signing leaf and its private key remain in keys/; generated .gitignore rules exclude private keys and build outputs. Back up your identity securely. Existing boards trust your CA, so keep that CA when moving to a new project or platform release.

For production, use your organization's signing identity. See external keys and certificate renewal. The container includes no SiMa production signing keys.

4. Customize the image​

For a first build, create overlay/etc/motd in your editor:

My custom Modalix image

Files under overlay/ retain their permissions and become root-owned in the image. The overlay is applied before package installation: a package may replace files outside /etc. Use a hook for changes that must happen after installation.

To install your application as a Debian package:

cp /path/to/my-app_1.0_arm64.deb custom-debs/
pib sign-debs
pib verify-debs

Add its package name, not its filename, to image.yaml:

packages:
add: [my-app]
remove: []

Packages must target arm64 or all. Kernel replacement, package removal, service enablement, and custom update scripts are covered in the customization reference.

5. Build a signed update​

pib build --sign

This builds the image, signs its SWU with your configured identity, and verifies its signature, payload hashes, and build manifest. A typical build takes several minutes, depending on your host and network. Results are in out/, including:

OutputPurpose
*.swuSigned update bundle
*.unsigned.swuBundle for a separate signing step
*.img.gzCompressed disk image for provisioning/recovery
*-boot0.beAssociated tRoot payload
*.manifest.jsonPackage versions/origins and boot payload provenance
*.cdx.jsonCycloneDX software bill of materials
SHA256SUMSArtifact checksums

To verify again, without locating the filenames yourself:

pib verify

For CI or a separate signing system, use pib build, pib sign, and pib verify as individual steps. pib sign and pib verify select the current image.yaml version, even when out/ also contains earlier versions.

Before the next build, increment the final component of version in image.yaml (for example, 3.0.0.1 to 3.0.0.2). Rebuilding the same version replaces its outputs, including an existing signed SWU. Boards enforce the image version policy.

6. Prepare for deployment​

Building and verifying a bundle does not change a board. Before deployment:

  • Configure first-boot access if you will flash a fresh board. By default root and sima are locked; an existing board's preserved credentials may survive an update. See board access.
  • Provision your CA through your authorized board-provisioning process. A stock board does not automatically trust the CA you just created.
  • Use the correct path for your task: SWUpdate for .swu, and the board's qualified media/recovery procedure for .img.gz and any required boot payloads.

See installing an SWU for SSH update commands. Validate your custom image on a recoverable development board before using it in production.

Troubleshooting​

  • Missing loop/device-mapper access: run pib doctor. The launcher supplies the required privileges, but the Linux Docker host must provide those devices.
  • ARM64 setup fails on x86: PIB registers its packaged emulator automatically. Check that the Linux Docker engine permits privileged binfmt access.
  • Interrupted image build: stop builds first, run pib clean to inspect leftover resources, then pib clean --yes to remove them. Cleanup can include other PIB projects on the same Docker host.
  • Package/bootstrap failure: inspect configs/images/mmdebstrap.log. Package repositories must remain reachable during the build.
  • New platform release: initialize a new project with that release's container, preserve your existing CA, and carry over compatible packages/customizations. See the upgrade reference.