{"id":15116049,"url":"https://github.com/ptrsr/pi-ci","last_synced_at":"2025-05-15T11:04:00.123Z","repository":{"id":127408453,"uuid":"367995470","full_name":"ptrsr/pi-ci","owner":"ptrsr","description":"Prepare Raspberry Pi 3, 4 \u0026 5 configurations using a virtual machine.","archived":false,"fork":false,"pushed_at":"2025-03-05T22:21:34.000Z","size":6575,"stargazers_count":717,"open_issues_count":1,"forks_count":44,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-04-07T16:01:44.785Z","etag":null,"topics":["ansible","container","continuous-integration","docker","raspberry-pi","reproducibility","virtual-machine"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ptrsr.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":"2021-05-16T22:12:53.000Z","updated_at":"2025-04-02T14:37:38.000Z","dependencies_parsed_at":"2023-06-28T19:16:32.794Z","dependency_job_id":"59e4fda2-fd71-423c-ba31-cb85adca7eaa","html_url":"https://github.com/ptrsr/pi-ci","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ptrsr%2Fpi-ci","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ptrsr%2Fpi-ci/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ptrsr%2Fpi-ci/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ptrsr%2Fpi-ci/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ptrsr","download_url":"https://codeload.github.com/ptrsr/pi-ci/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248941785,"owners_count":21186921,"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","container","continuous-integration","docker","raspberry-pi","reproducibility","virtual-machine"],"created_at":"2024-09-26T01:44:08.305Z","updated_at":"2025-04-14T18:52:49.558Z","avatar_url":"https://github.com/ptrsr.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# PI-CI [![PI-CI](https://github.com/ptrsr/pi-ci/actions/workflows/main.yml/badge.svg?branch=master)](https://github.com/ptrsr/pi-ci/actions/workflows/main.yml)\nA raspberry Pi emulator in a [Docker image](https://hub.docker.com/r/ptrsr/pi-ci) that lets developers easily prepare and flash RPi configurations.\n\n## Overview\nThe PI-CI project enables developers to easily:\n- Run a RPi VM.\n- Prepare a configuration inside a RPi VM.\n- Flash a RPi VM image to a physical SD card.\n\nExample use cases:\n- Preconfigure Raspberry Pi servers that work from first boot.\n- Create reproducible server configurations using Ansible.\n- Automate the distribution of configurations through a CI pipeline.\n- Test ARM applications in a virtualized environment.\n\nKey features:\n- Pi 3, 4 and **5** support\n- 64 bit (ARMv8) Raspberry PI OS (24.04, Bookworm) included\n  - Image: **[2024-07-04-raspios-bookworm-arm64-lite](https://downloads.raspberrypi.com/raspios_lite_arm64/images/raspios_lite_arm64-2024-07-04/)**\n  - Kernel: **[6.6-y](https://github.com/raspberrypi/linux/tree/rpi-6.6.y)**\n- Internet access\n- No root required\n- Safe, fully reproducible from source\n- Tested and stable\n\n## Usage\n```sh\n$ docker pull ptrsr/pi-ci\n$ docker run --rm -it ptrsr/pi-ci\n\n\u003e usage: docker run [docker args] ptrsr/pi-ci [command] [optional args]\n\u003e \n\u003e PI-CI: the reproducible PI emulator.\n\u003e \n\u003e positional arguments:\n\u003e   command     [init, start, resize, flash, export]\n\u003e \n\u003e optional arguments:\n\u003e   -h, --help  show this help message and exit\n\u003e   -v          show verbose output\n\u003e \n\u003e Refer to https://github.com/ptrsr/pi-ci for the full README on how to use this program.\n```\nEach command has a help message, for example: \n`docker run --rm -it ptrsr/pi-ci start -h`.\n\n## Start machine\nSimply run a `ptrsr/pi-ci` container with the start command:\n```sh\ndocker run --rm -it ptrsr/pi-ci start\n```\nThe emulator will automatically log into `root`.\n\n## Persistence\nTo save the resulting image, use a bind mount to `/dist`:\n```sh\ndocker run --rm -it -v $PWD/dist:/dist ptrsr/pi-ci start\n```\n**NOTE**: this example will create and mount the `dist` folder in the current working directory of the host.\n\nTo restart the image, simply use the same bind mount.\n\n## SSH access\nTo enable ssh access, run the container with port **2222** exposed.\n```sh\ndocker run --rm -p 2222:2222 ptrsr/pi-ci start\n```\n\nThen ssh into the virtual Pi:\n```sh\nssh root@localhost -p 2222\n```\n\n## Resize\nThe 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:\n1. by providing a path to the target device (e.g. `/dev/mmcblk0`). The resulting image will be the same size as the target device.\n\n2. By providing a specific size in gigabytes, megabytes or bytes (e.g. `8G`, `8192M`, `8589934592`).\n\nFor an image to be flashed to a device, the image has to be the less or equal to the device size.\n\n```sh\ndocker run --rm -it -v $PWD/dist:/dist --device=/dev/mmcblk0 ptrsr/pi-ci resize /dev/mmcblk0\n```\n\n**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.\n\n**NOTE**: resizing can potentially be a dangerous operation. Always make backup of the `image.qcow2` file in the `dist` folder before proceeding.\n\n## Flash \nTo flash the prepared image to a storage device (such as an SD card), provide the container with the device and run the flash command:\n```sh\ndocker run --rm -it -v $PWD/dist:/dist --device=/dev/mmcblk0 ptrsr/pi-ci flash /dev/mmcblk0\n```\nOn the first boot of the real RPi, a program will automatically inflate the root partition to fill the rest of the target device.\n\n## Export\nThe 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](https://www.balena.io/etcher). The export command takes two optional arguments; the `--input` and `--output` path;\n```sh\ndocker run --rm -it -v $PWD/dist:/dist ptrsr/pi-ci export --input /dist/image.qcow2 --output /dist/image.img\n```\nThe raw image should pop up alongside the virtual image in the mounted `dist` folder in the example above.\n\nA handy command to flash the file on Linux is;\n```\nsudo dd if=dist/distro.img of=/dev/sdX bs=4M status=progress\n```\nSubstitute `sdX` by the SD card drive (`lsblk`).\n\n## Automation\nUsing 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`.\n\nAnsible can take care of:\n1. Starting the VM\n2. Running tasks in the VM\n3. Stopping the VM\n\nAn example configuration can be found in the `./test` folder of this repository. To start the test process, run:\n```sh\nansible-playbook -i ./test/hosts.yml ./test/main.yml\n```\n\n## Tips\n- Do not forget to set a password for `root` and disable `PermitRootLogin` in the `/etc/ssh/sshd_config` for security.\n- Do not stop or kill the Docker container while the VM is running, this **WILL** corrupt the image!\n- Make sure to regularly back up the `distro.qcow2` image.\n\n## Versions\nPI-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):\n\n| Software  | Version  | \n| ----------| -------- |\n| Ansible   | 2.5.1    |\n| docker-py | 4.4.4    |\n| Docker    | 19.03.6  |\n\n## License\nPI-CI is licensed under [GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fptrsr%2Fpi-ci","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fptrsr%2Fpi-ci","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fptrsr%2Fpi-ci/lists"}