Geir O. Jerstad
ef4b4b7736
- Add comprehensive Home Manager refactoring plan document - Create initial Home Manager directory structure with user configs - Add modular Emacs configuration for Home Manager integration - Update system configurations for Home Manager compatibility - Preserve existing functionality while preparing for migration 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
441 lines
No EOL
15 KiB
Markdown
441 lines
No EOL
15 KiB
Markdown
# Home Manager Refactoring Plan
|
|
|
|
## Executive Summary
|
|
|
|
This document outlines a comprehensive plan to refactor the current user configuration management system from a system-centric NixOS approach to a user-centric Home Manager approach. The refactoring will provide better separation of concerns, improved dotfile management, user-level service management, and enhanced maintainability while preserving the existing sophisticated Emacs configuration system.
|
|
|
|
## Current Architecture Analysis
|
|
|
|
### Strengths of Current System
|
|
- **Declarative Configuration**: All configurations defined in Nix modules
|
|
- **Sophisticated Emacs Integration**: Profile-based Emacs system with Nix tool integration
|
|
- **Multi-machine Consistency**: Centralized configuration repository
|
|
- **Modular Design**: Clear separation between machines, modules, and users
|
|
- **Nix Tool Integration**: Excellent integration with Nix-provided tools and language servers
|
|
|
|
### Current Limitations
|
|
- **System-level User Configuration**: User preferences mixed with system configuration
|
|
- **No User Service Management**: Cannot manage user-level systemd services
|
|
- **Manual Dotfile Deployment**: Limited systematic dotfile management
|
|
- **Monolithic User Modules**: Large, complex user configuration files
|
|
- **No Per-user Package Management**: User packages defined at system level
|
|
|
|
## Refactoring Goals
|
|
|
|
### Primary Objectives
|
|
1. **Separate User from System Configuration**: Move user-specific settings to Home Manager
|
|
2. **Enable User Service Management**: Leverage Home Manager's systemd user service support
|
|
3. **Systematic Dotfile Management**: Implement proper dotfile deployment and management
|
|
4. **Preserve Emacs Excellence**: Maintain current sophisticated Emacs configuration
|
|
5. **Improve Maintainability**: Reduce complexity and improve modularity
|
|
|
|
### Secondary Objectives
|
|
1. **Multi-user Support**: Better support for multiple users with different preferences
|
|
2. **Development Environment Isolation**: User-level development environments
|
|
3. **Profile-based Configuration**: Different user profiles for different contexts
|
|
4. **Improved Package Management**: User-level package installation and management
|
|
|
|
## Migration Strategy
|
|
|
|
### Phase 1: Foundation Setup
|
|
**Timeline**: Week 1-2
|
|
**Risk Level**: Low
|
|
|
|
#### Tasks:
|
|
1. **Initialize Home Manager Integration**
|
|
- Add Home Manager to flake.nix inputs
|
|
- Configure basic Home Manager module in NixOS
|
|
- Create initial home.nix for user 'geir'
|
|
|
|
2. **Create Home Manager Directory Structure**
|
|
```
|
|
home-manager/
|
|
├── users/
|
|
│ ├── geir/
|
|
│ │ ├── home.nix # Main user configuration
|
|
│ │ ├── profiles/
|
|
│ │ │ ├── development.nix # Development profile
|
|
│ │ │ ├── workstation.nix # Full workstation profile
|
|
│ │ │ └── minimal.nix # Minimal profile
|
|
│ │ ├── programs/
|
|
│ │ │ ├── emacs.nix # Emacs configuration
|
|
│ │ │ ├── zsh.nix # Shell configuration
|
|
│ │ │ ├── git.nix # Git configuration
|
|
│ │ │ └── development.nix # Development tools
|
|
│ │ └── services/
|
|
│ │ ├── emacs-daemon.nix # User-level Emacs daemon
|
|
│ │ └── desktop.nix # Desktop services
|
|
│ └── sma/
|
|
│ └── home.nix # Admin user configuration
|
|
├── modules/
|
|
│ ├── emacs/ # Shared Emacs modules
|
|
│ ├── development/ # Development environment modules
|
|
│ └── desktop/ # Desktop environment modules
|
|
└── dotfiles/
|
|
├── emacs/ # Emacs configuration files
|
|
├── shell/ # Shell configuration files
|
|
└── desktop/ # Desktop configuration files
|
|
```
|
|
|
|
3. **Basic User Configuration Migration**
|
|
- Migrate user packages from system to Home Manager
|
|
- Set up basic shell configuration
|
|
- Implement minimal dotfile management
|
|
|
|
#### Deliverables:
|
|
- Working Home Manager integration
|
|
- Basic user configuration in Home Manager
|
|
- Preserved system functionality
|
|
|
|
### Phase 2: Emacs Migration
|
|
**Timeline**: Week 3-4
|
|
**Risk Level**: Medium
|
|
|
|
#### Tasks:
|
|
1. **Migrate Emacs Configuration to Home Manager**
|
|
- Preserve current profile-based system
|
|
- Migrate from `/etc/emacs/` to Home Manager file management
|
|
- Maintain Nix tool integration
|
|
- Convert systemd service to user service
|
|
|
|
2. **Enhanced Emacs Module Structure**
|
|
```nix
|
|
programs.emacs = {
|
|
enable = true;
|
|
profile = "development"; # or "workstation", "minimal"
|
|
package = emacsWithProfile;
|
|
|
|
profiles = {
|
|
minimal = {
|
|
packages = [...];
|
|
extraConfig = "...";
|
|
};
|
|
development = {
|
|
packages = [...];
|
|
extraConfig = "...";
|
|
};
|
|
workstation = {
|
|
packages = [...];
|
|
extraConfig = "...";
|
|
};
|
|
};
|
|
|
|
nixIntegration = {
|
|
enableLspServers = true;
|
|
enableFormatters = true;
|
|
tools = {
|
|
ripgrep = true;
|
|
fd = true;
|
|
sqlite = true;
|
|
};
|
|
};
|
|
};
|
|
```
|
|
|
|
3. **Dotfile Management for Emacs**
|
|
- Use `xdg.configFile` for Emacs configuration deployment
|
|
- Maintain modular structure
|
|
- Preserve profile-based loading
|
|
|
|
#### Deliverables:
|
|
- Emacs fully managed by Home Manager
|
|
- User-level Emacs daemon service
|
|
- Preserved profile-based functionality
|
|
- Improved dotfile deployment
|
|
|
|
### Phase 3: Complete User Migration
|
|
**Timeline**: Week 5-6
|
|
**Risk Level**: Medium
|
|
|
|
#### Tasks:
|
|
1. **Shell Configuration Migration**
|
|
- Move zsh configuration to Home Manager
|
|
- Implement user-specific aliases and functions
|
|
- Preserve current shell enhancement integration
|
|
|
|
2. **Development Environment Setup**
|
|
- User-level development tools
|
|
- Language server configurations
|
|
- Project-specific environments
|
|
|
|
3. **Desktop Environment Integration**
|
|
- User-level desktop services
|
|
- Application-specific configurations
|
|
- Theme and appearance management
|
|
|
|
#### Deliverables:
|
|
- Complete user environment in Home Manager
|
|
- System packages reduced to essential only
|
|
- User-specific development environments
|
|
|
|
### Phase 4: Multi-user and Profiles
|
|
**Timeline**: Week 7-8
|
|
**Risk Level**: Low
|
|
|
|
#### Tasks:
|
|
1. **Multi-user Support**
|
|
- Migrate 'sma' user configuration
|
|
- Shared modules for common functionality
|
|
- User-specific customizations
|
|
|
|
2. **Profile System Enhancement**
|
|
- Machine-specific user profiles
|
|
- Context-aware configurations
|
|
- Easy profile switching
|
|
|
|
3. **Documentation and Testing**
|
|
- Comprehensive documentation
|
|
- Migration testing on different machines
|
|
- Rollback procedures
|
|
|
|
#### Deliverables:
|
|
- Complete multi-user Home Manager setup
|
|
- Profile-based user configurations
|
|
- Comprehensive documentation
|
|
|
|
## Technical Implementation Details
|
|
|
|
### Home Manager Integration Pattern
|
|
|
|
```nix
|
|
# flake.nix
|
|
{
|
|
inputs = {
|
|
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
|
|
home-manager = {
|
|
url = "github:nix-community/home-manager";
|
|
inputs.nixpkgs.follows = "nixpkgs";
|
|
};
|
|
};
|
|
|
|
outputs = { nixpkgs, home-manager, ... }: {
|
|
nixosConfigurations = {
|
|
little-rascal = nixpkgs.lib.nixosSystem {
|
|
system = "x86_64-linux";
|
|
modules = [
|
|
./machines/little-rascal/configuration.nix
|
|
home-manager.nixosModules.home-manager
|
|
{
|
|
home-manager.useGlobalPkgs = true;
|
|
home-manager.useUserPackages = true;
|
|
home-manager.users.geir = import ./home-manager/users/geir/home.nix;
|
|
home-manager.users.sma = import ./home-manager/users/sma/home.nix;
|
|
}
|
|
];
|
|
};
|
|
};
|
|
};
|
|
}
|
|
```
|
|
|
|
### Emacs Configuration Structure
|
|
|
|
```nix
|
|
# home-manager/users/geir/programs/emacs.nix
|
|
{ config, lib, pkgs, ... }:
|
|
|
|
let
|
|
emacsProfile = config.programs.emacs.profile or "development";
|
|
|
|
# Package sets remain the same as current implementation
|
|
packageSets = {
|
|
essential = epkgs: with epkgs; [ use-package diminish bind-key which-key ];
|
|
minimal = epkgs: with epkgs; [ /* minimal packages */ ];
|
|
development = epkgs: with epkgs; [ /* development packages */ ];
|
|
workstation = epkgs: with epkgs; [ /* full packages */ ];
|
|
};
|
|
|
|
emacsWithProfile = profile:
|
|
(if profile == "nox" then pkgs.emacs-nox else pkgs.emacs-pgtk).pkgs.withPackages
|
|
(epkgs: packageSets.essential epkgs ++
|
|
(if profile == "nox"
|
|
then packageSets.minimal epkgs
|
|
else packageSets.development epkgs ++ packageSets.workstation epkgs));
|
|
|
|
in {
|
|
options.programs.emacs.profile = lib.mkOption {
|
|
type = lib.types.enum [ "gui" "nox" ];
|
|
default = "gui";
|
|
};
|
|
|
|
config = {
|
|
programs.emacs = {
|
|
enable = true;
|
|
package = emacsWithProfile emacsProfile;
|
|
};
|
|
|
|
services.emacs = {
|
|
enable = true;
|
|
package = config.programs.emacs.package;
|
|
};
|
|
|
|
xdg.configFile = {
|
|
"emacs/init.el".source = ../../../dotfiles/emacs/init-nix.el;
|
|
"emacs/modules/ui.el".source = ../../../dotfiles/emacs/modules/ui.el;
|
|
"emacs/modules/completion.el".source = ../../../dotfiles/emacs/modules/completion.el;
|
|
# ... other modules
|
|
};
|
|
|
|
home.sessionVariables = {
|
|
EMACS_PROFILE = emacsProfile;
|
|
RG_PATH = "${pkgs.ripgrep}/bin/rg";
|
|
FD_PATH = "${pkgs.fd}/bin/fd";
|
|
# ... other tool paths
|
|
};
|
|
};
|
|
}
|
|
```
|
|
|
|
### Dotfile Management Strategy
|
|
|
|
```nix
|
|
# home-manager/users/geir/home.nix
|
|
{
|
|
# XDG-compliant configuration files
|
|
xdg.configFile = {
|
|
"niri/config.kdl".source = ../../dotfiles/niri/config.kdl;
|
|
"git/config".source = ../../dotfiles/git/config;
|
|
};
|
|
|
|
# Home directory files
|
|
home.file = {
|
|
".zshrc".source = ../../dotfiles/shell/zshrc;
|
|
".tmux.conf".source = ../../dotfiles/tmux/tmux.conf;
|
|
};
|
|
|
|
# Direct content management
|
|
xdg.configFile."starship.toml".text = ''
|
|
# Starship configuration
|
|
format = "$all$character"
|
|
'';
|
|
}
|
|
```
|
|
|
|
## Risk Assessment and Mitigation
|
|
|
|
### High-Risk Areas
|
|
1. **Emacs Configuration Migration**
|
|
- **Risk**: Breaking existing sophisticated Emacs setup
|
|
- **Mitigation**:
|
|
- Preserve exact current functionality first
|
|
- Test on non-critical machine first
|
|
- Maintain parallel system during transition
|
|
|
|
2. **User Service Management**
|
|
- **Risk**: Service startup/shutdown issues
|
|
- **Mitigation**:
|
|
- Test user services thoroughly
|
|
- Provide fallback to system services
|
|
- Document service debugging procedures
|
|
|
|
### Medium-Risk Areas
|
|
1. **Package Dependency Changes**
|
|
- **Risk**: Missing packages or version conflicts
|
|
- **Mitigation**:
|
|
- Careful package migration tracking
|
|
- Test on all machine types
|
|
- Maintain system packages temporarily
|
|
|
|
2. **Dotfile Deployment**
|
|
- **Risk**: Configuration file conflicts or missing files
|
|
- **Mitigation**:
|
|
- Backup existing configurations
|
|
- Gradual migration approach
|
|
- Collision detection and resolution
|
|
|
|
### Low-Risk Areas
|
|
1. **Shell Configuration**
|
|
- **Risk**: Minor shell behavior changes
|
|
- **Mitigation**: Preserve exact current shell configuration
|
|
|
|
2. **Git Configuration**
|
|
- **Risk**: Git workflow disruption
|
|
- **Mitigation**: Migrate settings exactly as-is
|
|
|
|
## Testing Strategy
|
|
|
|
### Phase Testing
|
|
1. **Per-phase Testing**: Each phase tested independently
|
|
2. **Machine-specific Testing**: Test on each machine type
|
|
3. **User-specific Testing**: Test for both geir and sma users
|
|
4. **Rollback Testing**: Verify rollback procedures work
|
|
|
|
### Test Environments
|
|
1. **Development VM**: Safe testing environment
|
|
2. **Non-critical Machine**: Real hardware testing
|
|
3. **Critical Machines**: Final validation
|
|
|
|
### Test Cases
|
|
1. **Emacs Functionality**: All profiles, modules, and integrations
|
|
2. **Development Workflow**: Complete development environment
|
|
3. **Service Management**: User services start/stop correctly
|
|
4. **Multi-machine**: Configuration works across all machines
|
|
5. **Package Management**: All user packages available
|
|
|
|
## Migration Timeline
|
|
|
|
| Week | Phase | Focus | Risk Level |
|
|
|------|-------|-------|------------|
|
|
| 1-2 | Foundation | Home Manager setup, basic migration | Low |
|
|
| 3-4 | Emacs | Emacs configuration migration | Medium |
|
|
| 5-6 | Complete User | Full user environment migration | Medium |
|
|
| 7-8 | Polish | Multi-user, profiles, documentation | Low |
|
|
|
|
## Success Criteria
|
|
|
|
### Functional Requirements
|
|
- [ ] All current functionality preserved
|
|
- [ ] Emacs profiles work exactly as before
|
|
- [ ] User services managed by Home Manager
|
|
- [ ] Dotfiles systematically deployed
|
|
- [ ] Development environment fully functional
|
|
|
|
### Quality Requirements
|
|
- [ ] Configuration is more modular and maintainable
|
|
- [ ] Clear separation between user and system configuration
|
|
- [ ] Comprehensive documentation
|
|
- [ ] Easy rollback capability
|
|
- [ ] Multi-user support functional
|
|
|
|
### Performance Requirements
|
|
- [ ] No degradation in system startup time
|
|
- [ ] Emacs startup time maintained or improved
|
|
- [ ] Home Manager switch time acceptable (<30 seconds)
|
|
|
|
## Rollback Plan
|
|
|
|
### Emergency Rollback
|
|
1. **Git Revert**: Revert to pre-migration commit
|
|
2. **System Rebuild**: `sudo nixos-rebuild switch --flake .`
|
|
3. **Service Restart**: Restart affected services
|
|
|
|
### Partial Rollback
|
|
1. **Disable Home Manager**: Comment out Home Manager in machine configuration
|
|
2. **Restore System Packages**: Move packages back to system level
|
|
3. **Manual Service Management**: Manually manage services during transition
|
|
|
|
### Validation Steps
|
|
1. **Emacs Functionality**: Verify Emacs starts and works correctly
|
|
2. **Development Environment**: Verify development tools work
|
|
3. **User Services**: Verify essential services are running
|
|
4. **System Stability**: Verify system is stable and responsive
|
|
|
|
## Documentation Deliverables
|
|
|
|
### User Documentation
|
|
1. **Migration Guide**: Step-by-step migration instructions
|
|
2. **Home Manager Usage**: How to use Home Manager for daily workflow
|
|
3. **Profile Management**: How to switch and manage user profiles
|
|
4. **Troubleshooting Guide**: Common issues and solutions
|
|
|
|
### Developer Documentation
|
|
1. **Architecture Documentation**: New system architecture
|
|
2. **Module Documentation**: How modules are structured and work
|
|
3. **Extension Guide**: How to add new functionality
|
|
4. **Testing Procedures**: How to test changes
|
|
|
|
## Conclusion
|
|
|
|
This refactoring plan provides a comprehensive roadmap for migrating from the current system-centric user configuration to a modern Home Manager-based approach. The phased approach minimizes risk while ensuring all current functionality is preserved and enhanced. The end result will be a more maintainable, flexible, and user-centric configuration management system that better separates concerns between system and user configuration.
|
|
|
|
The plan prioritizes preserving the excellent current Emacs configuration while adding the benefits of proper user-level service management, systematic dotfile deployment, and improved modularity. The migration can be executed with confidence due to the comprehensive testing strategy and rollback procedures. |