geir/home-lab
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
home-lab/packages/lab-tool/DEVELOPMENT.md
Geir O. Jerstad 47c2961033 Refactor emacs configuration and clean up lab-tool project 
- Reorganized emacs configuration with profiles in modules/development/emacs.nix
- Updated machine configurations to use new emacs module structure
- Cleaned up lab-tool project by removing archive, research, testing, and utils directories
- Streamlined lab-tool to focus on core deployment functionality with deploy-rs
- Added DEVELOPMENT.md documentation for lab-tool

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-07-03 17:45:34 +02:00

3.4 KiB
Raw Blame History

Lab Tool Development Guide

Build Commands

Build the Lab Tool Package

# Build the lab tool from project root
nix build .#packages.x86_64-linux.lab

# The binary will be available at ./result/bin/lab

Quick Development Build

# From the lab-tool directory
cd packages/lab-tool
nix build .#lab-tool  # if available, otherwise use full path above

Testing Commands

Test Lab Tool Functionality

# Test help command
./result/bin/lab help

# Test machine listing
./result/bin/lab machines

# Test status check
./result/bin/lab status

# Test dry-run deployment
./result/bin/lab deploy little-rascal --dry-run

# Test actual deployment
./result/bin/lab deploy little-rascal

Test System Integration

# Deploy configuration using nixos-rebuild (requires sudo access)
sudo nixos-rebuild switch --flake .#little-rascal --show-trace

# Or using lab tool (recommended)
lab deploy little-rascal

Development Workflow

1. Make Changes

Edit source files in:

  • main.scm - CLI interface
  • lab/deployment.scm - Deployment logic
  • lab/machines.scm - Machine management
  • utils/*.scm - Utility functions

2. Build and Test

# Rebuild after changes
nix build .#packages.x86_64-linux.lab

# Test basic functionality
./result/bin/lab help
./result/bin/lab machines

# Test deployment (dry-run first)
./result/bin/lab deploy little-rascal --dry-run

3. Debug Issues

# Enable Guile debugging
export GUILE_AUTO_COMPILE=0

# Run with verbose output
./result/bin/lab deploy little-rascal --dry-run

# Check deploy-rs command directly
deploy --help

Common Development Tasks

Update Deploy-rs Command Format

Edit lab/deployment.scm in the build-deploy-command function:

;; Example: Add new flags
(when new-option
  (set! flags (cons "--new-flag=value" flags)))

Add New Machine

Add to the machine list in lab/machines.scm or config files.

Debug Deployment Issues

  1. Check the generated command with dry-run
  2. Test deploy-rs directly: deploy '.#little-rascal' --dry-activate
  3. Check flake structure: nix flake show

Module Structure

  • main.scm - Entry point and CLI parsing
  • lab/core.scm - Core lab functionality
  • lab/deployment.scm - Deploy-rs integration
  • lab/machines.scm - Machine management
  • lab/monitoring.scm - Health checks and monitoring
  • lab/auto-update.scm - Automatic update system
  • utils/logging.scm - Logging system with colors
  • utils/config.scm - Configuration management
  • utils/ssh.scm - SSH utilities
  • utils/json.scm - JSON handling

Troubleshooting

Build Failures

# Check flake structure
nix flake show

# Verify Guile syntax
guile --no-auto-compile -c "(load \"main.scm\")"

Runtime Errors

# Check module exports
guile -c "(use-modules (lab deployment)) (display 'loaded)"

# Test individual functions
guile -c "(use-modules (lab deployment)) (deploy-machine \"little-rascal\" \"default\" '((dry-run . #t)))"

Deploy-rs Issues

# Test deploy-rs directly
deploy '.#little-rascal' --dry-activate

# Check machine connectivity
ssh sma@little-rascal 'echo "connected"'

Best Practices

  1. Always test with dry-run first
  2. Use the lab tool instead of direct nixos-rebuild when possible
  3. Check flake status before deployment (nix flake check)
  4. Keep commits atomic - one feature/fix per commit
  5. Update this file when adding new commands or workflows