{"id":21508851,"url":"https://github.com/oddlama/gentoo-install","last_synced_at":"2025-05-15T11:07:11.976Z","repository":{"id":37755009,"uuid":"231108150","full_name":"oddlama/gentoo-install","owner":"oddlama","description":"A gentoo installer with a TUI interface that supports systemd and OpenRC, EFI and BIOS, as well as variable disk layouts using ext4, zfs, btrfs, luks and mdraid.","archived":false,"fork":false,"pushed_at":"2025-03-02T17:46:38.000Z","size":705,"stargazers_count":591,"open_issues_count":13,"forks_count":84,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-04-14T18:14:22.090Z","etag":null,"topics":["gentoo","installer","linux","stage3-tarball","system"],"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/oddlama.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":"2019-12-31T15:09:52.000Z","updated_at":"2025-04-12T20:01:03.000Z","dependencies_parsed_at":"2023-10-14T16:15:29.801Z","dependency_job_id":"9698c6e1-fc4d-4eee-9015-a2b2c838ddad","html_url":"https://github.com/oddlama/gentoo-install","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oddlama%2Fgentoo-install","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oddlama%2Fgentoo-install/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oddlama%2Fgentoo-install/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oddlama%2Fgentoo-install/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oddlama","download_url":"https://codeload.github.com/oddlama/gentoo-install/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248933340,"owners_count":21185460,"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","installer","linux","stage3-tarball","system"],"created_at":"2024-11-23T21:13:06.614Z","updated_at":"2025-04-14T18:14:26.495Z","avatar_url":"https://github.com/oddlama.png","language":"Shell","funding_links":[],"categories":["\u003ca name=\"utility\"\u003e\u003c/a\u003eUtilities","Shell"],"sub_categories":[],"readme":"## About gentoo-install\n\nThis project aspires to be your favourite way to install gentoo.\nIt aims to provide a smooth installation experience, both for beginners and experts.\nYou may configure it by using a menuconfig-inspired interface or simply via a config file.\n\nIt supports the most common disk layouts, different file systems like ext4, ZFS and btrfs as well\nas additional layers such as LUKS or mdraid. It also supports both EFI (recommended) and BIOS boot,\nand can be used with systemd or OpenRC as the init system. SSH can also be configured to allow using an automation framework\nlike [Ansible](https://github.com/ansible/ansible) or [Fora](https://github.com/oddlama/fora) to automate beyond system installation.\n\n[Usage](#usage) |\n[Overview](#overview) |\n[Updating the Kernel](#updating-the-kernel) |\n[Recommendations](#recommendations) |\n[FAQ](#troubleshooting-and-faq)\n\n![](contrib/screenshot_configure.png)\n\nThis installer might appeal to you if\n\n- you want to try gentoo without initially investing a lot of time, or fully committing to it yet.\n- you already are a gentoo expert but want an automatic and repeatable best-practices installation.\n\nOf course, we do encourage everyone to install gentoo manually. You will learn a lot if you\nhaven't done so already.\n\n## Usage\n\nFirst, boot into a live environment of your choice. I recommend using an [Arch Linux](https://www.archlinux.org/download/) live ISO,\nas the installer will then be able to automatically download required programs or setup ZFS support on the fly.\nAfterwards, proceed with the following steps:\n\n```bash\npacman -Sy git  # (Archlinux) Install git in live environment, then clone:\ngit clone \"https://github.com/oddlama/gentoo-install\"\ncd gentoo-install\n./configure     # configure to your liking, save as gentoo.conf\n./install       # begin installation\n```\n\nEvery option is explained in detail in `gentoo.conf.example` and in the help menus of the TUI configurator.\nWhen installing, you will be asked to review the partitioning before anything critical is done.\n\nThe installer should be able to run without any user supervision after partitioning, but depending\non the current state of the gentoo repository, you might need to intervene in case a package fails\nto emerge. The critical commands will ask you what to do in case of a failure. If you encounter a\nproblem you cannot solve, you might want to consider getting in contact with some experienced people\non [IRC](https://www.gentoo.org/get-involved/irc-channels/) or [Discord](https://discord.com/invite/gentoolinux).\n\nIf you need to enter an installed system in a chroot to fix something (e.g. after rebooting your live system),\nyou can always clone the installer, mount your main drive under `/mnt` and use `./install --chroot /mnt` to\njust chroot into your system.\n\n## Overview\n\nThe installer performs the following main steps (in roughly this order),\nwith some parts depending on the chosen configuration:\n\n1. Partition disks (highly dependent on configuration)\n2. Download and extract stage3 tarball (with cryptographic verification)\n   \\[Continues in chroot from here\\]\n3. Setup portage (initial rsync/git sync, run mirrorselect, create zz-autounmask files)\n4. Base system configuration (hostname, timezone, keymap, locales)\n5. Install required packages (git, kernel, ...)\n6. Make system bootable (generate fstab, build initramfs, create efibootmgr/syslinux boot entry)\n7. Ensure minimal working system (automatic wired networking, install eix, set root password)\n   - (Optional) Install sshd with secure config (no password logins)\n   - (Optional) Install additional packages provided in config\n\nThe goal of the installer is just to setup a minimal gentoo system following best-practices.\nAnything beyond that is considered out-of-scope (with the exception of configuring sshd).\nHere are some things that you might want to consider doing after the system installation is finished:\n\n1. Read the news with `eselect news read`.\n2. Compile a custom kernel and remove `gentoo-kernel-bin`\n3. Adjust `/etc/portage/make.conf`\n   - Set `CFLAGS` to `\u003cmarch_native_flags\u003e -O2 -pipe` for native builds by using the `resolve-march-native` tool\n   - Set `CPU_FLAGS_X86` using the `cpuid2cpuflags` tool\n4. Use a safe umask like `umask 077`\n\n### (Optional) sshd\n\nThe script can provide a fully configured ssh daemon with reasonably good security settings.\nIt will by default only allow ed25519 keys, restrict key exchange\nalgorithms to a reasonable subset, disable any password based authentication,\nand only allow root to login.\n\nYou can provide keys that will be written to root's `.ssh/authorized_keys` file. This will allow\nyou to directly continue your setup with your favourite infrastructure management software.\n\n### (Optional) Additional packages\n\nYou can add any amount of additional packages to be installed on the target system.\nThese will simply be passed to a final `emerge` call before the script is done,\nwhere autounmasking will also be done automatically. It is recommended to keep\nthis to a minimum, because of the quite \"interactive\" nature of gentoo package management ;)\n\n## Updating the kernel\n\nBy default, the installed system uses gentoo's binary kernel distribution (`sys-kernel/gentoo-kernel-bin`)\ntogether with an initramfs generated by dracut. This ensures that the installed system works on all common hardware configurations.\nFeel free to replace this with a custom-built kernel (and possibly remove/adjust the initramfs) when the system is booted.\n\nThe installer will provide the convenience script `generate_initramfs.sh` in `/boot/efi/`\nor `/boot/bios` which may be used to generate a new initramfs for the given kernel version.\nDepending on whether your system uses EFI or BIOS boot, you will also find your kernel and initramfs in different locations:\n\n```bash\n# EFI\nkernel=\"/boot/efi/vmlinuz.efi\"\ninitrd=\"/boot/efi/initramfs.img\"\n# BIOS\nkernel=\"/boot/bios/vmlinuz-current\"\ninitrd=\"/boot/bios/initramfs.img\"\n```\n\nIn both cases, the update procedure is as follows:\n\n1. Emerge new kernel\n2. `eselect kernel set \u003ckver\u003e`\n3. Backup old kernel and initramfs (`mv \"$kernel\"{,.bak}`, `mv \"$initrd\"{,.bak}`)\n4. Generate new initramfs for this kernel `generate_initramfs.sh \u003ckver\u003e \"$initrd\"`\n5. Copy new kernel `cp /boot/kernel-\u003ckver\u003e \"$kernel\"` (for systemd) or `cp /boot/vmlinuz-\u003ckver\u003e \"$kernel\"` (for openrc)\n\n## Recommendations\n\nThis project started out as a way of documenting a best-practices installation for myself.\nAs the project grew larger, I've added more configuration options to suit legacy needs.\nBelow I've outlined several decisions I've made for this project, or decisions you\nhave during configuration. If you intend on setting up a modern system, you might want\nto check them out. Please keep in mind that those are all based on my personal opinions and\nexperience. Your mileage may vary.\n\n#### EFI vs BIOS\n\nUse EFI. BIOS is old and deprecated for a long time now.\nOnly certain VPS hosters may require you to use BIOS still (time to write to them about that!)\n\n#### EFIstub booting\n\nDon't install a bootloader when this script is done, except you absolutely need one.\nThe kernel can directly be booted by EFI without need for a bootloader.\nBy default, this script will use efibootmgr to add a bootentry directly to your \"mainboard's bootselect\" (typically F12).\nNowadays, there's just no reason to use GRUB, syslinux, or similar bootloaders by default.\nThey only add additional time to your boot, and even dualbooting Windows works just fine without one.\nOnly if you require frequent editing of kernel parameters, or want kernel autodiscovery from attached media\nyou might want to consider using one of these. For the average (advanced) user this isn't necessary.\n\nIf you want to add more boot options or want to learn about efibootmgr, refer to [this page on the gentoo wiki](https://wiki.gentoo.org/wiki/Efibootmgr).\n\n#### Modern file systems\n\nI recommend using a modern file system like ZFS, both on desktops and servers.\nIt provides transparent block-level compression, instant snapshots and full-disk encryption.\nGenerally, encrypting your root fs doesn't cost you anything and protects your data in case you lose your device.\n\n#### Systemd vs OpenRC\n\nI will not entertain the religious eternal debate here. Both are fine init systems, and\nI've been using both *a lot*. If you cannot decide, here are some objective facts:\n\n- OpenRC is a service manager. Setting up all the other services is a lot of work, but you will learn a lot.\n- Systemd is an OS-level software suite. It brings an insane amount of features with a steep learning curve.\n\nHere's a non-exhaustive list of things you will ~do manually~ learn when using OpenRC,\nthat are already provided for in systemd: udev, dhcp, acpi events (power/sleep button),\ncron jobs, reliable syslog, logrotate, process sandboxing, persistent backlight setting, persistent audio mute-status, user-owned login sessions, ...\n\nMake of this what you will, both have their own quirks. Choose your poison.\n\n#### Miscellaneous\n\n- Use the newer iwd for WiFi instead of wpa_supplicant\n- (If systemd) Use timers instead of cron jobs\n\n## Troubleshooting and FAQ\n\nAfter the initial sanity check, the script should be able to finish unattendedly.\nBut given the unpredictability of future gentoo versions, you might still run into issues\nonce in a while.\n\nThe script checks every command for success, so if anything fails during installation,\nyou will be given a proper message of what went wrong. Inside the chroot,\nmost commands will be executed in a checked loop, and allow you to interactively\nfix problems with a shell, to retry, or to skip the command. You can report\nissues specific to this script on the issue tracker. To seek help\nregarding gentoo in general, visit the official [IRC](https://www.gentoo.org/get-involved/irc-channels/)\nor [Discord](https://discord.com/invite/gentoolinux).\n\nIf you experience any issues after rebooting and need to fix something inside the chroot,\nyou can use the installer to chroot into an existing system. Run `./install --help` for more infos.\n\n#### Q: ZFS cannot be installed in the chroot due to an unsupported kernel version\n\n**A:** The newest stable ZFS module may require a kernel version that is newer than what is provided on gentoo stable.\nIf you encounter this problem, you might be able to fix the problem by switching to testing by dropping to a shell temporarily:\n\n```\n# Press S\u003cEnter\u003e when asked about what to do next.\n# This opens an emergency shell in the chroot.\necho 'ACCEPT_KEYWORDS=\"~amd64\"' \u003e\u003e /etc/portage/make.conf # Enable testing for your architecture.\nemerge -v gentoo-kernel-bin                               # Update kernel to newest version\nexit # Ctrl-D\n# Now select 'retry' when asked about what to do next.\n```\n\n#### Q: I get errors after partitioning about blkid not being able to find a UUID\n\n**A:** Be sure that all devices are unmounted and not in use before starting the script.\nUse `wipefs -a \u003cDEVICE\u003e` on your partitions or fully wipe the disk before use.\nThe new partitions probably align with previously existing partitions that had\nfilesystems on them. Some filesystems signatures like those of ZFS can coexist with\nother signatures and may cause blkid to find ambiguous information.\n\n## References\n\n* [Gentoo AMD64 Handbook](https://wiki.gentoo.org/wiki/Handbook:AMD64)\n* [Sakaki's EFI Install Guide](https://wiki.gentoo.org/wiki/Sakaki%27s_EFI_Install_Guide)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foddlama%2Fgentoo-install","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foddlama%2Fgentoo-install","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foddlama%2Fgentoo-install/lists"}