| btrfs-install.md | ||
| README.md | ||
BTRFS Installation Guide for lainOS Protocol 7 (Community Edition)
⚠️ Official Warning: The lainOS Layer 02 release notes explicitly state: "DO NOT USE BTRFS". This guide documents a successful community workaround to install Protocol 7 on a BTRFS root partition despite this warning.
📖 Overview
This repository contains a complete, step‑by‑step installation log and debugging walkthrough for installing lainOS Layer 02 / Protocol 7 on a UEFI system with an NVMe SSD using BTRFS.
The guide covers the entire journey – from the initial GRUB failure (corrupt kernel) right through to a successful first boot, including every fix applied along the way.
🖥️ System & Environment
- Date: 2026-06-24
- System: UEFI (not legacy BIOS)
- Storage: NVMe SSD
- Filesystem: BTRFS (root) + ESP (EFI System Partition)
- ISO:
lainOS-layer-02-2026.06.23.iso(Protocol 7 alpha)
📑 Table of Contents (Guide Phases)
The full guide covers these exact steps:
| Phase | Description |
|---|---|
| Phase 0 | Booting the Live ISO in UEFI mode |
| Phase 1 | Switching to root |
| Phase 2 | Setting system time (for keyring) |
| Phase 3 | Keyring initialization (Round 1 – Live ISO) |
| Phase 4 | Launching Calamares installer |
| Phase 5 | Manual BTRFS partitioning in Calamares |
| Phase 6 | Mounting the installed BTRFS subvolume (@) |
| Phase 7 | Chrooting into the installed system |
| Phase 8 | Keyring initialization (Round 2 – Chroot) |
| Phase 9 | Fixing Dracut and GRUB configuration |
| Phase 10 | Reinstalling the kernel |
| Phase 11 | Rebuilding Initramfs and GRUB |
| Phase 12 | Final verification (checksums) |
| Phase 13 | Exiting chroot and rebooting |
| Phase 14 | Post‑boot expectations & troubleshooting |
🔧 Key Fixes Summarized
Here are the critical solutions implemented in this guide:
| Problem | Solution |
|---|---|
Kernel corrupt (premature end of file) |
Reinstall kernel with pacman -S linux |
| GRUB installed for BIOS on UEFI system | Install GRUB with --target=x86_64-efi |
| Initramfs missing NVMe drivers | Force‑load nvme and nvme_core in dracut |
| Dracut trying to build a UEFI executable | Add --no-uefi flag to dracut config |
| Keyring signature errors | Refresh keyring twice (Live ISO + Chroot) |
| BTRFS subvolume not mounting correctly | Mount with -o subvol=@ |
📂 Repository Contents
btrfs-install.md– The complete, detailed installation guide.README.md– This file (overview, summary, and quick links).
🚀 How to Use This Guide
- Read the full guide carefully.
- Ensure your hardware matches the prerequisites (UEFI + NVMe).
- Back up your data before proceeding.
- Follow the steps sequentially – the phases are designed to replicate the exact debug session.
⚠️ Disclaimer
This document is community‑contributed and not officially supported by the LainOS development team.
- The authors and maintainers are not responsible for any data loss or hardware damage.
- The official stance remains: "DO NOT USE BTRFS" – this is a workaround, not a recommendation.
🤝 Contributing
Found an issue, have a suggestion, or want to improve the guide?
- Fork this repository.
- Make your changes.
- Open a Pull Request, or submit an Issue via the Forgejo interface.
📝 Credits
Compiled from a successful real installation session on 2026-06-24. Special thanks to the LainOS developers for the Protocol 7 alpha release.
Made with ❤️ by the community.