From 95aec991f083d0b1049ee65c8875b29ed05deada Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Mon, 6 Apr 2026 12:25:39 +0200 Subject: [PATCH] docs: add REQUIREMENTS.md with pre-install checklist (Sam & Claude) Comprehensive pre-install requirements guide: Hardware requirements: - RAM: 8 GB minimum (ZFS + jails), 16 GB recommended, 32 GB for LLM - Disk: 64 GB USB minimum, 128 GB recommended, 256 GB for LLM - CPU: 2 cores minimum, 4+ recommended Network requirements: - 10+ Mbps internet for fetch phase - DNS must resolve pkg.FreeBSD.org - Firewall rules documented Tailscale setup: - Inline instructions for auth key generation - Without-Tailscale warnings - Security implications explained Build host requirements: - FreeBSD 15.0+ (Linux not supported) - 150 GB free disk space - curl + doas/sudo packages Time estimates: - Fetch: 15-20 min (network dependent) - Build: 10-15 min (CPU dependent) - Write: 5-10 min (USB 3.0) - First boot: 10-15 min - Total: 40-60 min USB requirements: - USB 3.0 recommended (5 min write) - USB 2.0 works but slower (10-15 min write) - Quality brands recommended Additional sections: - Pre-install checklist - Target-specific requirements (baremetal vs vps) - Offline/air-gapped build instructions - Troubleshooting common issues - Quick reference for minimal/recommended/LLM setups --- REQUIREMENTS.md | 355 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 355 insertions(+) create mode 100644 REQUIREMENTS.md diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md new file mode 100644 index 00000000..3bab3c3f --- /dev/null +++ b/REQUIREMENTS.md @@ -0,0 +1,355 @@ +# Clawdie-ISO Requirements + +Pre-install requirements checklist for building and deploying Clawdie-ISO. + +--- + +## Quick Start Checklist + +Before building, ensure you have: + +- [ ] FreeBSD 15.0+ build host +- [ ] 128 GB USB key (64 GB minimum) +- [ ] Internet connection (10+ Mbps) +- [ ] Tailscale auth key (recommended) +- [ ] 150 GB free disk space +- [ ] 40-60 minutes time + +--- + +## Hardware Requirements + +### Minimum Specifications + +| Component | Minimum | Recommended | Local LLM | Notes | +|-----------|---------|-------------|-----------|-------| +| **CPU** | 2 cores | 4+ cores | 4+ cores | More cores = faster builds | +| **RAM** | 8 GB | 16 GB | 32 GB+ | ZFS ARC + jails need RAM | +| **Disk** | 64 GB USB | 128 GB USB | 256 GB USB | USB key or internal | +| **Network** | 1 Gbps | 1 Gbps | 1 Gbps | Required for fetch phase | + +**Why 8 GB minimum?** +- ZFS ARC cache is RAM-hungry +- 4 jails running (worker, db, git, cms) +- Desktop environment (Lumina) +- Base system overhead + +**Why 32 GB for local LLM?** +- Ollama loads models into RAM +- 7B model = ~8 GB RAM +- 13B model = ~16 GB RAM +- System still needs RAM for jails + ZFS + +### USB Key Requirements + +| USB Size | Image Size | Free Space | Use Case | +|---------|-----------|-----------|----------| +| 64 GB | 50 GB | ~14 GB | Minimum (tight) | +| 128 GB | 100 GB | ~28 GB | **Recommended** | +| 256 GB | 200 GB | ~56 GB | Future-proof, | + +**Important:** +- Do NOT use USB < 64 GB (build will fail) +- USB 3.0 recommended (faster writes) +- Quality matters (avoid cheap USB keys) + +### USB Speed Comparison + +| USB Type | Speed | Write Time | Notes | +|----------|-------|------------|-------| +| USB 3.0 | 5 Gbps | ~5 min | **Recommended** | +| USB 2.0 | 480 Mbps | ~10-15 min | Works but slower | +| USB 3.1/3.2 | 10-20 Gbps | ~3-5 min | Overkill but fast | + +### Target-Specific Requirements + +| Target | RAM | Disk | Use Case | +|--------|-----|------|----------| +| `baremetal` | 8+ GB | 128 GB USB | Desktop + jails | +| `vps` | 4+ GB | 20 GB VPS | Headless, minimal | +| `baremetal` + LLM | 32+ GB | 256 GB USB | Local AI models | + +--- + +## Network Requirements + +### Internet Connection + +- **Required for:** Fetch phase (downloads ~8 GB) +- **Speed:** 10+ Mbps recommended +- **Duration:** 15-20 minutes +- **Optional for:** Air-gapped builds (see Offline Build section) + +### Firewall Rules + +**During Build:** +- **Outbound:** Allow HTTPS (443), HTTP (80) for package downloads +- **Inbound:** None required + +**Post-Install:** +- **With Tailscale:** No inbound ports needed +- **Without Tailscale:** SSH (22) exposed publicly + +### DNS + +- Working DNS resolution required +- `pkg.FreeBSD.org` must be resolvable +- `codeberg.org` must be resolvable (for Clawdie-AI tarball) + +--- + +## Tailscale Setup (Recommended) + +### Why Tailscale? + +- Secure remote access without port forwarding +- Works behind NAT, CGNAT, dynamic IPs +- Encrypted WireGuard tunnels +- Free for up to 100 devices +- Multi-device access (phone, laptop, tablet) + +### Setup Steps + +1. **Sign up** at https://tailscale.com (free, no credit card) + +2. **Navigate to key generation:** + - Admin console → Settings → Keys + - Or direct: https://login.tailscale.com/admin/settings/keys + +3. **Generate auth key:** + - Click "Generate auth key" + - **Check "Reusable"** (for multiple deployments) + - Add description: "Clawdie-ISO builds" + - Set expiration: 90 days (or custom) + - Tags: Optional (e.g., "tag:clawdie") + - Click "Generate key" + +4. **Copy key** (starts with `tskey-auth-...`) + - Store securely (it's like a password) + - You won't be able to see it again + +5. **Export before building:** + ```bash + export TAILSCALE_AUTHKEY="tskey-auth-..." + ``` + +6. **Verify:** + ```bash + echo $TAILSCALE_AUTHKEY + # Should show: tskey-auth-... + ``` + +### Without Tailscale + +- Build continues with warning +- SSH exposed on public port 22 +- You are responsible for: + - Strong passwords + - SSH hardening (key-only auth, fail2ban) + - Firewall rules + - Regular security updates + +**Not recommended for production deployments.** + +--- + +## Build Host Requirements + +### FreeBSD Build Host + +- **OS:** FreeBSD 15.0+ (14.2 minimum) +- **Packages:** + ```bash + pkg install curl # for downloads + pkg install doas # or sudo (for steps 5-7) + ``` +- **Disk space:** 150 GB free in `tmp/` directory +- **Permissions:** Root or doas/sudo access for steps 5-7 + +### Linux Build Host + +- **NOT SUPPORTED** - build.sh requires FreeBSD tools: + - `mdconfig` (memory disk configuration) + - `gpart` (partitioning) + - `newfs` (UFS filesystem) + - `mount_ufs` (UFS mount) + +**Workaround:** Use FreeBSD VM for building: +```bash +# Example: Use bhyve or VirtualBox +# Install FreeBSD 15.0 in VM +# Install curl, doas +# Clone clawdie-iso repo +# Build inside VM +``` + +--- + +## Time Requirements + +### Build Phases + +| Phase | Duration | Depends On | Notes | +|-------|----------|------------|-------| +| Fetch packages | 15-20 min | Network speed | ~8 GB download | +| Build image | 10-15 min | CPU + disk | Image creation | +| Write to USB | 5-10 min | USB speed | USB 3.0: 5 min, USB 2.0: 10-15 min | +| First boot + wizard | 10-15 min | Interactive | User input needed | +| **Total** | **40-60 min** | | | + +### Breakdown by Target + +| Target | Fetch | Build | Write | First Boot | Total | +|--------|-------|-------|-------|------------|-------| +| `baremetal` | 15-20 min | 10-15 min | 5-10 min | 15-20 min | 45-65 min | +| `vps` | 10-15 min | 5-10 min | N/A | 5-10 min | 20-35 min | + +**Note:** VPS builds are faster (no desktop packages, fewer GPU drivers). + +--- + +## Pre-Install Checklist + +### Required + +- [ ] FreeBSD 15.0+ host available +- [ ] 128 GB USB key (or 64 GB minimum) +- [ ] Internet connection (10+ Mbps) +- [ ] `curl` installed (`pkg install curl`) +- [ ] Root/doas access (for steps 5-7) +- [ ] 150 GB free disk space in `tmp/` +- [ ] 40-60 minutes uninterrupted time + +### Recommended + +- [ ] Tailscale account + auth key generated +- [ ] USB 3.0 key (faster writes) +- [ ] Quality USB brand (SanDisk, Samsung, Kingston) +- [ ] Uninterruptible power supply (UPS) + +### For VPS Builds + +- [ ] Assistant name decided (e.g., "Clawdie", "Natasha") +- [ ] Domain decided (e.g., "clawdie.example.com") +- [ ] Timezone known (e.g., "Europe/Ljubljana") + +### For Local LLM + +- [ ] 32+ GB RAM confirmed +- [ ] 256 GB USB key +- [ ] GPU optional (for future acceleration) + +--- + +## Offline/Air-Gapped Builds + +### Scenario + +- Building in isolated network +- No internet access +- Security policy prevents cloud services + +### Requirements + +- Pre-downloaded `tmp/` directory from online build +- Alternative package repository (local mirror) +- No Tailscale (you handle security) + +### Steps + +1. **On internet-connected host:** + ```bash + ./build.sh --fetch-only + tar -czf clawdie-cache.tar.gz tmp/ + # Transfer to air-gapped host + ``` + +2. **On air-gapped host:** + ```bash + tar -xzf clawdie-cache.tar.gz + ./build.sh --skip-fetch + ``` + +### Trade-offs + +- No automatic security updates +- Manual package management +- You own the security model +- No Tailscale integration + +--- + +## Troubleshooting Common Issues + +| Issue | Cause | Solution | +|-------|-------|----------| +| "Insufficient space on /mnt" | USB < 64 GB | Use 128 GB USB key | +| "pkg: Cannot access database" | No internet | Connect for fetch phase | +| "Cannot attach mdconfig" | Not root | Use `doas` or `sudo` | +| Build takes > 60 min | Slow network | Use faster connection | +| "TAILSCALE_AUTHKEY not set" | Missing key | Optional (warning only) | +| USB write fails | Bad USB | Try different USB key | +| "out of memory" during build | < 4 GB RAM | Add more RAM (8+ GB) | +| ZFS pool import fails | Wrong pool name | Pool should be "clawdie" | +| SSH connection refused | Firewall | Check PF rules, check port 22 | + +### Performance Issues + +| Symptom | Likely Cause | Fix | +|---------|--------------|-----| +| Very slow fetch (2+ hours) | Network < 1 Mbps | Use faster connection | +| Build hangs at step 5 | Slow disk | Use SSD, not HDD | +| USB write takes 30+ min | USB 2.0 + cheap USB | Use USB 3.0 + quality brand | +| First boot slow (5+ min) | Low RAM | Add more RAM | + +--- + +## Next Steps + +Once requirements are met: + +1. **Build:** See [BUILD.md](BUILD.md) for build instructions +2. **Test:** See [TESTING.md](TESTING.md) for test procedures +3. **Deploy:** Boot from USB and follow firstboot wizard + +--- + +## Quick Reference + +### Minimum Viable Setup + +``` +FreeBSD 15.0 host +8 GB RAM +128 GB USB 3.0 +10 Mbps internet +curl + doas installed +40-60 min time +``` + +### Recommended Setup + +``` +FreeBSD 15.0 host +16 GB RAM +128 GB USB 3.0 (SanDisk/Samsung) +25 Mbps internet +Tailscale auth key ready +curl + doas installed +40-60 min time +``` + +### Local LLM Setup + +``` +FreeBSD 15.0 host +32+ GB RAM +256 GB USB 3.0 +Tailscale auth key ready +curl + doas installed +GPU (optional, future acceleration) +``` + +--- + +**Questions?** See [BUILD.md](BUILD.md) for detailed build steps or [TESTING.md](TESTING.md) for testing procedures.