clawdie/clawdie-iso
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: add REQUIREMENTS.md with pre-install checklist (Sam & Claude)

Browse source 
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
This commit is contained in:
Sam & Claude 2026-04-06 12:25:39 +02:00 • committed by 123kupola
parent c3599469e0
commit 95aec991f0
1 changed files with 355 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

355
REQUIREMENTS.md Normal file
View file

@ -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.