diff options
Diffstat (limited to 'docs/NOTES.org')
| -rw-r--r-- | docs/NOTES.org | 257 |
1 files changed, 204 insertions, 53 deletions
diff --git a/docs/NOTES.org b/docs/NOTES.org index f56e7bd..89c02ad 100644 --- a/docs/NOTES.org +++ b/docs/NOTES.org @@ -1,6 +1,6 @@ -#+TITLE: Claude Code Notes - [Project Name] +#+TITLE: Claude Code Notes - archzfs #+AUTHOR: Craig Jennings & Claude -#+DATE: [Date] +#+DATE: 2026-01-17 * About This File @@ -22,50 +22,146 @@ This file contains project-specific information for this project. * Project-Specific Context -This is where context regarding this project is placed. - -Examples of what goes here: -- Project overview and goals -- People and their relationships to the user -- Contact information for companies and people -- Current state of the project -- Status report -- Links to important documents -- Technical architecture notes -- Key decisions and rationale - -** Welcome to Your First Session! - -This is your first session with Craig on this project. - -**First session checklist:** -1. **Determine project type and git/docs policy:** - - Is this project in a git repository? - - **Is this a code project** (Emacs package, library, software project)? - - **YES (code project):** Add docs/ to .gitignore (private notes, not part of codebase) - - Examples: org-msg, chime.el, wttrin, or any future Emacs packages/libraries - - docs/ contains session notes and should remain private - - **NO (non-code project):** Commit docs/ normally (part of the project documentation) - - Examples: personal projects, business planning, documentation projects - - docs/ is project documentation and should be versioned - - What are the remote repositories (if any)? - -2. **Understand the project:** - - Ask what the project is about - - Ask what the goals of the project are - - Ask any clarifying questions along the way - -3. **Brainstorm how to help:** - - Discuss approaches and strategies - - Identify immediate next steps - -4. **Document learnings:** - - Record what you learned in relevant sections of this document - - Add project-specific context below this section - -5. **Clean up:** - - Remove this "Welcome to Your First Session!" heading and its content - - Update Project-Specific Context section with actual project information +** Overview + +Build system for creating a custom Arch Linux installation ISO with ZFS support. The goal is to have a bootable ISO that can install Arch Linux on ZFS root without needing to manually compile ZFS or deal with kernel version mismatches. + +** Repository + +- Remote: =cjennings@cjennings.net:git/archzfs.git= +- Branch: =main= +- docs/ is committed (not private) + +** Key Components + +- =build.sh= - Main build script (runs as root) + - Downloads ZFS packages from archzfs GitHub releases + - Creates custom archiso profile based on releng + - Adds custom packages (nodejs, npm, jq, zsh, htop, ripgrep, etc.) + - Copies custom installer scripts into ISO + - Builds ISO with mkarchiso + +- =custom/= - Custom scripts included in ISO + - =install-archzfs= - Main installer script + - =install-claude= - Claude Code installer + - =archsetup-zfs= - ZFS-specific Arch setup + - =zfs-setup= - Installs ZFS packages and loads module (generated by build.sh) + +- =scripts/test-vm.sh= - QEMU VM for testing the ISO + +** Current State + +TESTING: install-archzfs script almost complete. + +- ISO builds successfully (4.8G) with linux-lts + zfs-dkms +- ZFS module loads correctly in live environment +- install-archzfs runs through partitioning, pool creation, base install, system config +- Last fix: added freetype2 for grub-mkfont (needs rebuild to test) + +Next: Rebuild ISO, complete install test, boot installed system. + +** Goals + +Create a bootable Arch Linux installation ISO that: +1. Installs Arch on ZFS root with native encryption +2. Uses sane defaults for dataset layout +3. Configures automatic snapshots (sanoid) +4. Sets up replication to TrueNAS for backups +5. Includes Claude Code on live ISO for emergency troubleshooting + +** Design Decisions + +*** Kernel Strategy +- Use =linux-lts= + =zfs-dkms= from archzfs.com repo +- DKMS builds ZFS from source, guaranteeing kernel compatibility +- Slower build time but eliminates version mismatch issues entirely +- LTS kernel provides stability, DKMS provides flexibility + +*** ZFS Pool Configuration +| Setting | Value | Rationale | +|---------+-------+-----------| +| Pool name | =zroot= | Standard convention | +| Encryption | AES-256-GCM, passphrase | Required at every boot | +| Compression | =zstd= (default) | Good balance of speed/ratio | +| Ashift | 12 (4K sectors) | Modern drives | +| Root reservation | 50GB | Prevents pool from filling | + +*** Dataset Layout +| Dataset | Mountpoint | Special Settings | Purpose | +|---------+------------+------------------+---------| +| zroot/ROOT/default | / | reservation=50G | Root filesystem | +| zroot/home | /home | | Home directories (archsetup creates user subdataset) | +| zroot/media | /media | compression=off | Pre-compressed media files | +| zroot/vms | /vms | recordsize=64K | VM disk images (qemu/libvirt + virtualbox) | +| zroot/var/log | /var/log | | System logs | +| zroot/var/cache | /var/cache | | Package cache | +| zroot/var/lib/pacman | /var/lib/pacman | | Package database | +| zroot/var/lib/docker | /var/lib/docker | | Docker storage | +| zroot/tmp | /tmp | auto-snapshot=false | Temp files | +| zroot/var/tmp | /var/tmp | auto-snapshot=false | Temp files | + +*** Snapshot Policy (Sanoid) +Less aggressive since TrueNAS handles long-term backups: + +| Template | Hourly | Daily | Weekly | Monthly | Used For | +|----------+--------+-------+--------+---------+----------| +| production | 6 | 7 | 2 | 1 | root, home, var/log, pacman | +| backup | 0 | 3 | 2 | 1 | media, vms | +| none | 0 | 0 | 0 | 0 | tmp, cache | + +Plus: Pacman hook creates snapshot before every transaction. + +*** TrueNAS Replication +- Primary: =truenas.local= (local network) +- Fallback: =truenas= (tailscale) +- Destination pool: =vault/[TBD]= +- Schedule: Nightly at 2:00 AM +- Datasets: ROOT/default, home, media, vms + +*** Included Packages +- Base system + development tools +- =nodejs=, =npm=, =jq= (for Claude Code) +- =zsh=, =htop=, =ripgrep=, =eza=, =fd=, =fzf= +- =sanoid= (snapshot management) +- =dialog= (installer UI) + +*** Installation UX +- All questions asked upfront, then unattended installation +- WiFi tested before installation begins (if provided) +- User can walk away during install and come back +- Summary + final confirmation before starting + +*** User Account Strategy +- install-archzfs creates root account only (asks for root password) +- No user account created during install +- Just create =zroot/home= dataset (no user-specific subdataset) +- archsetup creates user account + home dataset post-reboot + +*** GRUB HiDPI Support +- Generate 32px DejaVuSansMono font during install +- Set =GRUB_FONT= to use custom font +- Works well on HiDPI and regular displays + +*** WiFi Configuration +- Ask for SSID + password during install (optional) +- Test connection before installation starts +- Copy connection profile to installed system +- Auto-connects after reboot + +*** Post-Install Workflow +1. install-archzfs: Minimal ZFS system + root account +2. Reboot, login as root +3. Run archsetup manually for full workstation setup + +*** Testing/Debugging (VM) +- SSH access on live ISO: sshd enabled, known root password +- Serial console: =-serial mon:stdio= in QEMU for terminal copy/paste +- Port forwarding: 2222→22 (already configured) +- Allows easy copy/paste of error messages during testing + +** Open Questions + +- [ ] TrueNAS destination dataset path (vault/???) * AVAILABLE WORKFLOWS @@ -233,15 +329,70 @@ Each entry should use this format: ** Session Entries -*** [First session date] +*** 2026-01-17 Sat @ 17:10 -0600 -*Time:* Initial setup -*Status:* COMPLETE - Template created +*Status:* IN PROGRESS *What We Completed:* -- Project initialized with Claude Code templates -- Ready for first work session +- Fixed ZFS kernel module mismatch by switching to linux-lts + zfs-dkms +- Fixed bootloader to use linux-lts kernel (was defaulting to regular linux) +- Fixed broadcom-wl dependency (switched to broadcom-wl-dkms) +- Updated mkinitcpio preset for linux-lts with archiso config +- Fixed install-archzfs bugs: + - =[[ ]] && error= pattern causing early exit with =set -e= (changed to if/then) + - 50G reservation on 50G disk (now dynamic: 20% of pool, capped 5-20G) + - sanoid not in official repos (moved to archsetup) + - grub-mkfont needs freetype2 package (added to pacstrap) +- Removed sanoid/syncoid from install-archzfs (archsetup will handle) +- Created inbox item for archsetup with full sanoid/syncoid config +- ISO now 4.8G (was 5.4G) - only linux-lts kernel + +*Key Technical Insights:* +- =broadcom-wl= depends on =linux= kernel specifically - use =broadcom-wl-dkms= instead +- archiso releng profile has linux.preset in airootfs that needs renaming to linux-lts.preset +- With =set -e=, =[[ test ]] && command= returns exit code 1 if test is false, causing script exit +- =grub-mkfont= requires =freetype2= package (not installed by default with grub) + +*Files Modified:* +- [[file:../build.sh][build.sh]] - major updates for linux-lts, bootloader configs, mkinitcpio preset +- [[file:../custom/install-archzfs][custom/install-archzfs]] - multiple bug fixes, removed sanoid/syncoid +- [[file:~/code/archsetup/inbox/zfs-sanoid-detection.txt][archsetup inbox]] - sanoid/syncoid config for archsetup to implement + +*Current State:* +- ISO builds successfully with linux-lts + zfs-dkms +- ZFS module loads correctly in live environment +- install-archzfs runs through most steps +- Last error: grub-mkfont missing freetype2 (now fixed, needs rebuild/test) *Next Steps:* -- Begin first actual work session -- Follow "Welcome to Your First Session!" checklist above +- Rebuild ISO with freetype2 fix +- Complete full install-archzfs test in VM +- Test booting the installed system +- Git commit all changes + +*** 2026-01-17 Sat @ 13:16 -0600 + +*Status:* COMPLETE (continued above) + +*What We Completed:* +- Initialized git repository +- Created .gitignore (excludes work/, out/, profile/, zfs-packages/) +- Initial commit with all build scripts +- Added docs/ to git (decided to track publicly) +- Built fresh ISO (archzfs-claude-2026.01.17-x86_64.iso, 4.9G) +- Tested ISO in QEMU VM +- Documented project goals and design decisions in NOTES.org + +*Key Decisions Made:* +- Use linux-lts + zfs-dkms from archzfs.com (DKMS ensures kernel compatibility) +- Less aggressive snapshot policy (TrueNAS handles long-term backups) +- All install questions upfront, then unattended installation +- Root account only (archsetup creates user post-reboot) +- 32px GRUB font for HiDPI displays +- WiFi config tested before install starts + +*Files Modified:* +- [[file:../.gitignore][.gitignore]] - created +- [[file:../build.sh][build.sh]] - major rewrite +- [[file:../custom/install-archzfs][custom/install-archzfs]] - complete rewrite +- [[file:../scripts/test-vm.sh][scripts/test-vm.sh]] - added serial console |