init by ai
This commit is contained in:
364
SETUP.md
Normal file
364
SETUP.md
Normal file
@@ -0,0 +1,364 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user