Project-5: Automate Kria Ubuntu SD Card Image with Docker

Overview

In this project, we take everything learned so far and bring it together into a fully automated workflow for building a custom Ubuntu-based SD card image for the AMD/Xilinx Kria KR260 board.

Using Docker with ARM64 emulation, we create a clean, reproducible environment that fetches a base Ubuntu root filesystem, configures it with essential networking, SSH, locale, and user settings, and finally produces a.wic SD card image—ready to boot Kria directly.

This approach makes it easy to maintain and extend the image for future AI and FPGA applications, just by editing a script or Dockerfile. Ideal for developers looking for a robust, containerized way to prepare Kria for real-world use.

Features

• Automated Docker-based build environment for ARM64 Ubuntu images
• Customizable scripts for adding packages and post-install configurations
• Generation of .wic SD card images ready to boot on Kria boards
• Support for setting up users, SSH, networking, locale, and timezone
• Shared directories for easy script and file management between host and container

Prerequisites

A host computer with the following services properly configured and running:

• Operating System: Ubuntu 22.04 LTS (or compatible)
• Docker Engine (version: 28.1.1, build 4eba377)
• QEMU: Version supporting ARM64 emulation

This tutorial builds on the previous two tutorials:

• Project 2: Build a Custom PetaLinux Image for Kria Board
• Project 4: Turn Ubuntu Rootfs into a Bootable Image for Kria

Note: You will need the following components built in Project 2:

• Linux kernel: Image
• Device Tree Blob: system.dtb

Install Required Packages

Here are just a quick recap of what we already setup in the Project 4: Turn Ubuntu Rootfs into a Bootable Image for Kria:

• Install Docker Engine on your system by following the official instructions provided here.
• Register QEMU to enable ARM64 emulation:.

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

• Set up a Docker builder that supports ARM64:

docker buildx create --name kria-builder --use

Getting Started

This project is built on top of a GitHub repository that consolidates all the key scripts and configurations developed in Project-4. All automation logic for building, configuring, and packaging the Ubuntu root filesystem into a bootable.wic SD card image is included there.

This repository is designed to be modular and extensible—ideal for adding new packages or tweaking system settings for advanced Kria-based AI applications.

1. Clone the repository:

git clone https://github.com/s59mz/kria-build-system.git
cd kria-build-system

2. ExploreDirectory Structure

kria-build-system/
├── boot/
│  ├── boot.scr
│  ├── Image
│  └── system.dtb
├── build.sh
├── Dockerfile
├── LICENSE
├── output/
│  └── custom-linux-image.wic.zip
├── README.md
├── rootfs/
├── run.sh
├── scripts/
│  ├── additional-packages.sh
│  ├── build-kria-image.sh
│  ├── make_wic_image.sh
│  ├── mount-chroot-ro.sh
│  ├── post-config.sh
│  └── umount-chroot-ro.sh
└── workspace/
└── ubuntu-base-22.04-base-arm64.tar.gz

• boot/: Contains bootloader files, kernel and DTS (boot.scr, Image, system.dtb). Could be updated with a new custom kernel files.
• scripts/: Shell scripts for building and configuring the image
• workspace/: Contains the base Ubuntu ARM64 root filesystem
• output/: Directory where the final.wic image is stored

3. Read README.md

Follow the instructions provided in the Readme file.

Usage

1. Build the Docker Image

./build.sh

2. Run the Docker Container

./run.sh

This command mounts necessary directories and shares the host’s /dev to the container, which is required for loop device operations during image creation.

3. Build the SD Card Image

Inside the Docker container, execute:

./scripts/build-kria-image.sh

This script performs the following steps:

• Downloads and extracts the base Ubuntu ARM64 root filesystem
• Mounts the root filesystem and chroots into it
• Installs additional packages specified in additional-packages.sh
• Applies post-configuration settings from post-config.sh
• Creates a.wic SD card image and compresses it into a.zip file

The final image will be located at output/custom-linux-image.wic.zip.

Customization

• To add additional packages, edit scripts/additional-packages.sh.
• For post-install configurations (e.g., setting up users, SSH, networking), modify scripts/post-config.sh.

Troubleshooting

In case your build fails due to Segmentation Faults, try this command and rebuild again:

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

Boot Kria board from SD card

To boot the Kria board from the SD card, flash the generated custom-linux-image.wic.zip image file to an SD card using a tool like Balena Etcher or similar.

Once flashed, insert the SD card into the SD card slot on the Kria board and power on the board. U-Boot will launch from the QSPI flash, which contains the pre-installed BOOT.BIN and execute the boot.scr script located on the SD card.

If everything is set up correctly, the system will boot into your custom Ubuntu root filesystem. Log in using the username and password you set up in the post-config.sh file, and verify, if everything works as expected.

Final Notes

If you’ve made it this far—congratulations! You now have a fully automated Docker-based build system for generating a bootable Ubuntu SD card image for the Kria platform.

Feel free to leave a comment, ask questions, or share suggestions below. I’d love to hear your feedback and ideas on how to improve or customize this build for even more powerful Kria-based projects!