https://github.com/ptrsr/pi-ci Skip to content Navigation Menu Toggle navigation Sign in * Product + Actions Automate any workflow + Packages Host and manage packages + Security Find and fix vulnerabilities + Codespaces Instant dev environments + GitHub Copilot Write better code with AI + Code review Manage code changes + Issues Plan and track work + Discussions Collaborate outside of code Explore + All features + Documentation + GitHub Skills + Blog * Solutions By size + Enterprise + Teams + Startups By industry + Healthcare + Financial services + Manufacturing By use case + CI/CD & Automation + DevOps + DevSecOps * Resources Topics + AI + DevOps + Security + Software Development + View all Explore + Learning Pathways + White papers, Ebooks, Webinars + Customer Stories + Partners * Open Source + GitHub Sponsors Fund open source developers + The ReadME Project GitHub community articles Repositories + Topics + Trending + Collections * Enterprise + Enterprise platform AI-powered developer platform Available add-ons + Advanced Security Enterprise-grade security features + GitHub Copilot Enterprise-grade AI features + Premium Support Enterprise-grade 24/7 support * Pricing Search or jump to... Search code, repositories, users, issues, pull requests... Search [ ] Clear Search syntax tips Provide feedback We read every piece of feedback, and take your input very seriously. [ ] [ ] Include my email address so I can be contacted Cancel Submit feedback Saved searches Use saved searches to filter your results more quickly Name [ ] Query [ ] To see all available qualifiers, see our documentation. Cancel Create saved search Sign in Sign up Reseting focus You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert {{ message }} ptrsr / pi-ci Public * Notifications You must be signed in to change notification settings * Fork 5 * Star 58 Prepare Raspberry Pi 3, 4 & 5 configurations using a virtual machine. License View license 58 stars 5 forks Branches Tags Activity Star Notifications You must be signed in to change notification settings * Code * Issues 0 * Pull requests 0 * Actions * Projects 0 * Security * Insights Additional navigation options * Code * Issues * Pull requests * Actions * Projects * Security * Insights ptrsr/pi-ci This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. master BranchesTags Go to file Code Folders and files Name Name Last commit Last commit message date Latest commit History 66 Commits .github/workflows .github/ workflows .vscode .vscode src src test test tools tools .dockerignore .dockerignore .gitignore .gitignore LICENSE LICENSE README.md README.md dockerfile dockerfile View all files Repository files navigation * README * License PI-CI PI-CI A raspberry Pi emulator in a Docker image that lets developers easily prepare and flash RPi configurations. Overview The PI-CI project enables developers to easily: * Run a RPi VM. * Prepare a configuration inside a RPi VM. * Flash a RPi VM image to a physical SD card. Example use cases: * Preconfigure Raspberry Pi servers that work from first boot. * Create reproducible server configurations using Ansible. * Automate the distribution of configurations through a CI pipeline. * Test ARM applications in a virtualized environment. Key features: * Pi 3, 4 and 5 support * 64 bit (ARMv8) Raspberry PI OS (Bookworm) included + image: 2024-07-04-raspios-bookworm-arm64-lite + kernel: 6.6-y * Internet access * No root required * Safe, fully reproducible from source * Tested and stable Usage $ docker pull ptrsr/pi-ci $ docker run --rm -it ptrsr/pi-ci > usage: docker run [docker args] ptrsr/pi-ci [command] [optional args] > > PI-CI: the reproducible PI emulator. > > positional arguments: > command [init, start, resize, flash, export] > > optional arguments: > -h, --help show this help message and exit > -v show verbose output > > Refer to https://github.com/ptrsr/pi-ci for the full README on how to use this program. Each command has a help message, for example: docker run --rm -it ptrsr/pi-ci start -h. Start machine Simply run a ptrsr/pi-ci container with the start command: docker run --rm -it ptrsr/pi-ci start The emulator will automatically log into root. Persistence To save the resulting image, use a bind mount to /dist: docker run --rm -it -v $PWD/dist:/dist ptrsr/pi-ci start NOTE: this example will create and mount the dist folder in the current working directory of the host. To restart the image, simply use the same bind mount. SSH access To enable ssh access, run the container with port 2222 exposed. docker run --rm -p 2222:2222 ptrsr/pi-ci start Then ssh into the virtual Pi: ssh root@localhost -p 2222 Resize The default image is 2 gigabytes in size. This can be increased (but not decreased!) through the resize command. Increasing the size can be done in two ways: 1. by providing a path to the target device (e.g. /dev/mmcblk0). The resulting image will be the same size as the target device. 2. By providing a specific size in gigabytes, megabytes or bytes (e.g. 8G, 8192M, 8589934592). For an image to be flashed to a device, the image has to be the less or equal to the device size. docker run --rm -it -v $PWD/dist:/dist --device=/dev/mmcblk0 ptrsr/pi-ci resize /dev/mmcblk0 NOTE: although an SD card will say a specific size (such as 16GB), the device is usually if not always smaller (GB vs GiB). Therefore, using a target device is recommended. NOTE: resizing can potentially be a dangerous operation. Always make backup of the image.qcow2 file in the dist folder before proceeding. Flash To flash the prepared image to a storage device (such as an SD card), provide the container with the device and run the flash command: docker run --rm -it -v $PWD/dist:/dist --device=/dev/mmcblk0 ptrsr/pi-ci flash /dev/mmcblk0 On the first boot of the real RPi, a program will automatically inflate the root partition to fill the rest of the target device. Export The export function converts the virtual (.qcow2) image to a raw (.img) image. This is particularly handy when it is not possible to directly flash an image (e.g. when using WSL), as the raw image can be flashed using tools like Balena Etcher. The export command takes two optional arguments; the --input and --output path; docker run --rm -it -v $PWD/dist:/dist ptrsr/pi-ci export --input /dist/image.qcow2 --output /dist/image.img The raw image should pop up alongside the virtual image in the mounted dist folder in the example above. Automation Using Ansible, it is possible to automate the whole configuration process. Ansible requires docker-py to be installed. This can be done using pip3 install docker-py. Ansible can take care of: 1. Starting the VM 2. Running tasks in the VM 3. Stopping the VM An example configuration can be found in the ./test folder of this repository. To start the test process, run: ansible-playbook -i ./test/hosts.yml ./test/main.yml Tips * Do not forget to set a password for root and disable PermitRootLogin in the /etc/ssh/sshd_config for security. * Do not stop or kill the Docker container while the VM is running, this WILL corrupt the image! * Make sure to regularly back up the distro.qcow2 image. Versions PI-CI has automatically been tested on Ubuntu 24.04 using GitHub Actions. Any other distro should work with the following software versions (or higher, perhaps): Software Version Ansible 2.5.1 docker-py 4.4.4 Docker 19.03.6 License PI-CI is licensed under GPLv3. About Prepare Raspberry Pi 3, 4 & 5 configurations using a virtual machine. Topics docker raspberry-pi ansible continuous-integration virtual-machine container reproducibility Resources Readme License View license Activity Stars 58 stars Watchers 4 watching Forks 5 forks Report repository Releases 1 Export image shrinking & RPi 5 support confirmation Latest Nov 28, 2023 Languages * Python 95.0% * Shell 5.0% Footer (c) 2024 GitHub, Inc. Footer navigation * Terms * Privacy * Security * Status * Docs * Contact * Manage cookies * Do not share my personal information You can't perform that action at this time.