From 344e7686bfedfb7464db97afbd060c3448912b43 Mon Sep 17 00:00:00 2001 From: Geir Okkenhaug Jerstad Date: Wed, 4 Jun 2025 16:20:05 +0200 Subject: [PATCH] Workflow description --- DEVELOPMENT_WORKFLOW.md | 305 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 305 insertions(+) diff --git a/DEVELOPMENT_WORKFLOW.md b/DEVELOPMENT_WORKFLOW.md index e69de29..babd443 100644 --- a/DEVELOPMENT_WORKFLOW.md +++ b/DEVELOPMENT_WORKFLOW.md @@ -0,0 +1,305 @@ +# ๐Ÿ”„ Development Workflow for Home Lab Infrastructure + +## Overview + +This document outlines the development workflow for the NixOS Home Lab infrastructure, emphasizing GitOps principles, automated testing, and safe configuration management. + +## ๐Ÿš€ Quick Start for Contributors + +### Prerequisites +- NixOS system with flakes enabled +- Git configured with your credentials +- Access to the home lab machines (if deploying) + +### Initial Setup +```bash +# Clone the repository +git clone Home-lab +cd Home-lab + +# Verify flake configuration +nix flake check + +# Test configuration locally (safe, non-persistent) +sudo nixos-rebuild test --flake .#congenital-optimist +``` + +## ๐Ÿ”„ Development Cycle + +### 1. Feature Development +```bash +# Start from develop branch +git checkout develop +git pull origin develop + +# Create feature branch +git checkout -b feature/improve-desktop-config + +# Make your changes +# ... edit configuration files ... + +# Validate configuration +nix flake check + +# Test configuration (non-persistent) +sudo nixos-rebuild test --flake .#congenital-optimist + +# Stage and commit changes +git add . +git commit -m "feat(desktop): improve GNOME configuration + +- Add GNOME extensions for better workflow +- Configure custom keybindings +- Optimize performance settings" + +# Push to remote +git push origin feature/improve-desktop-config +``` + +### 2. Pull Request Process +1. **Create PR** from feature branch to `develop` +2. **Automated Testing** runs via GitHub Actions: + - Flake syntax validation + - Build tests for all machines + - Security audit + - Documentation checks +3. **Code Review** by team members +4. **Local Testing** by reviewers (optional but recommended) +5. **Merge** to develop after approval + +### 3. Production Deployment +```bash +# Merge develop to main (after testing) +git checkout main +git merge develop + +# Tag release +git tag -a v1.1.0 -m "Release v1.1.0: Desktop improvements" + +# Deploy to production +sudo nixos-rebuild switch --flake .#congenital-optimist +``` + +## ๐Ÿงช Testing Strategy + +### Automated Testing (CI/CD) +Our GitHub Actions pipeline automatically tests: + +- **Syntax Validation**: `nix flake check --all-systems` +- **Build Testing**: Full system build for each machine +- **Security Scanning**: Check for secrets and vulnerabilities +- **Module Validation**: Individual module testing +- **Documentation**: Ensure docs are up to date + +### Manual Testing Levels + +#### Level 1: Basic Validation +```bash +# Quick syntax check +nix flake check + +# Build without applying +nix build .#nixosConfigurations.congenital-optimist.config.system.build.toplevel +``` + +#### Level 2: Safe Testing +```bash +# Test configuration (temporary, reverts on reboot) +sudo nixos-rebuild test --flake .#congenital-optimist + +# Verify services +systemctl status incus libvirtd podman.socket +``` + +#### Level 3: Persistent Testing +```bash +# Apply configuration permanently +sudo nixos-rebuild switch --flake .#congenital-optimist + +# Create rollback point +sudo nixos-rebuild test --flake .#congenital-optimist --rollback +``` + +## ๐Ÿ—๏ธ Configuration Architecture + +### Module Organization +``` +modules/ +โ”œโ”€โ”€ common/ # Shared base configuration +โ”œโ”€โ”€ desktop/ # Desktop environment modules +โ”œโ”€โ”€ development/ # Development tools and editors +โ”œโ”€โ”€ hardware/ # Hardware-specific configurations +โ”œโ”€โ”€ services/ # Service configurations +โ”œโ”€โ”€ system/ # Core system modules +โ”œโ”€โ”€ users/ # User configurations +โ””โ”€โ”€ virtualization/ # Container and VM setup +``` + +### Best Practices + +#### Module Design +- **Single Responsibility**: Each module handles one aspect +- **Configurable**: Use options for customization +- **Documented**: Include comments and documentation +- **Testable**: Design for easy testing + +#### Configuration Changes +- **Small Commits**: Make focused, atomic changes +- **Test First**: Always test before committing +- **Document Impact**: Explain what changes and why +- **Consider Rollback**: Ensure changes can be reverted + +## ๐Ÿ” Security Considerations + +### Configuration Security +- **No Secrets in Git**: Never commit passwords, keys, or certificates +- **Proper Permissions**: Set correct file permissions in configuration +- **Firewall Rules**: Review network access changes +- **User Privileges**: Validate user group memberships + +### Development Security +- **Branch Protection**: Main branch requires reviews +- **Signed Commits**: Consider GPG signing for production +- **Access Control**: Limit who can deploy to production +- **Audit Trail**: All changes tracked in git history + +## ๐Ÿšจ Emergency Procedures + +### Rollback Procedures + +#### Git-based Rollback +```bash +# Find last known good commit +git log --oneline + +# Rollback to specific commit +git checkout +sudo nixos-rebuild switch --flake .#congenital-optimist + +# Or revert specific changes +git revert +``` + +#### NixOS Generation Rollback +```bash +# List available generations +sudo nixos-rebuild list-generations + +# Rollback to previous generation +sudo nixos-rebuild switch --rollback + +# Or switch to specific generation +sudo /nix/var/nix/profiles/system--link/bin/switch-to-configuration switch +``` + +#### ZFS Snapshot Rollback +```bash +# List snapshots +zfs list -t snapshot + +# Rollback to snapshot (destructive!) +zfs rollback zpool/root@pre-update-snapshot +``` + +### Recovery Boot +If system fails to boot: +1. Boot from NixOS installation media +2. Import ZFS pools if needed +3. Chroot into system +4. Rollback to working configuration +5. Rebuild and reboot + +## ๐Ÿ“Š Monitoring and Maintenance + +### Health Checks +Regular monitoring should include: + +- **System Generations**: Track configuration changes +- **Service Status**: Monitor critical services +- **Storage Health**: ZFS pool status +- **Security Updates**: Regular dependency updates +- **Performance**: System resource utilization + +### Automated Maintenance +Our CI/CD pipeline handles: + +- **Weekly Dependency Updates**: Automated flake.lock updates +- **Security Scanning**: Regular vulnerability checks +- **Documentation Updates**: Auto-generated documentation +- **Build Verification**: Continuous build testing + +### Manual Maintenance Tasks + +#### Weekly +- Review open pull requests +- Check system logs for errors +- Verify backup operations +- Update development environment + +#### Monthly +- Security audit of configurations +- Clean up old git branches +- Review and update documentation +- Performance optimization review + +#### Quarterly +- Major dependency updates +- Infrastructure planning review +- Security policy updates +- Disaster recovery testing + +## ๐ŸŽฏ Performance Optimization + +### Build Performance +- **Nix Binary Cache**: Use shared cache for faster builds +- **Parallel Builds**: Configure appropriate build parallelism +- **Module Organization**: Optimize module import structure +- **Build Dependencies**: Minimize unnecessary dependencies + +### Runtime Performance +- **Service Configuration**: Optimize service settings +- **Hardware Configuration**: Tune for specific hardware +- **Resource Allocation**: Configure appropriate limits +- **Monitoring**: Track performance metrics + +## ๐Ÿ“ Documentation Standards + +### Code Documentation +- **Module Comments**: Explain complex configurations +- **Option Documentation**: Document custom options +- **Example Usage**: Provide usage examples +- **Change Rationale**: Explain why changes were made + +### Process Documentation +- **Workflow Updates**: Keep process docs current +- **Decision Records**: Document architectural decisions +- **Troubleshooting**: Maintain troubleshooting guides +- **Knowledge Transfer**: Document tribal knowledge + +## ๐Ÿค Collaboration Guidelines + +### Communication +- **Clear Commit Messages**: Use conventional commit format +- **Descriptive PRs**: Explain what and why +- **Review Feedback**: Provide constructive feedback +- **Documentation**: Update docs with changes + +### Code Review Focus Areas +1. **Correctness**: Does the configuration work? +2. **Security**: Any security implications? +3. **Performance**: Impact on system performance? +4. **Maintainability**: Is the code maintainable? +5. **Documentation**: Are docs updated? + +## ๐Ÿ”— Related Documentation + +- [**README.md**](README.md): Project overview and quick start +- [**BRANCHING_STRATEGY.md**](BRANCHING_STRATEGY.md): Git workflow details +- [**plan.md**](plan.md): Migration and development plan +- [**CI/CD Pipeline**](.github/workflows/ci.yml): Automated testing configuration + +--- + +*"The important thing is not to panic."* - Douglas Adams + +This workflow ensures reliable, tested, and maintainable infrastructure while enabling rapid development and safe deployments.