{"id":20476440,"url":"https://github.com/tagae/gentoo-on-raspberry-pi","last_synced_at":"2026-05-08T10:34:18.744Z","repository":{"id":42699797,"uuid":"232663680","full_name":"tagae/gentoo-on-raspberry-pi","owner":"tagae","description":"Gentoo image generator for the Raspberry Pi platform","archived":false,"fork":false,"pushed_at":"2023-02-06T11:13:09.000Z","size":163,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-30T21:08:12.818Z","etag":null,"topics":["gentoo","linux","raspberry-pi"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tagae.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":"2020-01-08T21:30:02.000Z","updated_at":"2021-10-28T07:47:14.000Z","dependencies_parsed_at":"2024-11-15T16:30:53.372Z","dependency_job_id":null,"html_url":"https://github.com/tagae/gentoo-on-raspberry-pi","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tagae/gentoo-on-raspberry-pi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tagae%2Fgentoo-on-raspberry-pi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tagae%2Fgentoo-on-raspberry-pi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tagae%2Fgentoo-on-raspberry-pi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tagae%2Fgentoo-on-raspberry-pi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tagae","download_url":"https://codeload.github.com/tagae/gentoo-on-raspberry-pi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tagae%2Fgentoo-on-raspberry-pi/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262850262,"owners_count":23374355,"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":["gentoo","linux","raspberry-pi"],"created_at":"2024-11-15T15:20:40.920Z","updated_at":"2026-05-08T10:34:13.695Z","avatar_url":"https://github.com/tagae.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"Gentoo Linux on Raspberry Pi\n============================\n\n![test](https://github.com/tagae/gentoo-on-raspberry-pi/workflows/test/badge.svg)\n\nThis repository contains a number of tools to install Gentoo Linux on the\n[Raspberry Pi 4 Model B] platform.\n\nThese tools automate parts of the [Gentoo Handbook] to obtain in the end a\nminimal installation based on [systemd] that is able to boot and accept SSH\nconnections. Provisioning and further system configuration are out of scope for\nthis project.\n\nThe built system is meant to run as a headless server. The installation has\nbeen tested only by accessing the Raspberry Pi through a serial console\nconnection (using a USB to TTL serial cable), and through SSH\nconnections. Visual functionality (e.g., HDMI support, 3D graphics\nacceleration) has not been tested.\n\n[Raspberry Pi 4 Model B]: https://www.raspberrypi.org/products/raspberry-pi-4-model-b/\n[Gentoo Handbook]: https://wiki.gentoo.org/wiki/Handbook:Main_Page\n[systemd]: https://systemd.io/\n\n\nBuild environment\n-----------------\n\nThis projects builds and installs Gentoo using Gentoo as build environment.\n\nIf your host runs Gentoo, you can use it as build environment by provisioning\nyour system with the needed tools through the `provision` command:\n\n    sudo ./provision\n\nIf your host system is not Gentoo (or even if it is but you prefer to keep your\nsystem untouched), you can run all commands in a `chroot`-ed Gentoo environment\nthrough the `builder` command.  So the previous command becomes instead:\n\n    sudo ./builder ./provision\n\nThe `builder` command creates a `builder.img` image containing a Gentoo build\nenvironment. You can remove the image once no longer needed.\n\nAll instructions in this guide assume the use of the `builder` environment,\nbecause it is the more general procedure that applies irrespective of the host\nLinux distribution. Keep in mind however that if you use your Gentoo system as\nbuild environment, you can simplify all commands shown in this guide by\nomitting the `builder` wrapper.\n\nIf your host architecture is not aarch64 (64-bit ARM), the build system will\ntake care of cross-compiling the needed resources.\n\n### Build Parameters\n\nThe parameters needed for installation are the following:\n\n    export MACHINE=gentoo  # hostname of the installed system\n    export PROFILE=rpi4    # Raspberry Pi 4\n\nIf installing directly to a Micro SD card, you also need\n\n    export DEVICE=/dev/mmcblk0 # target block device for installation\n\nThese environment variables are defined only for convenience in this guide;\nyou can inline their values if you prefer.\n\n### Kernel Requirements\n\nYour build system must run a kernel that supports Master Boot Record partitions\n(`MSDOS_PARTITION`), FAT file systems (`FAT_FS`) and BTRFS file systems\n(`BTRFS_FS`). Most Linux distributions meet these requirements out of the box.\n\n\nInstallation\n------------\n\nThe `install` command installs a Gentoo system onto any given block device,\nsuch that it can be booted by the Raspberry Pi. Concretely, the install process\nwill:\n\n* Partition the device, creating\n  * a boot partition containing a FAT file system, and\n  * a base partition containing a BTRFS file system.\n\n* For the boot file system, the `install` command will\n  * fetch, compile and install the Linux kernel and modules, and\n  * fetch and install the Raspberry Pi firmware.\n\n* For the base file system, the `install` command will bootstrap a Gentoo\n  system, as described in the \"Bootstrapping\" section.\n\nThe `install` command can write directly to the microSD card that will be used\nto run the Raspberry Pi. Simply issue:\n\n    sudo -E ./builder ./install $MACHINE $PROFILE $DEVICE\n\nOnce the installation is complete, you can insert the card into your Raspberry\nPi, connect the Pi via an Ethernet cable to your network, and you will be able\nto SSH into it with\n\n    ssh root@$MACHINE.local\n\nThis assumes that the system from which you connect is able to resolve\nMulticast DNS (`.local`) domains. Otherwise you need to find the IP address of\nthe Pi host in your network.\n\nBy default the installed system will be configured to allow SSH connections\nfrom your key at `~/.ssh/id_rsa`, if available.  If unavailable (in particular,\nif you omit the `-E` option from `sudo`), a fresh key will be generated at\n`install.d/ssh/$MACHINE` and used instead.\n\n\nPackaging\n---------\n\nThe `package` command creates an image containing a Gentoo installation that\ncan boot on the Raspberry Pi, as described in the \"Installation\" section.\n\nTo create the image, issue\n\n    sudo -E ./builder ./package $MACHINE.$PROFILE.img\n\nThe image will have `$MACHINE` as default hostname, and will allow SSH\nconnections for your personal key at `$HOME/.ssh/id_rsa`.\n\nYou can omit the `-E` option from `sudo` if you prefer to use the key at\n`install.d/ssh/$MACHINE`. The key will be automatically generated unless it\nalready exists.\n\nGiven that you can install Gentoo directly to a microSD card (see\n\"Installation\" section), the main reason to build an image is to boot it\nthrough an emulator (see \"Booting\" section) for the sake of exploration and\ntesting.\n\n\nBooting\n-------\n\nThe `boot` command runs a QEMU virtual machine that has an image of the system\n(see \"Packaging\" section) as main hard disk:\n\n    sudo -E ./builder ./boot $MACHINE.$PROFILE.img\n\nThis makes it possible to test the system locally, before it is written to a\nmicroSD card and run on the Raspberry Pi.\n\nTo connect to the virtual machine, issue\n\n    ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 2222 root@localhost\n\nThe `-o` options avoid polluting your `~/.ssh/known_hosts` with the fingerprint\nof a machine that you are only testing.\n\nCurrently QEMU cannot emulate the Raspberry Pi 4 hardware, and thus the image\nis run in a generic 64-bit ARM machine that has none of the hardware specific\nto the Raspberry Pi. Still, this is enough to test most of the relevant parts\nof the system before it is actually deployed on the Pi.\n\n\nBootstrapping\n-------------\n\nThe `bootstrap` command will deploy a bare-bones (stage3) Gentoo system onto\nany given sub-directory that is part of a BTRFS file system.\n\nThe `bootstrap` command is akin to tools like [debootstrap] for Debian, and\n[arch-bootstrap] for Arch Linux.\n\nBootstrapping is used both to create build environments (see \"Build\nenvironment\" section), and to bootstrap the system that will run on the\nRaspberry Pi.\n\nYou can of course bootstrap Gentoo for other purposes, and use it as `chroot`\njail or `systemd-nspawn` container.\n\n[debootstrap]: https://wiki.debian.org/Debootstrap\n[arch-bootstrap]: https://github.com/tokland/arch-bootstrap\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftagae%2Fgentoo-on-raspberry-pi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftagae%2Fgentoo-on-raspberry-pi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftagae%2Fgentoo-on-raspberry-pi/lists"}