added niri
This commit is contained in:
Geir Okkenhaug Jerstad
parent
cdbce471ba
commit
8029d93a84
10 changed files with 837 additions and 2 deletions
305
documentation/DEVELOPMENT_WORKFLOW.md
Normal file
305
documentation/DEVELOPMENT_WORKFLOW.md
Normal file
|
|
@ -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 <repository-url> 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 <commit-hash>
|
||||
sudo nixos-rebuild switch --flake .#congenital-optimist
|
||||
|
||||
# Or revert specific changes
|
||||
git revert <bad-commit-hash>
|
||||
```
|
||||
|
||||
#### 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-<generation>-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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue