268 lines
6.5 KiB
Markdown
268 lines
6.5 KiB
Markdown
# Portable NixOS Configuration
|
|
|
|
A production-ready, modular NixOS + Home Manager setup with automatic disk
|
|
partitioning, secrets management, and support for both new and existing
|
|
systems.
|
|
|
|
## Features
|
|
|
|
- ✅ **Modular**: Configure system and home separately or together
|
|
- ✅ **Portable**: Works on new machines, existing NixOS, or non-NixOS (home-manager only)
|
|
- ✅ **Auto-partitioning**: Disko handles disk setup automatically
|
|
- ✅ **Secrets**: sops-nix for encrypted, portable secrets
|
|
- ✅ **Unstable packages**: Mix stable and unstable nixpkgs
|
|
- ✅ **Single command**: Deploy entire system with one command
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
nix-config/
|
|
├── flake.nix # Main entry point (inputs + outputs)
|
|
├── flake.lock # Pinned versions
|
|
├── hosts/ # Per-machine configs
|
|
│ ├── laptop/default.nix # Machine-specific settings
|
|
│ └── server/default.nix
|
|
├── nixos/ # Shared NixOS modules
|
|
│ ├── default.nix
|
|
│ └── modules/
|
|
│ ├── system.nix # User creation, sudo
|
|
│ ├── development.nix # Languages, tools
|
|
│ └── shell.nix # Shell config
|
|
├── home/ # Shared Home Manager modules
|
|
│ ├── default.nix
|
|
│ └── modules/
|
|
│ ├── shell.nix # Zsh + direnv
|
|
│ ├── editor.nix # Neovim/VSCode
|
|
│ ├── git.nix # Git config
|
|
│ └── dev-tools.nix # tmux, etc
|
|
├── secrets/
|
|
│ ├── .sops.yaml # Encryption config
|
|
│ └── secrets.yaml # Encrypted secrets
|
|
└── README.md
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
### 1. Initial Setup
|
|
|
|
```bash
|
|
# Clone repository
|
|
git clone <repo-url> nix-los
|
|
cd nix-los
|
|
|
|
# Generate age keypair (one-time)
|
|
age-keygen -o -f ~/.config/sops/age/keys.txt
|
|
|
|
# Update .sops.yaml with your public key
|
|
age-keygen -y ~/.config/sops/age/keys.txt
|
|
# Copy the output and update secrets/.sops.yaml
|
|
```
|
|
|
|
### 2. Personalize Your Config
|
|
|
|
Edit these files to match your setup:
|
|
|
|
**flake.nix:**
|
|
- Change `youruser` to your actual username (3 places)
|
|
|
|
**hosts/laptop/default.nix:**
|
|
- Set `networking.hostName`
|
|
- Verify disk device (change `/dev/sda` if needed)
|
|
|
|
**home/default.nix & home/modules/git.nix:**
|
|
- Set your username and email
|
|
- Customize home packages
|
|
|
|
**secrets/secrets.yaml:**
|
|
- Add your SSH keys, API tokens, passwords
|
|
|
|
### 3. Deploy to Existing NixOS
|
|
|
|
```bash
|
|
# Rebuild the entire system
|
|
sudo nixos-rebuild switch --flake .#laptop
|
|
|
|
# Or, just update home-manager
|
|
home-manager switch --flake .#youruser@linux
|
|
```
|
|
|
|
### 4. Deploy to New Machine (ISO Install)
|
|
|
|
```bash
|
|
# Boot NixOS live ISO, then:
|
|
# (Option A) Manual installation
|
|
sudo nix run github:nix-community/disko -- --mode zap --flake .#laptop
|
|
|
|
# (Option B) Automated with nixos-anywhere (from another machine)
|
|
nix run github:nix-community/nixos-anywhere -- --flake .#laptop root@192.168.1.100
|
|
|
|
# (Option C) One-liner installer
|
|
nix run .#installer -- laptop
|
|
```
|
|
|
|
### 5. Non-NixOS Machine (Home Manager Only)
|
|
|
|
```bash
|
|
# Install home-manager and apply config
|
|
home-manager switch --flake .#youruser@linux
|
|
|
|
# Or use the installer script
|
|
nix run .#installer -- laptop
|
|
```
|
|
|
|
## Usage Patterns
|
|
|
|
### Rebuild After Changes
|
|
|
|
```bash
|
|
# System + home
|
|
sudo nixos-rebuild switch --flake .#laptop
|
|
|
|
# Just home-manager
|
|
home-manager switch --flake .#youruser@linux
|
|
|
|
# Dry-run to see what changes
|
|
sudo nixos-rebuild test --flake .#laptop
|
|
```
|
|
|
|
### Manage Secrets
|
|
|
|
```bash
|
|
# Edit encrypted secrets (requires age key)
|
|
sops secrets/secrets.yaml
|
|
|
|
# Reference in NixOS config:
|
|
# sops.secrets."ssh/github_key".owner = "youruser";
|
|
# sops.secrets."ssh/github_key".path = "/home/youruser/.ssh/github_key";
|
|
|
|
# Access in shell:
|
|
# cat ${config.sops.secrets."ssh/github_key".path}
|
|
```
|
|
|
|
### Enable/Disable Features
|
|
|
|
Edit host config (e.g., `hosts/laptop/default.nix`):
|
|
|
|
```nix
|
|
# Enable development tools for specific languages
|
|
custom.development.enable = true;
|
|
custom.development.languages = [ "rust" "python" "nodejs" ];
|
|
|
|
# Disable specific modules
|
|
custom.shell.enable = false;
|
|
```
|
|
|
|
### Add New Modules
|
|
|
|
Create `nixos/modules/myfeature.nix`:
|
|
|
|
```nix
|
|
{ config, lib, pkgs, ... }:
|
|
|
|
{
|
|
options.custom.myfeature = {
|
|
enable = lib.mkEnableOption "My feature";
|
|
};
|
|
|
|
config = lib.mkIf config.custom.myfeature.enable {
|
|
# Your config here
|
|
};
|
|
}
|
|
```
|
|
|
|
Then import in `nixos/default.nix`:
|
|
```nix
|
|
imports = [ ./modules/myfeature.nix ];
|
|
```
|
|
|
|
### Development Shell
|
|
|
|
```bash
|
|
# Load dev environment
|
|
nix flake show
|
|
|
|
# Enter dev shell with all tools
|
|
nix develop
|
|
```
|
|
|
|
## Multi-Machine Setup
|
|
|
|
To support multiple machines:
|
|
|
|
1. Create new host:
|
|
```bash
|
|
mkdir -p hosts/newhost
|
|
cp hosts/laptop/default.nix hosts/newhost/default.nix
|
|
```
|
|
|
|
2. Edit `flake.nix` and add:
|
|
```nix
|
|
newhost = nixpkgs.lib.nixosSystem {
|
|
inherit system;
|
|
specialArgs = { inherit sops-nix disko; pkgs-unstable = pkgs-unstable; };
|
|
modules = [
|
|
overlayUnstable
|
|
sops-nix.nixosModules.sops
|
|
disko.nixosModules.disko
|
|
./hosts/newhost/default.nix
|
|
./nixos/default.nix
|
|
home-manager.nixosModules.home-manager
|
|
{ home-manager.users.youruser = import ./home/default.nix; }
|
|
];
|
|
};
|
|
```
|
|
|
|
3. Deploy:
|
|
```bash
|
|
sudo nixos-rebuild switch --flake .#newhost
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Secrets decryption fails
|
|
```bash
|
|
# Check your age key exists
|
|
ls ~/.config/sops/age/keys.txt
|
|
|
|
# Verify sops config
|
|
sops -d secrets/secrets.yaml
|
|
|
|
# Regenerate .sops.yaml with your key
|
|
age-keygen -y ~/.config/sops/age/keys.txt
|
|
```
|
|
|
|
### Disko disk errors
|
|
```bash
|
|
# List available disks
|
|
lsblk
|
|
|
|
# Manually run disko (test mode)
|
|
sudo nix run github:nix-community/disko -- --mode doit --flake .#laptop
|
|
```
|
|
|
|
### Home-manager import errors
|
|
```bash
|
|
# Check flake validity
|
|
nix flake check
|
|
|
|
# Validate syntax
|
|
nix flake show
|
|
```
|
|
|
|
## Resources
|
|
|
|
- [NixOS Manual](https://nixos.org/manual/nixos/stable/)
|
|
- [Home Manager](https://nix-community.github.io/home-manager/)
|
|
- [sops-nix Documentation](https://github.com/mic92/sops-nix)
|
|
- [disko](https://github.com/nix-community/disko)
|
|
- [Flakes Guide](https://nix.dev/manual/nix/latest/command-ref/new-cli/nix3-flake.html)
|
|
|
|
## Tips for Portability
|
|
|
|
1. **Keep secrets encrypted**: Always use sops, never commit plain text secrets
|
|
2. **Machine-specific overrides**: Use `lib.mkDefault` in shared modules
|
|
3. **Conditionally enable features**: Use `options` + `config = mkIf cfg.enable`
|
|
4. **Test before deploying**: Use `nixos-rebuild test` or `home-manager build`
|
|
5. **Version your flake**: Commit `flake.lock` for reproducibility
|
|
6. **Separate concerns**: System settings → nixos/, User env → home/
|