Add summary of today's session to log

2026-03-08 16:25:16 +01:00
parent 30cb05b0c9
commit afd4b414e4
1 changed files with 133 additions and 0 deletions
--- a/docs/logs/2026-03-08-initial-setup.md
+++ b/docs/logs/2026-03-08-initial-setup.md
@@ -0,0 +1,133 @@
+# Project Log: Rostyr
+
+## Date: 2026-03-08
+
+## Context
+- **Original project**: styr (https://gitea.rowanbrook.net/jakob/styr) - Shell scripts for configuring FreeBSD workstations, servers, VMs, and jails
+- **Rewrite target**: rostyr (https://gitea.rowanbrook.net/jakob/rostyr) - Rust rewrite
+
+## Requirements Decided
+
+| Requirement | Decision | Rationale |
+|-------------|----------|-----------|
+| Scope | Minimal first, then expand | User preference - start lean, add incrementally |
+| Platform | FreeBSD-focused | Keep aligned with styr's FreeBSD focus |
+| Config format | TOML | Structured config vs shell scripts |
+| Idempotency | All commands re-runnable | Critical requirement - run anytime without side effects |
+| Testing | Snapshot-based | User preference - run apply twice, verify no changes second time |
+| Test infrastructure | VMs | User preference - bhyve VMs for testing |
+| Rollback | Automatic ZFS snapshots | User preference - prominent ZFS usage |
+| apply command | Actually applies | User preference - not dry-run by default |
+
+## Architecture
+
+### Platform Strategy
+- **Hosts**: FreeBSD only
+- **Jails**: Primary service isolation (FreeBSD-native)
+- **bhyve VMs**: For Linux-incompatible services
+- **ZFS**: Snapshot-based backup/rollback (prominent usage)
+
+### CLI Commands
+```
+rostyr init <hostname>     # Scaffold new host config
+rostyr validate           # Validate all TOML configs
+rostyr diff [--host H]   # Show pending changes (dry-run)
+rostyr check [--host H]  # Detect current system state
+rostyr apply [--host H]  # Apply changes (creates ZFS snapshot first)
+rostyr rollback          # Revert to last ZFS snapshot
+```
+
+### Idempotency Strategy
+1. **Detect** current state (jails, VMs, ZFS, users, packages)
+2. **Diff** desired vs actual state
+3. **Plan** minimal changes needed
+4. **Execute** only when state differs
+5. **Snapshot** ZFS before any apply
+
+### Testing Strategy
+- **Unit tests**: Config parsing, state detection, diff logic
+- **Integration tests**: CLI commands against isolated test VMs
+- **Idempotency tests**: Run apply twice, verify no changes on second run (snapshot comparison)
+- **VMs for testing**: All tests run in isolated bhyve VMs before production deployment
+
+## Project Created
+
+### Branch
+- `draft/initial-setup` (created from main)
+
+### Files
+- `README.md` - Project documentation with overview, architecture, roadmap
+- `Cargo.toml` - Rust dependencies: clap, toml, serde, thiserror, tracing, anyhow
+- `src/main.rs` - CLI with 6 commands scaffolded
+- `src/lib.rs` - Module declarations
+- `src/{config,state,planner,executor,jail,vm,zfs,commands}/mod.rs` - Placeholder modules
+
+### Directory Structure
+```
+rostyr/
+├── README.md
+├── Cargo.toml
+├── configs/
+│   ├── hosts/
+│   ├── users/
+│   └── services/
+├── src/
+│   ├── main.rs
+│   ├── lib.rs
+│   ├── config/
+│   ├── state/
+│   ├── planner/
+│   ├── executor/
+│   ├── jail/
+│   ├── vm/
+│   ├── zfs/
+│   └── commands/
+└── tests/
+    ├── unit/
+    ├── integration/
+    └── idempotency/
+```
+
+### Status
+- Project compiles successfully
+- Ready for review/merge to main
+
+## Phased Roadmap
+
+### Phase 1 - Core Foundation
+- Project scaffolding (Rust, CLI framework)
+- Config parsing (TOML)
+- Basic state detection (host info, ZFS)
+- init, validate commands
+
+### Phase 2 - Idempotent Apply
+- Diff/planner logic
+- Apply command with ZFS snapshot
+- Rollback command
+- check command
+
+### Phase 3 - Jails
+- Jail creation/management
+- Basic service jail templates
+- User management inside jails
+
+### Phase 4 - bhyve VMs
+- VM lifecycle management
+- Linux VM templates
+- Service deployment to VMs
+
+### Phase 5+ - Services
+- Individual service implementations (from styr)
+- Full port of styr functionality
+
+## styr Reference (for porting)
+
+### Structure (from API)
+- `Core/` - Core initialization scripts (freebsd.zsh, init/*.sh, functions.zsh, settings.zsh)
+- `Host/` - Host configurations: borgen, london, madrid, rackett, template
+- `User/` - User configurations: elisabet, jakob, root, stefan
+- `Service/` - Service definitions: arr, bhyve, bitcoind, fah, gitea, iocage, iperf, joinmarket, mariadb, matrix, nfs, specter, tor, transmission, zab
+- `Scripts/` - Helper scripts: jmc.zsh, vml, vms
+
+### Description (from repo)
+"Set of scripts to configure workstations, servers, virtual machines, and jails"