{"id":13582531,"url":"https://github.com/mkaczanowski/packer-builder-arm","last_synced_at":"2025-04-04T20:16:08.873Z","repository":{"id":37952431,"uuid":"217678874","full_name":"mkaczanowski/packer-builder-arm","owner":"mkaczanowski","description":"Packer plugin to build ARM images","archived":false,"fork":false,"pushed_at":"2024-08-12T16:13:06.000Z","size":14408,"stargazers_count":323,"open_issues_count":33,"forks_count":105,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-28T19:12:03.625Z","etag":null,"topics":["arm","packer","packer-builder"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mkaczanowski.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":"2019-10-26T08:25:56.000Z","updated_at":"2025-02-10T14:57:15.000Z","dependencies_parsed_at":"2023-02-16T11:00:47.866Z","dependency_job_id":"b8f9c384-77e8-42f8-9fad-893ca6a2fe59","html_url":"https://github.com/mkaczanowski/packer-builder-arm","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkaczanowski%2Fpacker-builder-arm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkaczanowski%2Fpacker-builder-arm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkaczanowski%2Fpacker-builder-arm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkaczanowski%2Fpacker-builder-arm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mkaczanowski","download_url":"https://codeload.github.com/mkaczanowski/packer-builder-arm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247242683,"owners_count":20907134,"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":["arm","packer","packer-builder"],"created_at":"2024-08-01T15:02:48.174Z","updated_at":"2025-04-04T20:16:08.848Z","avatar_url":"https://github.com/mkaczanowski.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# Packer builder ARM\n\n[![Build Status][github-badge]][github]\n[![GoDoc][godoc-badge]][godoc]\n[![GoReportCard][report-badge]][report]\n[![Docker Pulls][docker-pulls]][docker-hub]\n[![Docker Image Size][docker-size]][docker-hub]\n[![Docker Image Version][docker-version]][docker-hub]\n\n[github-badge]:https://img.shields.io/github/actions/workflow/status/mkaczanowski/packer-builder-arm/docker.yml?branch=master\n[github]: https://github.com/mkaczanowski/packer-builder-arm/actions\n[godoc-badge]: https://godoc.org/github.com/mkaczanowski/packer-builder-arm?status.svg\n[godoc]: https://godoc.org/github.com/mkaczanowski/packer-builder-arm\n[report-badge]: https://goreportcard.com/badge/github.com/mkaczanowski/packer-builder-arm\n[report]: https://goreportcard.com/report/github.com/mkaczanowski/packer-builder-arm\n[docker-hub]: https://hub.docker.com/r/mkaczanowski/packer-builder-arm\n[docker-pulls]: https://img.shields.io/docker/pulls/mkaczanowski/packer-builder-arm\n[docker-size]: https://img.shields.io/docker/image-size/mkaczanowski/packer-builder-arm\n[docker-version]: https://img.shields.io/docker/v/mkaczanowski/packer-builder-arm?sort=semver\n\n\nThis plugin allows you to build or extend ARM system image. It operates in two modes:\n* new - creates empty disk image and populates the rootfs on it\n* reuse - uses already existing image as the base\n* resize - uses already existing image but resize given partition (ie. root)\n\nPlugin mimics standard image creation process, such as:\n* building base empty image (dd)\n* partitioning (sgdisk / sfdisk)\n* filesystem creation (mkfs.type)\n* partition mapping (losetup)\n* filesystem mount (mount)\n* populate rootfs (tar/unzip/xz etc)\n* setup qemu + chroot\n* customize installation within chroot\n\nThe virtualization works via [binfmt_misc](https://en.wikipedia.org/wiki/Binfmt_misc) kernel feature and qemu.\n\nSince the setup varies a lot for different hardware types, the example configuration is available per \"board\". Currently the following boards are supported (feel free to add more):\n* bananapi-r1 (Archlinux ARM)\n* beaglebone-black (Archlinux ARM, Debian)\n* jetson-nano (Ubuntu)\n* odroid-u3 (Archlinux ARM)\n* odroid-xu4 (Archlinux ARM, Ubuntu)\n* parallella (Ubuntu)\n* raspberry-pi (Archlinux ARM, Raspbian)\n* raspberry-pi-3 (Archlinux ARM (armv8))\n* raspberry-pi-4 (Archlinux ARM (armv7), Ubuntu 20.04 LTS))\n* wandboard (Archlinux ARM)\n* armv7 generic (Alpine, Archlinux ARM)\n\n# Quick start\n```\ngit clone https://github.com/mkaczanowski/packer-builder-arm\ncd packer-builder-arm\ngo mod download\ngo build\n\nsudo packer build boards/odroid-u3/archlinuxarm.json\n```\n## Run in Docker\nThis method is primarily for macOS users where is no native way to use qemu-user-static, loop mount Linux specific filesystems and install all above mentioned Linux specific tools (or Linux users, who do not want to setup packer and all the tools).\n\nThe container is a multi-arch container (linux/amd64 or linux/arm64), that can be used on Intel (x86_64) or Apple M1 (arm64) Macs and also on Linux machines running linux (x86_64 or aarch64) kernels.\n\n\u003e **_NOTE:_** On Macs: Don't run `go build .` (that produces a **darwin** binary) and then run below `docker run ...` commands from the same folder to avoid the error `error initializing builder 'arm': fork/exec /build/packer-builder-arm: exec\nformat error` (**linux** packer process within docker fails to load the outside container compiled packer-builder-arm binary due to being a **darwin** binary). Delete any local binary via `rm -r packer-*` to solely use the binary already included and provided by the container.\n\n### Usage via container from Docker Hub:\n\nPull the latest version of the container to ensure the next commands are not using an old cached version of the container :\n```\ndocker pull mkaczanowski/packer-builder-arm:latest\n```\n\nBuild a board:\n```\ndocker run --rm --privileged -v /dev:/dev -v ${PWD}:/build mkaczanowski/packer-builder-arm:latest build boards/raspberry-pi/raspbian.json\n```\nBuild a board with more system packages (e.g. bmap-tools, zstd) can be added via the parameter `-extra-system-packages=...`:\n```\ndocker run --rm --privileged -v /dev:/dev -v ${PWD}:/build mkaczanowski/packer-builder-arm:latest build boards/raspberry-pi/raspbian.json -extra-system-packages=bmap-tools,zstd\n```\n\n\u003e **_NOTE:_** In above commands **latest** can also be replaced via e.g. **1.0.3** to get a specific container version.\n\n### Usage via local container build (supports amd64/aarch64 hosts):\nBuild the container locally:\n```\ndocker build -t packer-builder-arm -f docker/Dockerfile .\n```\nRun packer via the local built container:\n```\ndocker run --rm --privileged -v /dev:/dev -v ${PWD}:/build packer-builder-arm build boards/raspberry-pi/raspbian.json\n```\n\n# Dependencies\n* `sfdisk / sgdisk`\n* `e2fsprogs`\n* `parted` (resize mode)\n* `resize2fs` (resize mode)\n* `qemu-img` (resize mode)\n\n# Configuration\nConfiguration is split into 3 parts:\n* remote file config\n* image config\n* qemu config\n\n## Remote file\nDescribes the remote file that is going to be used as base image or rootfs archive (depending on `image_build_method`)\n\n```\n\"file_urls\" : [\"http://os.archlinuxarm.org/os/ArchLinuxARM-odroid-xu3-latest.tar.gz\"],\n\"file_checksum_url\": \"http://hu.mirror.archlinuxarm.org/os/ArchLinuxARM-odroid-xu3-latest.tar.gz.md5\",\n\"file_checksum_type\": \"md5\",\n\"file_unarchive_cmd\": [\"bsdtar\", \"-xpf\", \"$ARCHIVE_PATH\", \"-C\", \"$MOUNTPOINT\"],\n\"file_target_extension\": \"tar.gz\",\n```\n\nDownloads of the `file_urls` are done with the help of `github.com/hashicorp/go-getter`, which supports various protocols: local files, http(s) and various others, see https://github.com/hashicorp/go-getter#supported-protocols-and-detectors). Downloading via more protocols can be done by using other tools (curl, wget, rclone, ...) before running packer and referencing the downloaded files as local file in `file_urls`.\n\nThe `file_unarchive_cmd` is optional and should be used if the standard golang archiver can't handle the archive format.\n\nRaw images format (`.img` or `.iso`) can be used by defining the `file_target_extension` appropriately.\n\n## Image config\nThe base image description (size, partitions, mountpoints etc).\n\n```\n\"image_build_method\": \"new\",\n\"image_path\": \"odroid-xu4.img\",\n\"image_size\": \"2G\",\n\"image_type\": \"dos\",\n\"image_partitions\": [\n    {\n        \"name\": \"root\",\n        \"type\": \"8300\",\n        \"start_sector\": \"4096\",\n        \"filesystem\": \"ext4\",\n        \"size\": \"0\",\n        \"mountpoint\": \"/\"\n    }\n],\n```\n\nThe plugin doesn't try to detect the image partitions because that varies a lot. Instead it solely depend on `image_partitions` specification, so you should set that even if you reuse the image (`method` = reuse).\n\n## Qemu config\nAnything qemu related:\n\n```\n\"qemu_binary_source_path\": \"/usr/bin/qemu-arm-static\",\n\"qemu_binary_destination_path\": \"/usr/bin/qemu-arm-static\"\n```\n\nThe arm instruction set (default=`armv7l` for qemu-arm-static) to be emulated can be defined via the `QEMU_CPU` variable. To switch to `armv6l` (check with `uname -m` as provission command) run packer e.g. via:\n* `QEMU_CPU=arm1176 packer build ...`\n* `docker run -e QEMU_CPU=arm1176 ...`\n\n# Chroot provisioner\nTo execute command within chroot environment you should use chroot communicator:\n```\n\"provisioners\": [\n {\n   \"type\": \"shell\",\n   \"inline\": [\n     \"pacman-key --init\",\n     \"pacman-key --populate archlinuxarm\"\n   ]\n }\n]\n```\nThis plugin doesn't resize partitions on the base image. However, you can easily expand partition size at the boot time with a systemd service. [Here](./boards/raspberry-pi/archlinuxarm.json) you can find real-life example, where a raspberry pi root-fs partition expands to all available space on sdcard.\n\n# Flashing\nTo dump image on device you can use [custom postprocessor](https://github.com/mkaczanowski/packer-post-processor-flasher) (really wrapper around `dd` with some sanity checks):\n```\n\"post-processors\": [\n {\n     \"type\": \"flasher\",\n     \"device\": \"/dev/sdX\",\n     \"block_size\": \"4096\",\n     \"interactive\": true\n }\n]\n```\n\n# Other\n## Generating rootfs archive\nWhile image (`.img`) format is useful for most cases, you might want to use\nrootfs for other purposes (ex. export to docker). This is how you can generate\nrootfs archive instead of image:\n```\n\"image_path\": \"odroid-xu4.img\" # generates image\n\"image_path\": \"odroid-xu4.img.tar.gz\" # generates rootfs archive\n```\n\n## Resizing image\nCurrently resizing is only limited to expanding single `ext{2,3,4}` partition with `resize2fs`. This is often requested feature where already built image is given and we need to expand the main partition to accommodate changes made in provisioner step (ie. installing packages).\n\nTo resize a partition you need to set `image_build_method` to `resize` mode and set selected partition size to `0`, for example:\n```\n\"builders\": [\n  {\n    \"type\": \"arm\",\n    \"image_build_method\": \"resize\",\n    \"image_partitions\": [\n      {\n        \"name\": \"boot\",\n        ...\n      },\n      {\n        \"name\": \"root\",\n        \"size\": \"0\",\n        ...\n      }\n    ],\n    ...\n  }\n]\n```\n\nComplete examples:\n\n- [`boards/raspberry-pi/raspbian-resize.json`](./boards/raspberry-pi/raspbian-resize.json)\n- [`boards/beaglebone-black/ubuntu.pkr.hcl`](./boards/beaglebone-black/ubuntu.pkr.hcl)\n\n## Docker\nWith `artifice` plugin you can pass rootfs archive to docker plugins\n```\n\"post-processors\": [\n    [{\n        \"type\": \"artifice\",\n        \"files\": [\"rootfs.tar.gz\"]\n    },\n    {\n        \"type\": \"docker-import\",\n        \"repository\": \"mkaczanowski/archlinuxarm\",\n        \"tag\": \"latest\"\n    }],\n    ...\n]\n```\n\n## CI/CD\nThis is the live example on how to use github actions to push image to docker image registry:\n```\ncat .github/workflows/archlinuxarm-armv7-docker.yml\n```\n\n## How is this plugin different from `solo-io/packer-builder-arm-image`\nhttps://github.com/hashicorp/packer/pull/8462\n\n# Examples\nFor more examples please see:\n```\ntree boards/\n```\n\nThe repository also includes some arm typical scripts to e.g. resize partitions on first boot or more extensive\nprovision scripts:\n\n```\ntree scripts/\n```\n\nA big resource for packer provisions scripts is the [GitHub Actions runner images](https://github.com/actions/runner-images) repository.\n\n# Troubleshooting\nMany of the reported issues are platform/OS specific. If you happen to have\nproblems, the first question you should ask yourself is:\n\u003e Is my setup faulty? or is there an actual issue?\n\nTo answer that question, I'd recommend reproducing the error on the VM, for\ninstance:\n```\ncd packer-builder-arm\nvagrant up\nvagrant provision\n```\n\u003e Note: For this the disksize plugin is needed if not already installed `vagrant plugin install vagrant-disksize`\n\n# Demo\n[![asciicast](https://asciinema.org/a/7ad1nm2Q7DRFVlHpqAknPolNo.svg)](https://asciinema.org/a/7ad1nm2Q7DRFVlHpqAknPolNo)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkaczanowski%2Fpacker-builder-arm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmkaczanowski%2Fpacker-builder-arm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkaczanowski%2Fpacker-builder-arm/lists"}