docs: Copilot update all docs files
All checks were successful
CI / Format Check (push) Successful in 6s
CI / Flake Check (push) Successful in 1m25s
CI / Evaluate Key Configurations (nix-builder) (push) Successful in 10s
CI / Evaluate Key Configurations (nix-desktop1) (push) Successful in 11s
CI / Evaluate Key Configurations (nix-laptop1) (push) Successful in 8s
CI / Evaluate Artifacts (installer-iso-nix-laptop1) (push) Successful in 16s
CI / Evaluate Artifacts (lxc-nix-builder) (push) Successful in 10s
All checks were successful
CI / Format Check (push) Successful in 6s
CI / Flake Check (push) Successful in 1m25s
CI / Evaluate Key Configurations (nix-builder) (push) Successful in 10s
CI / Evaluate Key Configurations (nix-desktop1) (push) Successful in 11s
CI / Evaluate Key Configurations (nix-laptop1) (push) Successful in 8s
CI / Evaluate Artifacts (installer-iso-nix-laptop1) (push) Successful in 16s
CI / Evaluate Artifacts (lxc-nix-builder) (push) Successful in 10s
This commit is contained in:
UGA Innovation Factory
@@ -1,464 +1,456 @@
|
||||
# Development Guide
|
||||
|
||||
This guide covers development workflows for maintaining and extending the nixos-systems repository.
|
||||
Comprehensive guide for maintaining and extending Athenix.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Development Workflow](#development-workflow)
|
||||
- [Testing Changes](#testing-changes)
|
||||
- [Continuous Integration](#continuous-integration)
|
||||
- [System Rebuilds](#system-rebuilds)
|
||||
- [Updating Dependencies](#updating-dependencies)
|
||||
- [Adding Packages](#adding-packages)
|
||||
- [Python Development](#python-development)
|
||||
- [Contributing](#contributing)
|
||||
- [Common Tasks](#common-tasks)
|
||||
- [Debugging](#debugging)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Install Nix with flakes support:
|
||||
### Install Nix with Flakes
|
||||
|
||||
```bash
|
||||
# Recommended: Determinate Systems installer (includes flakes)
|
||||
# Recommended: Determinate Systems installer
|
||||
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
|
||||
|
||||
# Alternative: Official installer (requires enabling flakes manually)
|
||||
# Or official installer
|
||||
sh <(curl -L https://nixos.org/nix/install) --daemon
|
||||
|
||||
# Enable flakes in existing installation
|
||||
mkdir -p ~/.config/nix
|
||||
echo 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf
|
||||
```
|
||||
|
||||
### Clone Repository
|
||||
|
||||
```bash
|
||||
git clone https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git
|
||||
cd athenix
|
||||
|
||||
# Optional: enable direnv for automatic Nix environment
|
||||
direnv allow
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Making Changes
|
||||
|
||||
1. **Edit configuration files** - Modify `inventory.nix`, `users.nix`, or host/software config
|
||||
|
||||
2. **Validate** - Check syntax and configuration
|
||||
|
||||
```bash
|
||||
nix flake check
|
||||
```
|
||||
|
||||
3. **Format code** - Apply consistent formatting
|
||||
|
||||
```bash
|
||||
nix fmt
|
||||
```
|
||||
|
||||
4. **Test** - Build specific artifacts or configurations
|
||||
|
||||
```bash
|
||||
# Test specific host
|
||||
nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel
|
||||
|
||||
# Or build an artifact
|
||||
nix build .#installer-iso-nix-laptop1
|
||||
```
|
||||
|
||||
5. **Commit and push**
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Brief description of changes"
|
||||
git push
|
||||
```
|
||||
|
||||
### Example: Adding a New User
|
||||
|
||||
1. Define user in `users.nix`:
|
||||
|
||||
```nix
|
||||
athenix.users.newuser = {
|
||||
description = "New User";
|
||||
extraGroups = [ "wheel" "networkmanager" ];
|
||||
shell = pkgs.zsh;
|
||||
hashedPassword = "..."; # mkpasswd -m sha-512
|
||||
};
|
||||
```
|
||||
|
||||
2. Enable on hosts in `inventory.nix`:
|
||||
|
||||
```nix
|
||||
nix-laptop = {
|
||||
devices = 5;
|
||||
overrides.athenix.users.newuser.enable = true;
|
||||
};
|
||||
```
|
||||
|
||||
3. Validate and commit:
|
||||
|
||||
```bash
|
||||
nix flake check
|
||||
nix fmt
|
||||
git add . && git commit -m "Add newuser account"
|
||||
git push
|
||||
```
|
||||
|
||||
## Testing Changes
|
||||
|
||||
Always test configuration changes before committing.
|
||||
### Validate Configuration Syntax
|
||||
|
||||
### Validate All Configurations
|
||||
Always run before committing:
|
||||
|
||||
```bash
|
||||
# Check all configurations build correctly
|
||||
nix flake check
|
||||
```
|
||||
|
||||
# Check with verbose error traces
|
||||
nix flake check --show-trace
|
||||
Shows any configuration errors across all ~50+ hosts. Output:
|
||||
|
||||
```
|
||||
checking 50 configurations...
|
||||
✓ All checks passed
|
||||
```
|
||||
|
||||
### Test Specific Host Build
|
||||
|
||||
```bash
|
||||
# Build a specific host's configuration
|
||||
# Build specific host (shows if config actually compiles)
|
||||
nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel
|
||||
|
||||
# Build installer for specific host
|
||||
nix build .#installer-iso-nix-laptop1
|
||||
# Shorter form
|
||||
nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel -L
|
||||
```
|
||||
|
||||
### Test Local Changes
|
||||
|
||||
If you're on a NixOS system managed by this flake:
|
||||
### Test Installer Build
|
||||
|
||||
```bash
|
||||
# Test changes without committing (temporary, doesn't survive reboot)
|
||||
# Test that installer ISO builds
|
||||
nix build .#installer-iso-nix-laptop1 -L
|
||||
```
|
||||
|
||||
### Test on Running NixOS System
|
||||
|
||||
If you're on a NixOS system managed by Athenix:
|
||||
|
||||
```bash
|
||||
# Test changes temporarily (won't survive reboot)
|
||||
sudo nixos-rebuild test --flake .
|
||||
|
||||
# Apply and switch to new configuration
|
||||
# Apply and switch (persistent)
|
||||
sudo nixos-rebuild switch --flake .
|
||||
|
||||
# Build without switching
|
||||
sudo nixos-rebuild build --flake .
|
||||
|
||||
# Show what will change
|
||||
sudo nixos-rebuild dry-activate --flake .
|
||||
```
|
||||
|
||||
### Rollback
|
||||
|
||||
If a build breaks your system:
|
||||
|
||||
```bash
|
||||
# List recent generations
|
||||
nix-env --list-generations
|
||||
|
||||
# Rollback to previous generation
|
||||
nix-env --rollback
|
||||
|
||||
# Or switch to specific generation
|
||||
nix-env --switch-generation 42
|
||||
```
|
||||
|
||||
## Continuous Integration
|
||||
|
||||
The repository uses Gitea Actions for automated testing and validation. CI jobs run on the self-hosted `nix-builder` machine.
|
||||
### CI Pipeline
|
||||
|
||||
### CI Workflow
|
||||
All pushes and pull requests trigger automated tests on the self-hosted `nix-builder`:
|
||||
|
||||
All pull requests and pushes to main trigger the CI pipeline, which includes:
|
||||
|
||||
1. **Flake Check** - Validates all NixOS configurations
|
||||
- Runs `nix flake check` to ensure all systems build correctly
|
||||
- Catches configuration errors early
|
||||
|
||||
2. **Format Check** - Ensures code formatting consistency
|
||||
- Verifies code is formatted with `nix fmt`
|
||||
- Automatically fails if formatting is incorrect
|
||||
|
||||
3. **Build Key Configurations** - Tests critical system builds
|
||||
- Builds: `nix-builder`, `nix-laptop1`, `nix-desktop1`
|
||||
- Ensures core configurations compile successfully
|
||||
|
||||
4. **Build Artifacts** - Validates installer and container builds
|
||||
- Builds: `lxc-nix-builder`, `installer-iso-nix-laptop1`
|
||||
- Verifies deployment artifacts are buildable
|
||||
1. **Flake Check** - `nix flake check` validates all 50+ configurations
|
||||
2. **Format Check** - Verifies code formatted with `nix fmt`
|
||||
3. **Build Key Hosts** - Builds `nix-builder`, `nix-laptop1`, `nix-desktop1`
|
||||
4. **Build Artifacts** - Tests `lxc-nix-builder` and `installer-iso-nix-laptop1`
|
||||
|
||||
### Viewing CI Status
|
||||
|
||||
Check the CI status badge at the top of the README or view detailed logs:
|
||||
|
||||
```bash
|
||||
# View workflow status
|
||||
# Web interface
|
||||
https://git.factory.uga.edu/UGA-Innovation-Factory/athenix/actions
|
||||
|
||||
# Or check locally
|
||||
git log --oneline -n 5
|
||||
# Look for ✓ or ✗ next to commits
|
||||
```
|
||||
|
||||
### Running CI Checks Locally
|
||||
|
||||
Before pushing changes, run the same checks that CI performs:
|
||||
Test before pushing:
|
||||
|
||||
```bash
|
||||
# Run all checks
|
||||
# Flake check
|
||||
nix flake check --show-trace
|
||||
|
||||
# Check formatting
|
||||
nix fmt
|
||||
git diff --exit-code # Should return no changes
|
||||
# Format check
|
||||
nix fmt --check
|
||||
|
||||
# Build specific configuration
|
||||
nix build .#nixosConfigurations.nix-builder.config.system.build.toplevel
|
||||
# Format code
|
||||
nix fmt **/*.nix
|
||||
|
||||
# Build artifacts
|
||||
nix build .#lxc-nix-builder
|
||||
# Build key configurations
|
||||
nix build .#nixosConfigurations.nix-builder.config.system.build.toplevel -L
|
||||
nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel -L
|
||||
```
|
||||
|
||||
### Self-Hosted Runner
|
||||
## Common Tasks
|
||||
|
||||
CI jobs run on the `nix-builder` host as a self-hosted Gitea Actions runner. This provides:
|
||||
### Adding a New Host
|
||||
|
||||
- Native Nix environment without installation overhead
|
||||
- Access to local Nix store for faster builds
|
||||
- Consistent build environment matching deployment targets
|
||||
- Direct access to build caching infrastructure
|
||||
|
||||
#### Setting Up the Gitea Actions Runner
|
||||
|
||||
The nix-builder host is configured with a Gitea Actions self-hosted runner in `inventory.nix`. To complete the setup:
|
||||
|
||||
1. **Generate a Gitea Runner Token**:
|
||||
- Go to https://git.factory.uga.edu/UGA-Innovation-Factory/athenix/settings/actions/runners
|
||||
- Click "Create new Runner"
|
||||
- Copy the registration token
|
||||
|
||||
2. **Create the token file on nix-builder**:
|
||||
```bash
|
||||
ssh engr-ugaif@nix-builder
|
||||
echo "YOUR_TOKEN_HERE" | sudo tee /var/lib/gitea-runner-token > /dev/null
|
||||
sudo chmod 600 /var/lib/gitea-runner-token
|
||||
```
|
||||
|
||||
3. **Rebuild the system** to start the runner:
|
||||
```bash
|
||||
sudo nixos-rebuild switch --flake git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#nix-builder
|
||||
```
|
||||
|
||||
4. **Verify the runner is registered**:
|
||||
- Check https://git.factory.uga.edu/UGA-Innovation-Factory/athenix/settings/actions/runners
|
||||
- The runner should appear with the `nix-builder` label
|
||||
|
||||
The runner service is configured in the nix-builder device configuration and will automatically:
|
||||
- Register with the repository on first start
|
||||
- Use the `nix-builder` label for workflow targeting
|
||||
- Run as the `engr-ugaif` user
|
||||
- Store work in `/var/lib/gitea-runner`
|
||||
|
||||
### Troubleshooting CI Failures
|
||||
|
||||
If CI fails:
|
||||
|
||||
1. **Check the error logs** in the Gitea Actions tab
|
||||
2. **Run the same command locally** to reproduce the issue
|
||||
3. **Use `--show-trace`** for detailed error information
|
||||
4. **Verify formatting** with `nix fmt` if format check fails
|
||||
5. **Check for external dependencies** that might be unavailable
|
||||
|
||||
Common CI issues:
|
||||
|
||||
- **Flake check fails**: Configuration error in a host definition
|
||||
- **Format check fails**: Run `nix fmt` locally and commit changes
|
||||
- **Build fails**: Missing dependency or syntax error in Nix expressions
|
||||
- **Cache issues**: Usually self-resolving; can retry the workflow
|
||||
|
||||
## System Rebuilds
|
||||
|
||||
### From Local Directory
|
||||
|
||||
```bash
|
||||
# Rebuild current host from local directory
|
||||
sudo nixos-rebuild switch --flake .
|
||||
|
||||
# Rebuild specific host
|
||||
sudo nixos-rebuild switch --flake .#nix-laptop1
|
||||
|
||||
# Test without switching (temporary, doesn't persist reboot)
|
||||
sudo nixos-rebuild test --flake .#nix-laptop1
|
||||
|
||||
# Build a new generation without activating it
|
||||
sudo nixos-rebuild build --flake .
|
||||
```
|
||||
|
||||
### From GitHub
|
||||
|
||||
```bash
|
||||
# Rebuild from GitHub main branch
|
||||
sudo nixos-rebuild switch --flake git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git
|
||||
|
||||
# Use --impure for external user configurations with fetchGit
|
||||
sudo nixos-rebuild switch --flake git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git --impure
|
||||
|
||||
# Rebuild specific host from GitHub
|
||||
sudo nixos-rebuild switch --flake git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git#nix-laptop1
|
||||
```
|
||||
|
||||
### Boot into Previous Generation
|
||||
|
||||
If something breaks:
|
||||
|
||||
```bash
|
||||
# List generations
|
||||
sudo nixos-rebuild list-generations
|
||||
|
||||
# Rollback to previous generation
|
||||
sudo nixos-rebuild switch --rollback
|
||||
|
||||
# Or select specific generation at boot (GRUB menu)
|
||||
# Reboot and select "NixOS - Configuration X" from boot menu
|
||||
```
|
||||
|
||||
## Updating Dependencies
|
||||
|
||||
### Update All Inputs
|
||||
|
||||
```bash
|
||||
# Update all flake inputs (nixpkgs, home-manager, etc.)
|
||||
nix flake update
|
||||
|
||||
# Review changes
|
||||
git diff flake.lock
|
||||
|
||||
# Test the updates
|
||||
nix flake check
|
||||
|
||||
# Commit if successful
|
||||
git add flake.lock
|
||||
git commit -m "Update flake inputs"
|
||||
git push
|
||||
```
|
||||
|
||||
### Update Specific Input
|
||||
|
||||
```bash
|
||||
# Update only nixpkgs
|
||||
nix flake lock --update-input nixpkgs
|
||||
|
||||
# Update home-manager
|
||||
nix flake lock --update-input home-manager
|
||||
|
||||
# Update multiple specific inputs
|
||||
nix flake lock --update-input nixpkgs --update-input home-manager
|
||||
```
|
||||
|
||||
### Check for Security Updates
|
||||
|
||||
```bash
|
||||
# After updating, check for known vulnerabilities
|
||||
nix flake check
|
||||
|
||||
# Review nixpkgs changelog
|
||||
git log HEAD..nixpkgs/nixos-25.11 --oneline | head -20
|
||||
```
|
||||
|
||||
## Adding Packages
|
||||
|
||||
### System-Wide Packages by Type
|
||||
|
||||
Add packages based on system type:
|
||||
|
||||
**Desktop systems:**
|
||||
```bash
|
||||
# Edit sw/desktop/programs.nix
|
||||
vim sw/desktop/programs.nix
|
||||
```
|
||||
|
||||
**Tablet kiosks:**
|
||||
```bash
|
||||
# Edit sw/tablet-kiosk/programs.nix
|
||||
vim sw/tablet-kiosk/programs.nix
|
||||
```
|
||||
|
||||
**Headless systems:**
|
||||
```bash
|
||||
# Edit sw/headless/programs.nix
|
||||
vim sw/headless/programs.nix
|
||||
```
|
||||
|
||||
### Packages for Specific Hosts
|
||||
|
||||
Add to `athenix.sw.extraPackages` in `inventory.nix`:
|
||||
Edit `inventory.nix`:
|
||||
|
||||
```nix
|
||||
nix-laptop = {
|
||||
devices = 2;
|
||||
nix-surface = {
|
||||
devices = 3; # Creates nix-surface1, nix-surface2, nix-surface3
|
||||
overrides = {
|
||||
athenix.sw.extraPackages = with pkgs; [
|
||||
vim
|
||||
docker
|
||||
kubernetes-helm
|
||||
];
|
||||
athenix.sw.type = "tablet-kiosk";
|
||||
athenix.sw.kioskUrl = "https://dashboard.example.com";
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### User-Specific Packages
|
||||
|
||||
Add to user's home-manager configuration in their external `user.nix`:
|
||||
|
||||
```nix
|
||||
# In external user.nix
|
||||
home.packages = with pkgs; [
|
||||
ripgrep
|
||||
fd
|
||||
bat
|
||||
];
|
||||
```
|
||||
|
||||
### Search for Packages
|
||||
Test:
|
||||
|
||||
```bash
|
||||
# Search nixpkgs
|
||||
nix search nixpkgs firefox
|
||||
nix search nixpkgs python3
|
||||
|
||||
# Show package details
|
||||
nix eval nixpkgs#firefox.meta.description
|
||||
```
|
||||
|
||||
## Python Development
|
||||
|
||||
All systems include modern Python tools: `pixi` and `uv`.
|
||||
|
||||
### Pixi (Recommended for Projects)
|
||||
|
||||
```bash
|
||||
# Initialize new project
|
||||
pixi init my-project
|
||||
cd my-project
|
||||
|
||||
# Add dependencies
|
||||
pixi add pandas numpy matplotlib jupyter
|
||||
|
||||
# Run Python
|
||||
pixi run python
|
||||
|
||||
# Run Jupyter
|
||||
pixi run jupyter notebook
|
||||
|
||||
# Run scripts
|
||||
pixi run python script.py
|
||||
|
||||
# Shell with dependencies
|
||||
pixi shell
|
||||
```
|
||||
|
||||
### uv (Quick Virtual Environments)
|
||||
|
||||
```bash
|
||||
# Create virtual environment
|
||||
uv venv
|
||||
|
||||
# Activate
|
||||
source .venv/bin/activate
|
||||
|
||||
# Install packages
|
||||
uv pip install requests pandas
|
||||
|
||||
# Freeze requirements
|
||||
uv pip freeze > requirements.txt
|
||||
|
||||
# Install from requirements
|
||||
uv pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### System Python
|
||||
|
||||
Python development tools are configured in `sw/python.nix` and can be controlled via:
|
||||
|
||||
```nix
|
||||
athenix.sw.python.enable = true; # Default: enabled
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
### Code Style
|
||||
|
||||
- Run formatter before committing: `nix fmt`
|
||||
- Follow existing code structure and conventions
|
||||
- Add comments for complex logic
|
||||
- Use the `athenix.*` namespace for all custom options
|
||||
|
||||
### Testing Workflow
|
||||
|
||||
1. Make changes
|
||||
2. Run formatter: `nix fmt`
|
||||
3. Test locally: `nix flake check`
|
||||
4. Test specific builds if needed
|
||||
5. Commit changes
|
||||
6. Push to GitHub
|
||||
|
||||
```bash
|
||||
# Full workflow
|
||||
nix fmt
|
||||
nix flake check
|
||||
git add .
|
||||
git commit -m "Description of changes"
|
||||
git push
|
||||
nix build .#installer-iso-nix-surface1 -L
|
||||
```
|
||||
|
||||
### Documentation
|
||||
### Modifying Software Configuration
|
||||
|
||||
Update relevant documentation when making changes:
|
||||
|
||||
- `README.md` - Overview and quick start
|
||||
- `docs/INVENTORY.md` - Inventory configuration
|
||||
- `docs/NAMESPACE.md` - Configuration options
|
||||
- `USER_CONFIGURATION.md` - User management
|
||||
- `EXTERNAL_MODULES.md` - External modules
|
||||
|
||||
### Creating Issues
|
||||
|
||||
When reporting bugs or requesting features:
|
||||
|
||||
1. Check existing issues first
|
||||
2. Provide clear description
|
||||
3. Include error messages and traces
|
||||
4. Specify which hosts are affected
|
||||
5. Include `flake.lock` info if relevant
|
||||
|
||||
## Useful Commands
|
||||
Edit appropriate file in `sw/`:
|
||||
|
||||
```bash
|
||||
# Show all available outputs
|
||||
nix flake show
|
||||
# Desktop software
|
||||
vim sw/desktop/programs.nix
|
||||
|
||||
# Evaluate specific option
|
||||
nix eval .#nixosConfigurations.nix-laptop1.config.networking.hostName
|
||||
# Or for all systems
|
||||
vim sw/default.nix
|
||||
```
|
||||
|
||||
Use `athenix.sw.extraPackages` for host-specific additions:
|
||||
|
||||
```nix
|
||||
nix-laptop = {
|
||||
devices = 5;
|
||||
overrides.athenix.sw.extraPackages = with pkgs; [ special-tool ];
|
||||
};
|
||||
```
|
||||
|
||||
### Adding a System Type
|
||||
|
||||
Create new type in `sw/`:
|
||||
|
||||
```bash
|
||||
mkdir -p sw/my-type
|
||||
touch sw/my-type/{default.nix,programs.nix,services.nix}
|
||||
```
|
||||
|
||||
Then reference in `sw/default.nix`:
|
||||
|
||||
```nix
|
||||
{
|
||||
imports = [
|
||||
./my-type/default.nix
|
||||
# ... other types
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
### Using External Configurations
|
||||
|
||||
For user dotfiles:
|
||||
|
||||
```nix
|
||||
# users.nix
|
||||
athenix.users.myuser.external = builtins.fetchGit {
|
||||
url = "https://git.factory.uga.edu/username/dotfiles";
|
||||
rev = "abc123..."; # Pin to commit
|
||||
};
|
||||
```
|
||||
|
||||
For system config:
|
||||
|
||||
```nix
|
||||
# inventory.nix
|
||||
nix-lxc = {
|
||||
devices."server" = builtins.fetchGit {
|
||||
url = "https://git.factory.uga.edu/org/server-config";
|
||||
rev = "abc123...";
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### Updating Dependencies
|
||||
|
||||
```bash
|
||||
# Update all flake inputs
|
||||
nix flake update
|
||||
|
||||
# Update specific input
|
||||
nix flake update nixpkgs
|
||||
|
||||
# Show what changed
|
||||
git diff flake.lock
|
||||
|
||||
# Test after update
|
||||
nix flake check --show-trace
|
||||
|
||||
# If tests pass, commit
|
||||
git add flake.lock && git commit -m "Update dependencies"
|
||||
```
|
||||
|
||||
## Debugging
|
||||
|
||||
### Verbose Output
|
||||
|
||||
Get detailed error messages:
|
||||
|
||||
```bash
|
||||
# Show full error traces
|
||||
nix flake check --show-trace
|
||||
|
||||
# With maximum verbosity
|
||||
nix build .#installer-iso-nix-laptop1 -vvv
|
||||
|
||||
# Show build log
|
||||
nix build .#installer-iso-nix-laptop1 -L
|
||||
```
|
||||
|
||||
### Inspect Configuration
|
||||
|
||||
```bash
|
||||
# Evaluate configuration for specific host
|
||||
nix eval .#nixosConfigurations.nix-laptop1.config.athenix.sw --json
|
||||
|
||||
# Get all host names
|
||||
nix eval .#nixosConfigurations --apply builtins.attrNames
|
||||
|
||||
# Check specific option
|
||||
nix eval .#nixosConfigurations.nix-laptop1.config.users.users
|
||||
```
|
||||
|
||||
### Test Module Loading
|
||||
|
||||
```bash
|
||||
# Evaluate specific module
|
||||
nix-build -A nixosConfigurations.nix-laptop1.config.system.build.toplevel
|
||||
|
||||
# Or with flakes
|
||||
nix build .#nixosConfigurations.nix-laptop1.config.system.build.toplevel --verbose
|
||||
```
|
||||
|
||||
### Check Derivation Dependencies
|
||||
|
||||
```bash
|
||||
# Show what dependencies a build needs
|
||||
nix show-derivation .#installer-iso-nix-laptop1
|
||||
|
||||
# Or human-readable
|
||||
nix build .#installer-iso-nix-laptop1 --dry-run
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Errors
|
||||
|
||||
#### "Evaluation error"
|
||||
|
||||
```
|
||||
error: evaluation aborted with the following error message: '...'
|
||||
```
|
||||
|
||||
**Solution:** Check syntax in modified files. Use `nix fmt` and `nix flake check --show-trace`.
|
||||
|
||||
#### "Unknown variable" or "Option does not exist"
|
||||
|
||||
```
|
||||
error: The option `athenix.xyz' does not exist.
|
||||
```
|
||||
|
||||
**Solution:** Check NAMESPACE.md for available options. Options must be in `athenix.*` namespace.
|
||||
|
||||
#### "Hash mismatch" (for external modules)
|
||||
|
||||
```
|
||||
error: Hash mismatch in fetched input
|
||||
```
|
||||
|
||||
**Solution:** Update the pin. For `builtins.fetchGit`, use actual commit hash. Or:
|
||||
|
||||
```bash
|
||||
nix flake update
|
||||
```
|
||||
|
||||
#### Build runs out of memory
|
||||
|
||||
```bash
|
||||
# Reduce parallel jobs
|
||||
nix build . --max-jobs 1
|
||||
```
|
||||
|
||||
#### "No such file or directory" in build
|
||||
|
||||
```bash
|
||||
# Check path exists
|
||||
ls -la /path/to/file
|
||||
|
||||
# Or check relative to repo
|
||||
ls -la sw/my-file.nix
|
||||
```
|
||||
|
||||
### Helpful Diagnostics
|
||||
|
||||
```bash
|
||||
# List all hosts
|
||||
nix eval .#nixosConfigurations --apply builtins.attrNames
|
||||
|
||||
# Check flake metadata
|
||||
nix flake metadata
|
||||
# Show flake structure
|
||||
nix flake show | head -50
|
||||
|
||||
# Show evaluation trace
|
||||
nix eval --show-trace .#nixosConfigurations.nix-laptop1
|
||||
# Check Nix store size
|
||||
du -sh /nix/store
|
||||
|
||||
# Build and enter debug shell
|
||||
nix develop
|
||||
# List top space users in store
|
||||
nix store du --human-readable | head -20
|
||||
|
||||
# Clean up old generations
|
||||
nix-collect-garbage -d
|
||||
|
||||
# Optimize Nix store
|
||||
nix store optimise
|
||||
# Find store paths for a package
|
||||
nix store path-info -rS $(which some-package)
|
||||
```
|
||||
|
||||
### Getting Help
|
||||
|
||||
1. **Check documentation** - Review relevant doc file
|
||||
2. **Look at existing examples** - Check `inventory.nix` or `users.nix`
|
||||
3. **Search for similar patterns** - `grep -r "athenix.option" .`
|
||||
4. **Run tests locally** - `nix flake check --show-trace` with full output
|
||||
5. **Review git history** - `git log --patch -- filename.nix`
|
||||
|
||||
## See Also
|
||||
|
||||
- [README.md](../README.md) - Main documentation
|
||||
- [INVENTORY.md](INVENTORY.md) - Host inventory configuration
|
||||
- [BUILDING.md](BUILDING.md) - Building installation media
|
||||
- [BUILDING.md](BUILDING.md) - Building artifacts
|
||||
- [INVENTORY.md](INVENTORY.md) - Host configuration
|
||||
- [NAMESPACE.md](NAMESPACE.md) - Configuration options
|
||||
- [USER_CONFIGURATION.md](USER_CONFIGURATION.md) - User management
|
||||
- [EXTERNAL_MODULES.md](EXTERNAL_MODULES.md) - External modules
|
||||
- [README.md](../README.md) - Main documentation
|
||||
|
||||
Reference in New Issue
Block a user