134 lines
4.3 KiB
Markdown
134 lines
4.3 KiB
Markdown
# 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"
|