365 lines
7.1 KiB
Markdown
365 lines
7.1 KiB
Markdown
# Setup Guide - Step by Step
|
|
|
|
This guide walks you through setting up your portable NixOS configuration from scratch.
|
|
|
|
## Prerequisites
|
|
|
|
- **For new NixOS machines**: NixOS ISO boot media
|
|
- **For existing NixOS**: SSH access or local terminal
|
|
- **For non-NixOS**: curl, bash
|
|
|
|
## Phase 1: Initialize Secrets (One-time)
|
|
|
|
### Generate Your Age Key
|
|
|
|
```bash
|
|
# Create age directory
|
|
mkdir -p ~/.config/sops/age
|
|
|
|
# Generate keypair
|
|
age-keygen -o -f ~/.config/sops/age/keys.txt
|
|
|
|
# Extract public key
|
|
age-keygen -y ~/.config/sops/age/keys.txt
|
|
# Output: age1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
|
```
|
|
|
|
### Update Encryption Config
|
|
|
|
Edit `secrets/.sops.yaml`:
|
|
|
|
```yaml
|
|
keys:
|
|
- &users |
|
|
- -----BEGIN AGE PUBLIC KEY-----
|
|
age1YOUR_KEY_HERE_FROM_ABOVE
|
|
-----END AGE PUBLIC KEY-----
|
|
```
|
|
|
|
### Encrypt Your Secrets
|
|
|
|
```bash
|
|
# First install sops and age
|
|
nix shell nixpkgs#sops nixpkgs#age
|
|
|
|
# Edit secrets
|
|
sops secrets/secrets.yaml
|
|
|
|
# Add your SSH keys, API keys, etc.
|
|
# File will be encrypted automatically on save
|
|
```
|
|
|
|
## Phase 2: Personalize Configuration
|
|
|
|
### Step 1: Update flake.nix
|
|
|
|
Replace `youruser` with your actual username:
|
|
|
|
```bash
|
|
sed -i 's/youruser/myusername/g' flake.nix
|
|
sed -i 's/youruser/myusername/g' home/default.nix
|
|
```
|
|
|
|
### Step 2: Configure Your Laptop Host
|
|
|
|
Edit `hosts/laptop/default.nix`:
|
|
|
|
```nix
|
|
{
|
|
networking.hostName = "mylaptop"; # Change this
|
|
|
|
disko.devices = {
|
|
disk.main = {
|
|
type = "disk";
|
|
device = "/dev/sda"; # Run 'lsblk' to find your disk
|
|
|
|
# For NVMe: device = "/dev/nvme0n1";
|
|
# For SATA: device = "/dev/sda";
|
|
# For RAID: add multiple disks
|
|
};
|
|
# ... rest stays the same
|
|
};
|
|
|
|
# Enable tools you want
|
|
custom.development.enable = true;
|
|
custom.development.languages = [ "rust" "python" "nodejs" ];
|
|
}
|
|
```
|
|
|
|
### Step 3: Customize Home Configuration
|
|
|
|
Edit `home/default.nix`:
|
|
|
|
```nix
|
|
home.username = "myusername"; # Match your username
|
|
home.homeDirectory = "/home/myusername";
|
|
```
|
|
|
|
Edit `home/modules/git.nix`:
|
|
|
|
```nix
|
|
programs.git = {
|
|
enable = true;
|
|
userName = "Your Real Name";
|
|
userEmail = "you@example.com";
|
|
# ... rest of config
|
|
};
|
|
```
|
|
|
|
## Phase 3: Deploy Strategy Based on Your Situation
|
|
|
|
### Scenario A: Deploying to Existing NixOS
|
|
|
|
```bash
|
|
# 1. Clone repo to your home directory
|
|
git clone <your-repo> ~/nix-config
|
|
cd ~/nix-config
|
|
|
|
# 2. Test the configuration (dry-run)
|
|
sudo nixos-rebuild test --flake .#laptop
|
|
|
|
# 3. If tests pass, apply the configuration
|
|
sudo nixos-rebuild switch --flake .#laptop
|
|
|
|
# 4. Also apply home-manager
|
|
home-manager switch --flake .#myusername@linux
|
|
```
|
|
|
|
### Scenario B: Fresh NixOS Installation (with Auto-Partitioning)
|
|
|
|
**On a machine running the NixOS ISO:**
|
|
|
|
```bash
|
|
# 1. Boot NixOS live ISO
|
|
# 2. Connect to network (if needed)
|
|
# 3. Clone the repo (copy files via USB or git clone)
|
|
|
|
nix flake update # Update to latest packages
|
|
|
|
# Option 1: Use disko directly
|
|
sudo nix run github:nix-community/disko -- \
|
|
--mode zap \
|
|
--flake .#laptop
|
|
|
|
# Option 2: Use nixos-anywhere from another machine
|
|
nix run github:nix-community/nixos-anywhere -- \
|
|
--flake .#laptop \
|
|
--build-on-remote \
|
|
root@<your-target-ip>
|
|
|
|
# Option 3: Manual installation
|
|
# 1. Partition disk manually: `sudo fdisk /dev/sda`
|
|
# 2. Mount partitions: `sudo mount /dev/sda2 /mnt && sudo mount /dev/sda1 /mnt/boot`
|
|
# 3. Generate initial config: `sudo nixos-generate-config --root /mnt`
|
|
# 4. Copy your flake.nix to /mnt/etc/nixos/flake.nix
|
|
# 5. Install: `sudo nixos-install --flake .#laptop`
|
|
```
|
|
|
|
### Scenario C: Non-NixOS Machine (Linux/macOS)
|
|
|
|
```bash
|
|
# 1. Install nix (if not present)
|
|
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | \
|
|
sh -s -- install
|
|
|
|
# 2. Clone and apply home-manager
|
|
git clone <your-repo> ~/nix-config
|
|
cd ~/nix-config
|
|
|
|
# 3. Install home-manager
|
|
nix run home-manager/release-24.11 -- init --switch
|
|
|
|
# 4. Apply your config
|
|
home-manager switch --flake .#myusername@linux
|
|
```
|
|
|
|
## Phase 4: Verify Everything Works
|
|
|
|
```bash
|
|
# Check flake validity
|
|
nix flake check
|
|
|
|
# Inspect what will be built
|
|
nix flake show
|
|
|
|
# Check secrets decryption (if using sops)
|
|
sops -d secrets/secrets.yaml
|
|
|
|
# Verify home-manager config
|
|
home-manager packages 2>&1 | head -20
|
|
|
|
# Verify NixOS config (on NixOS machines)
|
|
sudo nixos-option system.nixos.version
|
|
```
|
|
|
|
## Phase 5: Enable Advanced Features (Optional)
|
|
|
|
### Using Unstable Packages
|
|
|
|
In any module, use unstable versions:
|
|
|
|
```nix
|
|
# In home/modules/dev-tools.nix
|
|
home.packages = with pkgs; [
|
|
stable_package
|
|
pkgs-unstable.latest_package
|
|
];
|
|
```
|
|
|
|
### Adding Secrets to NixOS Config
|
|
|
|
Create `nixos/modules/secrets.nix`:
|
|
|
|
```nix
|
|
{ config, sops-nix, ... }:
|
|
|
|
{
|
|
imports = [ sops-nix.nixosModules.sops ];
|
|
|
|
sops.defaultSopsFile = ./secrets/secrets.yaml;
|
|
sops.age.keyFile = "/home/youruser/.config/sops/age/keys.txt";
|
|
|
|
sops.secrets."ssh/github_key" = {
|
|
owner = "youruser";
|
|
group = "users";
|
|
mode = "0600";
|
|
};
|
|
|
|
# Use in config:
|
|
# environment.variables.GITHUB_SSH_KEY = "${config.sops.secrets."ssh/github_key".path}";
|
|
}
|
|
```
|
|
|
|
### Custom Per-Language Development Shells
|
|
|
|
Create `.envrc`:
|
|
|
|
```bash
|
|
use flake
|
|
|
|
# Per-project overrides
|
|
layout python
|
|
```
|
|
|
|
Then:
|
|
|
|
```bash
|
|
direnv allow
|
|
```
|
|
|
|
## Common Customizations
|
|
|
|
### Add a New Programming Language
|
|
|
|
Edit `hosts/laptop/default.nix`:
|
|
|
|
```nix
|
|
custom.development.languages = [ "rust" "python" "nodejs" "go" ];
|
|
```
|
|
|
|
Supported: `rust`, `python`, `nodejs`, `go`, `ruby` (in `nixos/modules/development.nix`)
|
|
|
|
### Change Default Shell
|
|
|
|
Edit `nixos/modules/shell.nix`:
|
|
|
|
```nix
|
|
custom.shell.defaultShell = "fish"; # or "bash"
|
|
```
|
|
|
|
### Add System Packages
|
|
|
|
Edit `nixos/default.nix`:
|
|
|
|
```nix
|
|
environment.systemPackages = with pkgs; [
|
|
# ... existing packages
|
|
mynewtool
|
|
];
|
|
```
|
|
|
|
### Add User Home Packages
|
|
|
|
Edit `home/default.nix`:
|
|
|
|
```nix
|
|
home.packages = with pkgs; [
|
|
# ... existing packages
|
|
mynewtool
|
|
];
|
|
```
|
|
|
|
## Rebuilding After Changes
|
|
|
|
```bash
|
|
# After modifying any config:
|
|
|
|
# 1. Check for syntax errors
|
|
nix flake check
|
|
|
|
# 2. Test without committing
|
|
sudo nixos-rebuild test --flake .#laptop
|
|
|
|
# 3. If happy, switch to new config
|
|
sudo nixos-rebuild switch --flake .#laptop
|
|
|
|
# 4. Update lockfile with latest packages
|
|
nix flake update
|
|
|
|
# 5. Commit changes
|
|
git add -A
|
|
git commit -m "Update: <description of changes>"
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### "Bad substituter" errors
|
|
|
|
```bash
|
|
# Clear cache
|
|
nix store gc
|
|
|
|
# Update flake
|
|
nix flake update
|
|
|
|
# Rebuild
|
|
sudo nixos-rebuild switch --flake .#laptop
|
|
```
|
|
|
|
### Secrets not decrypting
|
|
|
|
```bash
|
|
# Verify key exists
|
|
ls ~/.config/sops/age/keys.txt
|
|
|
|
# Check sops can find the key
|
|
sops -d secrets/secrets.yaml
|
|
|
|
# Verify .sops.yaml has correct key
|
|
cat secrets/.sops.yaml
|
|
```
|
|
|
|
### Home-manager conflicts with existing config
|
|
|
|
```bash
|
|
# Move old config
|
|
mv ~/.bashrc ~/.bashrc.bak
|
|
mv ~/.zshrc ~/.zshrc.bak
|
|
|
|
# Apply home-manager
|
|
home-manager switch --flake .#myusername@linux
|
|
|
|
# Merge manually if needed
|
|
cat ~/.bashrc.bak >> ~/.bashrc
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
1. **Commit to git**: Version your config
|
|
2. **Add to GitHub**: Make it portable between machines
|
|
3. **Customize modules**: Create your own in `nixos/modules/`
|
|
4. **Backup secrets**: Safely store your age key
|
|
5. **Document changes**: Update README as you customize
|
|
|
|
See README.md for advanced usage patterns.
|