297 lines
6.0 KiB
Markdown
297 lines
6.0 KiB
Markdown
# Installation Guide
|
|
|
|
## First-Time Setup
|
|
|
|
### On macOS
|
|
|
|
#### 1. Install Nix (if not already installed)
|
|
|
|
```bash
|
|
sh <(curl -L https://nixos.org/nix/install)
|
|
```
|
|
|
|
#### 2. Enable Flakes
|
|
|
|
Create or edit `~/.config/nix/nix.conf`:
|
|
|
|
```bash
|
|
mkdir -p ~/.config/nix
|
|
cat <<EOF > ~/.config/nix/nix.conf
|
|
experimental-features = nix-command flakes
|
|
EOF
|
|
```
|
|
|
|
Restart your terminal or run:
|
|
```bash
|
|
. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
|
|
```
|
|
|
|
#### 3. Configure Your System
|
|
|
|
Edit the following files:
|
|
|
|
**In `flake.nix`:**
|
|
- Line 82-97: Replace `your-hostname` with your actual hostname (run `hostname` to find it)
|
|
- Line 94: Replace `your-username` with your actual username (run `whoami`)
|
|
|
|
**In `darwin/configuration.nix`:**
|
|
- Line 33-34: Set your hostname
|
|
- Line 45: Set your architecture:
|
|
- Apple Silicon (M1/M2/M3): `"aarch64-darwin"`
|
|
- Intel: `"x86_64-darwin"`
|
|
- Line 48-51: Set your username
|
|
|
|
**In `home-manager/home.nix`:**
|
|
- Line 30: Set your username
|
|
|
|
**In `home-manager/development.nix`** (optional):
|
|
- Uncomment lines for your git name and email
|
|
|
|
#### 4. Build and Apply
|
|
|
|
```bash
|
|
# Build the darwin configuration (first time)
|
|
nix build .#darwinConfigurations.YOUR-HOSTNAME.system --extra-experimental-features "nix-command flakes"
|
|
|
|
# Apply it
|
|
./result/sw/bin/darwin-rebuild switch --flake .#YOUR-HOSTNAME
|
|
```
|
|
|
|
After the first successful build, you can use:
|
|
```bash
|
|
darwin-rebuild switch --flake .#YOUR-HOSTNAME
|
|
```
|
|
|
|
#### 5. Reload Your Shell
|
|
|
|
Close and reopen your terminal, or source your shell config:
|
|
```bash
|
|
# For zsh:
|
|
source ~/.zshrc
|
|
|
|
# For fish:
|
|
source ~/.config/fish/config.fish
|
|
|
|
# For bash:
|
|
source ~/.bashrc
|
|
```
|
|
|
|
### On NixOS
|
|
|
|
#### 1. Clone This Repository
|
|
|
|
```bash
|
|
# As root or with sudo
|
|
cd /etc/nixos
|
|
git clone <your-repo-url> .
|
|
# Or copy your files to /etc/nixos
|
|
```
|
|
|
|
#### 2. Configure Your System
|
|
|
|
Edit the following files:
|
|
|
|
**In `flake.nix`:**
|
|
- Line 59-75: Replace `your-hostname` with your actual hostname
|
|
- Line 72: Replace `your-username` with your actual username
|
|
|
|
**In `nixos/configuration.nix`:**
|
|
- Line 38: Set your hostname
|
|
- Line 43-54: Configure your user account
|
|
- Uncomment line 47-51 if you want to set an initial password
|
|
|
|
**In `home-manager/home.nix`:**
|
|
- Line 30: Set your username
|
|
|
|
**In `home-manager/development.nix`** (optional):
|
|
- Uncomment lines for your git name and email
|
|
|
|
#### 3. Generate Hardware Configuration
|
|
|
|
If you haven't already:
|
|
```bash
|
|
sudo nixos-generate-config --show-hardware-config > nixos/hardware-configuration.nix
|
|
```
|
|
|
|
#### 4. Build and Apply
|
|
|
|
```bash
|
|
sudo nixos-rebuild switch --flake .#YOUR-HOSTNAME
|
|
```
|
|
|
|
#### 5. Reboot (optional but recommended)
|
|
|
|
```bash
|
|
sudo reboot
|
|
```
|
|
|
|
## Updating Your Configuration
|
|
|
|
### Update Flake Inputs (packages)
|
|
|
|
```bash
|
|
nix flake update
|
|
```
|
|
|
|
Then rebuild:
|
|
```bash
|
|
# macOS:
|
|
darwin-rebuild switch --flake .#YOUR-HOSTNAME
|
|
|
|
# NixOS:
|
|
sudo nixos-rebuild switch --flake .#YOUR-HOSTNAME
|
|
```
|
|
|
|
### Making Configuration Changes
|
|
|
|
1. Edit the relevant configuration files
|
|
2. Rebuild and switch:
|
|
|
|
```bash
|
|
# macOS:
|
|
darwin-rebuild switch --flake .
|
|
|
|
# NixOS:
|
|
sudo nixos-rebuild switch --flake .
|
|
```
|
|
|
|
### Testing Changes Before Applying
|
|
|
|
```bash
|
|
# macOS:
|
|
darwin-rebuild build --flake .
|
|
|
|
# NixOS:
|
|
sudo nixos-rebuild build --flake .
|
|
```
|
|
|
|
If the build succeeds, you can then apply with `switch`.
|
|
|
|
## Common Customizations
|
|
|
|
### Add User Packages
|
|
|
|
Edit `home-manager/common.nix`, `home-manager/development.nix`, or the platform-specific files:
|
|
|
|
```nix
|
|
home.packages = with pkgs; [
|
|
firefox
|
|
vscode
|
|
ripgrep
|
|
];
|
|
```
|
|
|
|
### Enable a Program
|
|
|
|
Most programs can be enabled via home-manager options:
|
|
|
|
```nix
|
|
programs.firefox.enable = true;
|
|
programs.git = {
|
|
enable = true;
|
|
userName = "Your Name";
|
|
userEmail = "you@example.com";
|
|
};
|
|
```
|
|
|
|
### Add System Packages
|
|
|
|
Edit `common.nix` or the platform-specific configuration:
|
|
|
|
```nix
|
|
environment.systemPackages = with pkgs; [
|
|
vim
|
|
wget
|
|
curl
|
|
];
|
|
```
|
|
|
|
### Customize Shell
|
|
|
|
Edit `home-manager/shell.nix` to configure bash, zsh, fish, or starship prompt.
|
|
|
|
### macOS System Defaults
|
|
|
|
Edit `darwin/configuration.nix` to customize macOS behavior (Dock, Finder, keyboard, etc.).
|
|
|
|
## Troubleshooting
|
|
|
|
### Build Fails with "experimental Nix feature 'flakes' is disabled"
|
|
|
|
Make sure you've enabled flakes in `~/.config/nix/nix.conf`:
|
|
```
|
|
experimental-features = nix-command flakes
|
|
```
|
|
|
|
### "error: collision between..."
|
|
|
|
This means two packages are trying to install the same files. Check for:
|
|
- Duplicate packages in system and home-manager configs
|
|
- Conflicting package versions
|
|
|
|
### macOS: "Could not find nix-darwin"
|
|
|
|
On first install, you need to build with the full path:
|
|
```bash
|
|
nix build .#darwinConfigurations.YOUR-HOSTNAME.system
|
|
./result/sw/bin/darwin-rebuild switch --flake .
|
|
```
|
|
|
|
### Home Manager File Conflicts
|
|
|
|
If home-manager tries to manage files that already exist, back them up:
|
|
```bash
|
|
# Create backups of existing files
|
|
for file in ~/.bashrc ~/.zshrc ~/.config/fish/config.fish; do
|
|
[ -f "$file" ] && mv "$file" "$file.backup"
|
|
done
|
|
```
|
|
|
|
Or use the backup flag:
|
|
```bash
|
|
home-manager switch --flake . --backup-extension .backup
|
|
```
|
|
|
|
### Can't Find Your Hostname
|
|
|
|
```bash
|
|
# macOS and Linux:
|
|
hostname
|
|
|
|
# If it's not what you expect, you can change it:
|
|
# macOS (temporarily):
|
|
sudo scutil --set HostName your-new-hostname
|
|
|
|
# NixOS: Set in configuration.nix
|
|
```
|
|
|
|
### Rollback to Previous Generation
|
|
|
|
If a new configuration breaks something:
|
|
|
|
```bash
|
|
# macOS:
|
|
darwin-rebuild --rollback
|
|
|
|
# NixOS:
|
|
sudo nixos-rebuild --rollback
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
After installation:
|
|
|
|
1. **Customize your configuration** - Edit the home-manager modules to suit your workflow
|
|
2. **Add your development tools** - Uncomment languages/tools you need in `development.nix`
|
|
3. **Configure Git** - Set your name and email in `development.nix`
|
|
4. **Set up shell** - Choose your preferred shell and customize in `shell.nix`
|
|
5. **Explore options** - Check out [Home Manager options](https://nix-community.github.io/home-manager/options.html)
|
|
|
|
## Getting Help
|
|
|
|
- [NixOS Discourse](https://discourse.nixos.org/)
|
|
- [Nix Discord](https://discord.gg/RbvHtGa)
|
|
- [r/NixOS](https://www.reddit.com/r/NixOS/)
|
|
- [Nix Documentation](https://nixos.org/learn.html)
|
|
|