{"id":13876018,"url":"https://github.com/alpinelinux/alpine-make-vm-image","last_synced_at":"2025-10-21T18:17:05.405Z","repository":{"id":39636309,"uuid":"101791786","full_name":"alpinelinux/alpine-make-vm-image","owner":"alpinelinux","description":"Make customized Alpine Linux disk image for virtual machines","archived":false,"fork":false,"pushed_at":"2025-02-12T12:00:19.000Z","size":115,"stargazers_count":317,"open_issues_count":9,"forks_count":109,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-19T03:25:21.583Z","etag":null,"topics":["alpine-linux","ci","deployment","disk-image","vm-images"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/alpinelinux.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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,"zenodo":null},"funding":{"github":"jirutka"}},"created_at":"2017-08-29T18:10:38.000Z","updated_at":"2025-04-14T03:46:39.000Z","dependencies_parsed_at":"2024-01-13T19:42:55.831Z","dependency_job_id":"204487cd-9c94-4183-82e7-8f81252eeb70","html_url":"https://github.com/alpinelinux/alpine-make-vm-image","commit_stats":{"total_commits":135,"total_committers":8,"mean_commits":16.875,"dds":"0.059259259259259234","last_synced_commit":"04c2e6df9628b675c82e5f0444315fdec459c6ea"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alpinelinux%2Falpine-make-vm-image","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alpinelinux%2Falpine-make-vm-image/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alpinelinux%2Falpine-make-vm-image/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alpinelinux%2Falpine-make-vm-image/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alpinelinux","download_url":"https://codeload.github.com/alpinelinux/alpine-make-vm-image/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254448578,"owners_count":22072764,"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":["alpine-linux","ci","deployment","disk-image","vm-images"],"created_at":"2024-08-06T06:00:57.299Z","updated_at":"2025-10-21T18:17:05.399Z","avatar_url":"https://github.com/alpinelinux.png","language":"Shell","funding_links":["https://github.com/sponsors/jirutka"],"categories":["Shell","deployment"],"sub_categories":[],"readme":"= Make Alpine Linux VM Image\n:script-name: alpine-make-vm-image\n:script-sha1: f17ef4997496ace524a8e8e578d944f3552255bb\n:gh-name: alpinelinux/{script-name}\n:version: 0.13.3\n\nifdef::env-github[]\nimage:https://github.com/{gh-name}/workflows/CI/badge.svg[\"Build Status\", link=\"https://github.com/{gh-name}/actions\"]\nendif::env-github[]\n\nThis project provides a script for making customized https://alpinelinux.org/[Alpine Linux] disk images for x86_64 and aarch64 footnote:[Supported since Alpine Linux v3.19. See \u003c\u003caarch64-old\u003e\u003e.] virtual machines.\nYou can choose between BIOS mode (using https://syslinux.org/[Syslinux], only for x86_64) and UEFI mode (using Linux https://docs.kernel.org/admin-guide/efi-stub.html[EFI stub]).\nIt’s quite simple (400 LoC of shell), fast (~32 seconds on GitHub Actions), requires minimum dependencies (QEMU and filesystem tools).\n\nTIP: Don’t need VM, just wanna chroot into Alpine Linux?\n     Try https://github.com/alpinelinux/alpine-chroot-install[alpine-chroot-install]!\n     Or do you want to create a custom rootfs?\n     Then https://github.com/alpinelinux/alpine-make-rootfs[alpine-make-rootfs] is for you!\n\n\n== Requirements\n\n* Linux system with common userland (Busybox or GNU coreutils)\n* POSIX-sh compatible shell (e.g. Busybox ash, dash, Bash, ZSH)\n* `qemu-img` and `qemu-nbd` tools\n* `rsync` (needed only for `--fs-skel-dir`)\n* `sfdisk` (needed only for `--partition`, `--boot-mode UEFI` and non-x86 architectures)\n* `mdev` or `udevadm` (needed only for `--partition`, `--boot-mode UEFI` and non-x86 architectures if device hotplug doesn’t work)\n* `e2fsprogs` (for ext4), `btrfs-progs` (for Btrfs), or `xfsprogs` (for XFS)\n* `dosfstools` (needed only for `--boot-mode UEFI` and non-x86 architectures)\n\nAll dependencies except the first two are automatically installed by the script when running on Alpine Linux.\n\n\n== Usage\n\nRead documentation in link:{script-name}[{script-name}].\nSee link:.github/workflows/ci.yml[] for GitHub Actions example.\n\nYou can copy link:{script-name}[{script-name}] into your repository or download it on demand, e.g.:\n\n[source, sh, subs=\"+attributes\"]\nwget https://raw.githubusercontent.com/{gh-name}/v{version}/{script-name} \\\n    \u0026\u0026 echo '{script-sha1}  {script-name}' | sha1sum -c \\\n    || exit 1\n\nOr, if you are on Alpine Linux, you can simply install the https://pkgs.alpinelinux.org/packages?name={script-name}[{script-name}] package.\n\n\n== Howtos\n\n=== Create images for aarch64 on x86_64 host\n\nAll you need to do is install the https://www.qemu.org/docs/master/user/main.html[QEMU User space emulator] for aarch64 and register it in https://docs.kernel.org/admin-guide/binfmt-misc.html[binfmt_misc] as the interpreter for aarch64 binaries.\n\nOn Alpine Linux::\n+\n[source, sh]\napk add qemu-aarch64 qemu-openrc\nrc-service qemu-binfmt start\n\nOn Debian/Ubuntu::\n+\n[source, sh]\napt-get install -y --no-install-recommends binfmt-support qemu-user-static\nupdate-binfmts --enable\n\nOn Fedora::\n+\n[source, sh]\ndnf install qemu-user-static\n\nOn GitHub Actions::\n+\n[source, yaml]\n----\n- name: Install qemu-aarch64 and register in binfmt\n  uses: jirutka/setup-alpine@v1\n  with:\n    arch: aarch64\n----\n+\nSee link:.github/workflows/ci.yml[] for a complete example.\n\nAfter that, run {script-name} with the option `--arch aarch64`.\n\n\n[[aarch64-old]]\n=== Create aarch64 image with Alpine v3.18 or older\n\nThe Linux kernel (_linux-virt_, _linux-lts_ or _linux-edge_ package) in Alpine v3.18 and earlier doesn’t have https://cateee.net/lkddb/web-lkddb/EFI_ZBOOT.html[EFI_ZBOOT] enabled, so EFI stub cannot load a compressed vmlinuz.\nWe backported it to v3.18, but then we had to revert it due to a problem with Grub (see https://gitlab.alpinelinux.org/alpine/aports/-/issues/15263[alpine/aports#15263]).\n\nIf you want to build an image with an older branch of Alpine Linux, you can, but you must install the kernel from the v3.19 branch (or newer).\nThis is relatively safe because the kernel package doesn’t have any dynamic dependencies.\n\n. Create a `repositories` file with a pinned main repository from v3.19, e.g.:\n+\n[source]\n----\n@v319 https://dl-cdn.alpinelinux.org/alpine/v3.19/main\nhttps://dl-cdn.alpinelinux.org/alpine/v3.18/main\nhttps://dl-cdn.alpinelinux.org/alpine/v3.18/community\n----\n\n. Run {script-name} with the options `--repositories-file ./repositories` and `--packages linux-virt@v319` (or `linux-lts@v319` if you use `--kernel-flavor lts`).\n\nThis will first install _linux-virt_ from v3.18, but in the later step it will reinstall it from the v3.19 branch.\n\n\n=== Create image for VMware (ESXi)\n\nVMware and disk images (virtual disks) is one big mess.\nYou can find that VMware uses the VMDK format, but the problem is that this is not a single format.\nActually it has many subformats with very different structure and various (in)compatibility with VMware hypervisors.\n\nWhen I’ve created a disk image using `qemu-img create -f vmdk` or converted Qcow2 to VMDK using `qemu-img convert -O vmdk`, vSphere client loaded this image without any problem, but the data was corrupted.\nEventually I found in some old documentation that ESXi does not support “sparse” disks…\n\nSo after many trials I found out that the least bad and functional solution is to create Qcow2 image and then convert it to VMDK using:\n\n[source, sh]\nqemu-img convert -f qcow2 -O vmdk -o adapter_type=lsilogic,subformat=monolithicFlat alpine.qcow2 alpine.vmdk\n\nUnfortunately, this creates a “thick” image, i.e. its size equals the “provisioned space”, not actually used space as in Qcow2.\nHowever, you can compress it with gzip to avoid transferring multiple gigabytes of zeros over network.\n\n\n== License\n\nThis project is licensed under http://opensource.org/licenses/MIT/[MIT License].\nFor the full text of the license, see the link:LICENSE[LICENSE] file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falpinelinux%2Falpine-make-vm-image","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falpinelinux%2Falpine-make-vm-image","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falpinelinux%2Falpine-make-vm-image/lists"}