init by ai
This commit is contained in:
269
README.md
Normal file
269
README.md
Normal file
@@ -0,0 +1,269 @@
|
||||
# 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 <your-repo> nix-config
|
||||
cd nix-config
|
||||
|
||||
# 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/
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
Reference in New Issue
Block a user