sebatec-images

Reproducible Debian Vagrant boxes for libvirt — built with mkosi, versioned, and published via Forgejo

A lightweight build pipeline that creates ready-to-use Vagrant boxes for the libvirt provider. The images are built from scratch on Debian stable using mkosi, then packaged as distributable .box archives and published to a Forgejo package registry.

Note

Versions follow YY.MM.PP format and are tracked in vagrant/mkosi.version. Use make bump to increment before a new release.

Features

• Reproducible builds — Fully deterministic image generation from Debian stable
• Minimal footprint — Optimized with systemd-boot, ext4 root, and ESP partitions
• Vagrant-ready — Pre-configured vagrant user with insecure key and passwordless sudo
• Cloud-native — Cloud-init, systemd-networkd (DHCP on eth0), and SSH pre-enabled
• Versioned releases — Automatic semantic versioning with make bump
• One-step packaging — Converts raw images to .box archives with metadata
• Registry publishing — Direct upload to Forgejo package registry

Project Structure

.
├── Vagrantfile                      # Local development box (libvirt + sshfs)
└── vagrant/
    ├── Makefile                     # Build, bump, clean, and upload targets
    ├── mkosi.conf                   # Image configuration (Debian stable)
    ├── mkosi.repart/                # Partition scheme (ESP, BIOS, root)
    ├── mkosi.extra/                 # Overlay files (sudoers, networking, SSH keys)
    ├── mkosi.postinst.chroot        # Post-installation hook (vagrant user setup)
    ├── mkosi.postoutput             # Post-output hook (raw → qcow2 → .box)
    ├── mkosi.bump                   # Version bump script
    ├── mkosi.version                # Current version file
    └── Vagrantfile.libvirt          # Bundled Vagrantfile for packaged boxes

Prerequisites

• mkosi >= 26
• qemu-utils (for qemu-img)
• jq (JSON query tool)
• Linux host with KVM support
• For publishing: Forgejo API token (PACKAGE_API_TOKEN)

Quick Start

Build

cd vagrant
make build         # Build and package the Vagrant box
make bump          # Advance version to YY.MM.<patch+1>
make clean         # Remove build artifacts

Output artifacts are written to vagrant/mkosi.output/:

• debian-stable-<version>.raw — Raw disk image
• debian-stable-<version>.box — Vagrant box (qcow2 + metadata)
• debian-stable-<version>.efi, .vmlinuz, .initrd — Kernel artifacts

Test Locally

Add and boot the generated box:

cd vagrant/mkosi.output
vagrant box add debian-stable debian-stable-<version>.box
vagrant up

Or use the repository root Vagrantfile, which automatically discovers the debian-stable box:

vagrant up

Publish to Forgejo

cd vagrant
export PACKAGE_API_TOKEN=<your-forgejo-token>
export API_URL=https://forge.sebatec.eu/api
make upload

The box will be published to:

${API_URL}/packages/sebatec-eu/vagrant/debian-stable/<version>/libvirt.box

Warning

Publishing requires PACKAGE_API_TOKEN to be set. The Makefile will refuse to upload without it.

Versioning

Versions follow YY.MM.PP (year / month / patch):

• Patch counter resets to 0 each month
• Otherwise increments automatically
• Use make bump to advance the version in vagrant/mkosi.version

See vagrant/mkosi.bump for implementation details.

Customizing the image

• Packages — edit the Packages= list in vagrant/mkosi.conf
• Partitions — adjust the SizeMinBytes / SizeMaxBytes entries in vagrant/mkosi.repart/
• Overlay files — drop content under vagrant/mkosi.extra/ (it is copied into the image as-is)
• First-boot commands — extend vagrant/mkosi.postinst.chroot
• Box metadata — modify the provider block in vagrant/Vagrantfile.libvirt