{"id":15051099,"url":"https://github.com/jerome-maurin/vmdb2-wrapper","last_synced_at":"2026-03-10T06:33:06.264Z","repository":{"id":163354781,"uuid":"258378914","full_name":"Jerome-Maurin/vmdb2-wrapper","owner":"Jerome-Maurin","description":"Simple wrapper for vmdb2, to build armhf \u0026 arm64 board images for SD-card using u-boot Debian packages, flash-kernel and Debian kernels","archived":false,"fork":false,"pushed_at":"2024-07-16T08:47:07.000Z","size":1604,"stargazers_count":8,"open_issues_count":1,"forks_count":5,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-24T03:53:08.218Z","etag":null,"topics":["ansible","arm64-images","armhf-images","board","bootable-media","cubieboard-images","debian","debian-kernels","debian-linux","debian-packages","debootstrap","linux","odroid-images","pine64-images","qemu-debootstrap","sd-card-image","u-boot","uboot-debian-packages","vmdb2","yaml-files"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Jerome-Maurin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-24T01:58:44.000Z","updated_at":"2025-01-08T16:46:34.000Z","dependencies_parsed_at":null,"dependency_job_id":"84044a53-bc75-4934-81af-d5ab0887ce58","html_url":"https://github.com/Jerome-Maurin/vmdb2-wrapper","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jerome-Maurin%2Fvmdb2-wrapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jerome-Maurin%2Fvmdb2-wrapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jerome-Maurin%2Fvmdb2-wrapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jerome-Maurin%2Fvmdb2-wrapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Jerome-Maurin","download_url":"https://codeload.github.com/Jerome-Maurin/vmdb2-wrapper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248143145,"owners_count":21054714,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible","arm64-images","armhf-images","board","bootable-media","cubieboard-images","debian","debian-kernels","debian-linux","debian-packages","debootstrap","linux","odroid-images","pine64-images","qemu-debootstrap","sd-card-image","u-boot","uboot-debian-packages","vmdb2","yaml-files"],"created_at":"2024-09-24T21:30:54.135Z","updated_at":"2026-03-10T06:33:06.173Z","avatar_url":"https://github.com/Jerome-Maurin.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# VMDB2-Wrapper\n\n\n[![actions build ](https://github.com/Jerome-Maurin/vmdb2-wrapper/workflows/Build%20images%20matrix/badge.svg)](https://github.com/Jerome-Maurin/vmdb2-wrapper/actions)\n\nVMDB2-Wrapper is a simple wrapper for [`vmdb2`](https://vmdb2.liw.fi/), to build armhf \u0026 arm64 board images for SD-card using `u-boot` Debian packages, `flash-kernel` and Debian kernels.\n\nSource code for `vmdb2` can be found on [Lars Wirzenius' Gitlab](https://gitlab.com/larswirzenius/vmdb2/) or [his own Gitano server](http://git.liw.fi/vmdb2/).\n\nThe Raspberry Pi different models are already [supported by Debian](https://raspi.debian.net).\u003cbr\u003e\nFYI these images are also [build using `vmdb2`](https://salsa.debian.org/raspi-team/image-specs/).\n\n# Table of contents\n\n- [Supported Platforms](#supported-platforms)\n- [TL;DR Getting started](#tldr-getting-started)\n- [How to build an image](#how-to-build-an-image)\n  * [Setting up the environment](#setting-up-the-environment)\n  * [Choosing the right target](#choosing-the-right-target)\n  * [Building the image](#building-the-image)\n- [Writing the image to an SD-card](#writing-the-image-to-an-sd-card)\n- [Customizing the image by using an Ansible-playbook](#customizing-the-image-by-using-an-ansible-playbook)\n- [Needed packages](#needed-packages)\n- [FAQ](#faq)\n  * [Why must the build be run as root?](#why-must-the-build-be-run-as-root-)\n  * [How to add the support for a new board?](#how-to-add-the-support-for-a-new-board-)\n- [Potential issues](#potential-issues)\n  * [Cleanup old cache](#cleanup-old-cache)\n\n# Supported Platforms\n\nFIXME\n\n# TL;DR Getting started\n\nYou can either download an already built image from [the project's Github Releases](https://github.com/Jerome-Maurin/vmdb2-wrapper/releases) or [the project's Github Actions (nigthly builds)](https://github.com/Jerome-Maurin/vmdb2-wrapper/actions) (needs to be logged-in) and then skip to the [**Writing the image to an SD-card**](#writing-the-image-to-an-sd-card) section.\n\n### Or\n\nYou can build the image yourself using a Debian (or an Ubuntu, you'll need to adapt the Debian procedure).\n\n# How to build an image\n\n## Setting up the environment (Bookworm)\n\nOn a freshly installed minimalist Debian Bookworm (with sudo installed), use this command to install needed packages:\n\n    sudo apt install vmdb2 zerofree curl ansible python3-distutils qemu-user-static binfmt-support\n\nThe purpose behind each of those packages is explained in the [**Needed packages**](#needed-packages) section.\n\n### Building on Buster\n\nvmdb2 version 0.13.2.\n\nInstalling zerofree is not needed in this version.\n\nThe `vmdb2` version in Debian Buster lacks a critical feature which forces the installation of Bullseye's version.\u003cbr\u003e\nEither add the Bullseye repository to your `sources.list` (be careful to [limit the package to vmdb2](https://wiki.debian.org/AptConfiguration#apt_preferences_.28APT_pinning.29)) or retrieve and install [the Bullseye package](https://packages.debian.org/bullseye/all/vmdb2/download) manually.\u003cbr\u003e\nFor example (manual install):\n\n    wget http://ftp.de.debian.org/debian/pool/main/v/vmdb2/vmdb2_0.22-1_all.deb\n    sudo apt install ./vmdb2_0.22-1_all.deb\n\n### Building on Bullseye\n\nvmdb2 version 0.22.\n\nInstalling zerofree is not needed in this version.\n\nFIXME\n\n## Choosing the right target\n\nEach Yaml file corresponds to a single board using the naming convention BOARD_RELEASE_ARCH_vmdb2-MINVERSION.yaml where:\n  - BOARD is the board's name.\n  - RELEASE is the expected Debian release.\n  - ARCH is the expected architecture (armhf or arm64 for example).\n  - MINVERSION is vmdb2's minimum required version for the Yaml file to work.\u003cbr\u003e\n    FYI versions of `vmdb2` are retro-compatible with older yaml files versions (0.14.1 yaml files will work with version 0.14.1+).\n\n## Building the image\n\nFor the time being `vmdb2` needs to be run as root, see [**Why must the build be run as root?**](#why-must-the-build-be-run-as-root-) for more details.\n\nUse `head` on the file corresponding to your board and run the command present in the comment on the first line.\n\n`vmdb2` command generic example:\n\n    sudo vmdb2 BOARD_RELEASE_ARCH_vmdb2-MINVERSION.yaml --output BOARD_RELEASE_ARCH.img --rootfs-tarball RELEASE_ARCH_rootfs.tgz --log=stderr\n\n### Or\n\nYou can run the following oneliner if you prefer:\n\n    eval $(head -n1 BOARD_RELEASE_ARCH_vmdb2-MINVERSION.yaml | sed 's/^.*: \\(.*\\)$/\\1/g')\n\nThe resulting image will be called `BOARD_RELEASE_ARCH.img`\n\n# Writing the image to an SD-card\n\nTo write the `.img` file to an sdcard, use `dd`.\n\nFor example:\n\n    sudo dd bs=64k status=progress oflag=dsync if=cubietruck_buster_armhf.img of=/dev/mmcblk1\n\nMake sure `/dev/mmcblkN` is the correct SD-card (by using `lsblk` for example).\n\nIn case the image comes from Github Releases or Github Actions you could use something like that:\n\n    zcat cubietruck_buster_armhf.img.bz2.zip | bunzip2 -c -d | sudo dd bs=64k status=progress oflag=dsync of=/dev/mmcblk1\n\n# Default login\n\nAs vmdb2 produces a standard Debian distribution, there is a default `root`\naccount, that is passwordless. If you boot a \"factory\" image, just enter the\nlogin `root`; no password will be prompted, and you will have full access to\nthe system.\n\n# Customizing the image by using an Ansible-playbook\n\nFor Ansible use `vmdb2-ansible.yaml.exemple` as a starting point, create a file named `vmdb2-ansible.yaml` to write an Ansible-playbook that will be used by `vmdb2`.\n\n# Needed packages\n\nWhy do I need those packages on my system to run a image build?\n\n`zerofree` is needed by vmdb2 since version 0.25 [(see here)](http://git.liw.fi/vmdb2/commit/?id=470b0a05ad7717139897f08e24f48d6fedc2a8d6a).\n\nUnfortunately, the [dependency list in the Bookworm package](https://packages.debian.org/bookworm/vmdb2) is missing zerofree, which means we need to install it manualy.\n\nThis is fixed in [Trixie](https://packages.debian.org/trixie/vmdb2).\n\n******************************\n\n`curl` is needed to fetch some binaries from the internet.\n\n******************************\n\n`ansible` is needed for the build to support customizing the image with an ansible playbook.\n\nIn some cases the needed package `python3-distutils` might not be installed, which can trigger an error in the ansible part.\u003cbr\u003e\nMake sure it is installed.\n\nYou can always comment or remove the call to ansible roles in the yaml files if you don't want to install it.\n\n******************************\n\nExtra packages needed for cross-compile build (use of qemu-debootstrap in yaml, default):\n\n`qemu-user-static` and `binfmt-support`\n\nYou can always replace `qemu-debootstrap` by `debootstrap` to build natively without needing `qemu-user-static` \u0026 `binfmt-support`, but in case you don't want to change the yaml files and you don't mind having `qemu-user-static` \u0026 `binfmt-support` on your system, `qemu-debootstrap` will also work for native builds with almost no overhead.\n\n# FAQ\n\n## Why must the build be run as root?\n\nFor the time being it is easier to be root for the abilities to create /dev/loops and mount/unmount them.\u003cbr\u003e\nAn alternative could be available later.\n\n## How to add the support for a new board?\n\nThe best starting point is the `cubieboard2_buster_armhf_vmdb2-0.14.1.yaml` file which is the simplest.\u003cbr\u003e\nFIXME\u003cbr\u003e\nIs the card supported by flash kernel?\u003cbr\u003e\nIf not, ..., comment the rm of /etc/flash-kernel/machine, if not kernel update wont work\u003cbr\u003e\nSame if flash-kernel cannot retrieve the card's name by looking in /proc/device-tree/model\u003cbr\u003e\nFor example in case something else than U-Boot is used as bootloader\u003cbr\u003e\nFIXME\n\n# Potential issues\n\n## Cleanup old cache\n\nIf you face any issue when running the built image, try removing the corresponding cache file `RELEASE_ARCH_rootfs.tbz` and rebuilding the image.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjerome-maurin%2Fvmdb2-wrapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjerome-maurin%2Fvmdb2-wrapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjerome-maurin%2Fvmdb2-wrapper/lists"}