Update README + AGENTS.md
This commit is contained in:
Melvin Ragusa
252
AGENTS.md
252
AGENTS.md
@@ -1,199 +1,127 @@
|
||||
# AGENTS.md - NixOS Configuration Guidelines
|
||||
# AGENTS.md - NixOS Configuration Repository
|
||||
|
||||
Guidelines for AI agents working with this NixOS flake-based configuration.
|
||||
This file provides guidance for AI coding assistants working on this NixOS configuration.
|
||||
|
||||
## Project Overview
|
||||
## Repository Overview
|
||||
|
||||
Modular NixOS configuration for a desktop workstation using Nix flakes.
|
||||
This is a NixOS system configuration for a desktop named "atlas". It uses flakes, modular organization, and includes customizations for gaming, development, and daily desktop use.
|
||||
|
||||
**Tech Stack:** NixOS, Nix Flakes, Fish shell, Wayland (Niri), AMD GPU
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
nixos/
|
||||
├── flake.nix # Flake inputs and outputs
|
||||
├── configuration.nix # Main config (imports all modules)
|
||||
├── hardware-configuration.nix # Auto-generated (don't edit)
|
||||
├── overlays/ # Custom nixpkgs overlays
|
||||
│ └── limine-install-patched.py # Patched Limine install script
|
||||
└── modules/
|
||||
├── apps.nix # User applications
|
||||
├── desktop.nix # Wayland, portals, polkit
|
||||
├── dev.nix # Docker, dev tools, languages
|
||||
├── gaming.nix # Steam, Gamemode, Wine
|
||||
├── gpu-amd.nix # AMD GPU drivers
|
||||
├── limine-custom-labels.nix # Custom boot entry labels
|
||||
├── shell.nix # Fish shell config
|
||||
├── theming.nix # Fonts, themes, cursors
|
||||
└── ... # Other modules
|
||||
```
|
||||
|
||||
## Build Commands
|
||||
## Build/Validation Commands
|
||||
|
||||
```bash
|
||||
# Test configuration without switching (recommended first)
|
||||
sudo nixos-rebuild test --flake .#nixos
|
||||
|
||||
# Switch to new configuration
|
||||
sudo nixos-rebuild switch --flake .#nixos
|
||||
|
||||
# Quick syntax validation
|
||||
# Validate Nix syntax and build configuration
|
||||
nix flake check
|
||||
|
||||
# Update all flake inputs
|
||||
nix flake update
|
||||
# Build the configuration (dry-run, doesn't activate)
|
||||
nixos-rebuild dry-build --flake .
|
||||
|
||||
# Garbage collection
|
||||
sudo nix-collect-garbage --delete-older-than 14d
|
||||
# Format all .nix files with nixfmt
|
||||
nixfmt **/*.nix
|
||||
|
||||
# Check for common issues
|
||||
nixos-rebuild dry-activate --flake .
|
||||
```
|
||||
|
||||
## Code Style Guidelines
|
||||
|
||||
### File Structure
|
||||
|
||||
Each module follows this pattern:
|
||||
### File Organization
|
||||
- Entry point: `configuration.nix`
|
||||
- Flake definition: `flake.nix`
|
||||
- Modular structure under `modules/` organized by category:
|
||||
- `core/` - Boot, system, networking, users, localization
|
||||
- `hardware/` - GPU, audio, storage, power management
|
||||
- `desktop/` - Window manager, apps, theming, portals
|
||||
- `services/` - System services (avahi, printing, navidrome)
|
||||
- `dev/` - Development tools, docker, shells
|
||||
- `gaming/` - Steam, wine, gamemode
|
||||
|
||||
### Module Pattern
|
||||
Each module follows this structure:
|
||||
```nix
|
||||
# modules/example.nix
|
||||
# Brief description of what this module does
|
||||
# modules/<category>/<name>.nix
|
||||
# Brief description of what this module configures
|
||||
{
|
||||
config,
|
||||
pkgs,
|
||||
lib,
|
||||
inputs, # Only if using flake inputs
|
||||
username, # Custom arg passed from flake
|
||||
...
|
||||
}:
|
||||
|
||||
{
|
||||
# Module content here
|
||||
# Configuration options here
|
||||
}
|
||||
```
|
||||
|
||||
### Formatting
|
||||
|
||||
- **Formatter**: `nixfmt`
|
||||
- **Indentation**: 2 spaces (no tabs)
|
||||
- **Line length**: ~100 chars, break long lists
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
- **Files**: `kebab-case.nix` (e.g., `gpu-amd.nix`)
|
||||
- **Options**: NixOS convention, camelCase (e.g., `extraGroups`)
|
||||
|
||||
### Comments & Headers
|
||||
|
||||
- Major sections: `# ═══ SECTION NAME ═══` (full line of `═`)
|
||||
- Subsections: `# ─── Subsection ───` (full line of `─`)
|
||||
- Inline comments for non-obvious settings
|
||||
|
||||
### Package Lists & Attribute Sets
|
||||
|
||||
### Imports Pattern
|
||||
`default.nix` files should only contain imports:
|
||||
```nix
|
||||
environment.systemPackages = with pkgs; [
|
||||
# Category header
|
||||
package1
|
||||
package2
|
||||
];
|
||||
|
||||
# Short sets inline: { enable = true; }
|
||||
# Multi-line with indentation:
|
||||
services.example = {
|
||||
enable = true;
|
||||
settings.Option = "value";
|
||||
};
|
||||
```
|
||||
|
||||
## Important Notes
|
||||
|
||||
1. **hardware-configuration.nix**: Auto-generated, never edit manually
|
||||
2. **Username**: `pinj` - used throughout the config
|
||||
3. **User groups**: Distributed across modules via `users.users.pinj.extraGroups`
|
||||
4. **GUI apps**: Managed via `nix profile`, not system packages
|
||||
5. **Unfree packages**: Enabled in `configuration.nix`
|
||||
6. **State version**: `26.05` - don't change unless migrating
|
||||
|
||||
## Flake Inputs
|
||||
|
||||
| Input | Purpose |
|
||||
|-------|---------|
|
||||
| `nixpkgs` | NixOS unstable channel |
|
||||
| `nix-cachyos-kernel` | CachyOS optimized kernel |
|
||||
| `noctalia` | Desktop shell |
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Adding a New Module
|
||||
|
||||
1. Create `modules/newmodule.nix` with standard header
|
||||
2. Add import to `configuration.nix`
|
||||
3. Test with `sudo nixos-rebuild test --flake .#nixos`
|
||||
|
||||
### Adding System Packages
|
||||
|
||||
Add to the relevant module's `environment.systemPackages`:
|
||||
```nix
|
||||
environment.systemPackages = with pkgs; [
|
||||
newpackage
|
||||
];
|
||||
```
|
||||
|
||||
### Adding User to Group
|
||||
|
||||
```nix
|
||||
users.users.pinj.extraGroups = [ "groupname" ];
|
||||
```
|
||||
|
||||
### Using Flake Inputs
|
||||
|
||||
```nix
|
||||
# Add inputs to module arguments
|
||||
{ config, pkgs, inputs, lib, ... }:
|
||||
|
||||
# modules/<category>/default.nix
|
||||
{
|
||||
environment.systemPackages = [
|
||||
inputs.flakename.packages.${pkgs.system}.default
|
||||
imports = [
|
||||
./boot.nix
|
||||
./system.nix
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
### Adding User GUI Apps
|
||||
### Formatting Rules
|
||||
- Use 2-space indentation
|
||||
- No tabs
|
||||
- Keep lines under 100 characters when possible
|
||||
- Add blank lines between logical sections
|
||||
- Use descriptive comments with `# Description` format
|
||||
|
||||
### Naming Conventions
|
||||
- Module files: descriptive lowercase with hyphens (e.g., `gpu-amd.nix`)
|
||||
- Use `username` variable from flake for user-specific paths
|
||||
- Use `lib.mkIf` for conditional configuration
|
||||
- Use `lib.mkDefault` for values that can be overridden
|
||||
|
||||
### Input Handling
|
||||
- Pass `inputs` from flake when accessing external packages
|
||||
- Access input packages via: `inputs.<name>.packages.${pkgs.stdenv.hostPlatform.system}.default`
|
||||
- Use `pkgs.stdenv.hostPlatform.system` for system-specific packages
|
||||
|
||||
### Special Files
|
||||
- `hardware-configuration.nix` - Generated by nixos-generate-config, DO NOT EDIT
|
||||
- Scripts in `scripts/` are bash installers (not part of NixOS config)
|
||||
- Overlays contain patched Python scripts
|
||||
|
||||
### Security Notes
|
||||
- Never commit secrets, API keys, or tokens
|
||||
- Sensitive files are in `.gitignore`
|
||||
- Use proper LUKS encryption for swap and root partitions
|
||||
- Secure Boot is enabled with custom Limine patches
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Adding a New Module
|
||||
1. Create file in appropriate `modules/<category>/` subdirectory
|
||||
2. Add to the category's `default.nix` imports
|
||||
3. Follow existing module structure and formatting
|
||||
4. Add brief header comment describing purpose
|
||||
|
||||
### Adding a Package
|
||||
- System packages: add to `environment.systemPackages` in appropriate module
|
||||
- User packages: prefer adding to system packages for shared use
|
||||
- Flake packages: access via inputs with proper system attribute
|
||||
|
||||
### Testing Changes
|
||||
```bash
|
||||
nix profile install nixpkgs#packagename
|
||||
# Before committing, always verify syntax
|
||||
nix flake check
|
||||
|
||||
# Build to catch evaluation errors
|
||||
nixos-rebuild dry-build --flake .
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
## Dependencies
|
||||
|
||||
- NixOS fails builds on errors - this is the primary validation
|
||||
- Always test with `nixos-rebuild test` before `switch`
|
||||
- Use `nix flake check` for quick syntax validation
|
||||
|
||||
## Custom Limine Boot Labels (MAINTENANCE REQUIRED)
|
||||
|
||||
**Files:**
|
||||
- `modules/limine-custom-labels.nix` - Module that applies the patch
|
||||
- `overlays/limine-install-patched.py` - Patched install script
|
||||
|
||||
**What it does:**
|
||||
- Changes boot entries from "Generation XYZ" to "Linux 6.X.Y-cachyos - Generation XYZ"
|
||||
- Removes "default profile" from group name (shows just "NixOS")
|
||||
- Shows kernel version in all entries including specialisations
|
||||
|
||||
**How it works:**
|
||||
The module imports the standard Limine module but overrides `system.build.installBootLoader`
|
||||
with a patched Python script that extracts kernel version from the kernel path.
|
||||
|
||||
**Maintenance burden:**
|
||||
- **HIGH** - This will break when nixpkgs updates the limine module
|
||||
- Check after every `nix flake update` by running `nixos-rebuild test`
|
||||
- If it breaks, compare `overlays/limine-install-patched.py` with the upstream
|
||||
`nixos/modules/system/boot/loader/limine/limine-install.py` in nixpkgs
|
||||
- Typical breakage: line number changes, function signature changes, new bootspec fields
|
||||
|
||||
**To fix breakage:**
|
||||
1. Check current upstream script: https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/system/boot/loader/limine/limine-install.py
|
||||
2. Identify the changes needed
|
||||
3. Re-apply the two key modifications:
|
||||
- Line ~550: Change `group_name = 'default profile'...` to `group_name = ''`
|
||||
- Add `get_kernel_version()` function and use it in `generate_config_entry()`
|
||||
4. Test with `sudo nixos-rebuild test --flake .#nixos`
|
||||
External flake inputs:
|
||||
- `nixpkgs` - Main NixOS packages (nixos-unstable)
|
||||
- `noctalia` - Desktop shell
|
||||
- `nix-cachyos-kernel` - CachyOS kernel with optimizations
|
||||
- `zen-browser` - Zen browser
|
||||
- `opencode` - AI coding assistant
|
||||
|
||||
75
CLAUDE.md
75
CLAUDE.md
@@ -1,75 +0,0 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Overview
|
||||
|
||||
This is "Atlas" - a modular, flake-based NixOS configuration for a desktop workstation. The system is AMD-specific (CPU + GPU) and optimized for gaming, development, and daily use.
|
||||
|
||||
## Common Commands
|
||||
|
||||
```bash
|
||||
# Test configuration without switching (validate before applying)
|
||||
sudo nixos-rebuild test --flake .#nixos
|
||||
|
||||
# Apply configuration
|
||||
sudo nixos-rebuild switch --flake .#nixos
|
||||
|
||||
# Build and set as boot default (without switching)
|
||||
sudo nixos-rebuild boot --flake .#nixos
|
||||
|
||||
# Update all flake inputs
|
||||
nix flake update
|
||||
|
||||
# Update specific input
|
||||
nix flake lock --update-input nixpkgs
|
||||
|
||||
# Garbage collection
|
||||
sudo nix-collect-garbage --delete-older-than 14d
|
||||
```
|
||||
|
||||
Shell aliases are defined in `modules/shell.nix`: `rebuild`, `rebuild-test`, `rebuild-boot`, `update`, `gc-nix`.
|
||||
|
||||
## Architecture
|
||||
|
||||
**Entry Points:**
|
||||
- `flake.nix` - Flake definition with inputs (nixpkgs unstable, nix-cachyos-kernel, noctalia shell)
|
||||
- `configuration.nix` - Main config that imports all modules, defines boot, networking, user, and nix settings
|
||||
- `hardware-configuration.nix` - Auto-generated by `nixos-generate-config` (do not edit manually)
|
||||
|
||||
**Modular Structure:**
|
||||
All feature configurations live in `modules/` as standalone NixOS modules:
|
||||
- `desktop.nix` - XDG portals, Wayland, polkit, launcher (Vicinae)
|
||||
- `gpu-amd.nix` - AMD drivers, Vulkan, VA-API, CoreCtrl
|
||||
- `gaming.nix` - Steam, Gamemode, Wine/Proton, kernel tweaks
|
||||
- `dev.nix` - Docker, Node.js, Rust, build tools, CLI utilities
|
||||
- `shell.nix` - Fish shell config, aliases, plugins
|
||||
- `services.nix` - fstrim, zram, avahi, profile-sync-daemon, earlyoom
|
||||
- `audio.nix`, `theming.nix`, `power.nix`, `virtualization.nix`, `navidrome.nix`, `apps.nix`
|
||||
|
||||
Each module follows the pattern: `{ config, pkgs, lib, ... }:`
|
||||
|
||||
**Package Management Philosophy:**
|
||||
- System packages (`environment.systemPackages`): Services, hardware support, desktop infrastructure, build tools
|
||||
- User packages (`nix profile`): GUI apps and fast-updating tools - managed independently with `update-apps` alias
|
||||
|
||||
## Code Conventions
|
||||
|
||||
- 2-space indentation
|
||||
- Standard module signature: `{ config, pkgs, lib, ... }:`
|
||||
- Package lists use `with pkgs; [ ... ]` syntax
|
||||
- Decorative comment separators (`# ═══...`) for major sections
|
||||
|
||||
## Critical Rules
|
||||
|
||||
1. **Never modify `hardware-configuration.nix`** - it's auto-generated
|
||||
2. **Never change `system.stateVersion`** (currently 26.05)
|
||||
3. **Always validate with `rebuild-test` before switching**
|
||||
4. User groups are distributed across modules (docker in dev.nix, gamemode in gaming.nix, corectrl in gpu-amd.nix, libvirtd in virtualization.nix)
|
||||
|
||||
## Key System Details
|
||||
|
||||
- **Kernel**: CachyOS with x86_64-v3 optimizations, scx_lavd scheduler
|
||||
- **Desktop**: Niri compositor, Ly display manager, Ghostty terminal
|
||||
- **User**: `pinj` with Fish shell (Zsh as fallback)
|
||||
- **State Version**: 26.05
|
||||
407
README.md
407
README.md
@@ -1,315 +1,158 @@
|
||||
# Atlas - NixOS Desktop Configuration
|
||||
# atlas - NixOS Configuration
|
||||
|
||||
A modular, flake-based NixOS configuration for a high-performance desktop workstation with AMD GPU, optimized for gaming and development.
|
||||
[](https://nixos.org)
|
||||
[](https://nixos.wiki/wiki/Flakes)
|
||||
[](LICENSE)
|
||||
|
||||
> A modular, declarative NixOS configuration for desktop gaming and development.
|
||||
|
||||
## Overview
|
||||
|
||||
This repository contains the complete NixOS system configuration for **atlas**, a desktop system optimized for gaming, development, and daily use. It uses Nix flakes for reproducible builds and modular organization for maintainability.
|
||||
|
||||
### System Highlights
|
||||
|
||||
- **OS**: NixOS (unstable channel)
|
||||
- **Kernel**: CachyOS optimized kernel with x86_64-v3 microarchitecture
|
||||
- **Bootloader**: Limine with Secure Boot support
|
||||
- **Window Manager**: Niri (scrollable-tiling Wayland compositor)
|
||||
- **Shell**: Fish with Zsh fallback
|
||||
- **Terminal**: Ghostty
|
||||
- **Browser**: Zen Browser + Firefox
|
||||
- **Editor**: Zed
|
||||
|
||||
## Features
|
||||
|
||||
- **Nix Flakes** - Reproducible, declarative system configuration
|
||||
- **CachyOS Kernel** - Performance-optimized kernel with sched-ext scheduler
|
||||
- **Wayland Desktop** - Niri compositor with Noctalia shell
|
||||
- **AMD GPU** - Full Vulkan, VA-API, and overclocking support via CoreCtrl
|
||||
- **Gaming Ready** - Steam, Proton-GE, Gamemode, Gamescope, Wine, Lutris
|
||||
- **Development** - Docker, direnv, modern CLI tools, multiple language runtimes
|
||||
- **Audio** - PipeWire with high-quality Bluetooth codecs (LDAC, AAC, aptX)
|
||||
- **Secure Boot** - Limine bootloader with Secure Boot support
|
||||
### Gaming
|
||||
- Steam with Proton-GE
|
||||
- Lutris, Heroic (Epic/GOG), Faugus Launchers
|
||||
- GameMode optimizations
|
||||
- MangoHud & vkBasalt support
|
||||
- AMD GPU with ROCm acceleration
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/ragusa-it/nixos.git
|
||||
cd nixos
|
||||
|
||||
# Test configuration (recommended first)
|
||||
sudo nixos-rebuild test --flake .#nixos
|
||||
|
||||
# Apply configuration
|
||||
sudo nixos-rebuild switch --flake .#nixos
|
||||
```
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
nixos/
|
||||
├── flake.nix # Flake inputs and outputs
|
||||
├── flake.lock # Pinned dependency versions
|
||||
├── configuration.nix # Main config (imports all modules)
|
||||
├── hardware-configuration.nix # Auto-generated hardware config
|
||||
├── AGENTS.md # Guidelines for AI agents
|
||||
└── modules/
|
||||
├── apps.nix # User applications
|
||||
├── audio.nix # PipeWire & Bluetooth audio
|
||||
├── boot-plymouth.nix # Plymouth boot splash
|
||||
├── desktop.nix # Wayland, portals, polkit
|
||||
├── dev.nix # Docker, dev tools, languages
|
||||
├── gaming.nix # Steam, Gamemode, Wine
|
||||
├── gpu-amd.nix # AMD GPU drivers & tools
|
||||
├── navidrome.nix # Music streaming server
|
||||
├── power.nix # Power management
|
||||
├── services.nix # System services
|
||||
├── shell.nix # Fish shell config
|
||||
└── theming.nix # Fonts, themes, cursors
|
||||
```
|
||||
|
||||
## Flake Inputs
|
||||
|
||||
| Input | Description |
|
||||
|-------|-------------|
|
||||
| `nixpkgs` | NixOS unstable channel |
|
||||
| `nix-cachyos-kernel` | CachyOS performance-optimized kernels |
|
||||
| `noctalia` | Noctalia desktop shell |
|
||||
| `zen-browser` | Zen Browser (Firefox fork) |
|
||||
| `opencode` | AI coding assistant |
|
||||
|
||||
## Module Overview
|
||||
### Development
|
||||
- Rust, Python, Node.js toolchains
|
||||
- Docker & container tools
|
||||
- Git, GitHub CLI, Lazygit
|
||||
- Nix language server (nil, nixd)
|
||||
- Claude Code & Opencode AI assistants
|
||||
|
||||
### Desktop Environment
|
||||
- Custom Noctalia desktop shell
|
||||
- Wayland portals for screen sharing
|
||||
- Flatpak support with Flathub
|
||||
- Nordic theming
|
||||
- Plymouth boot splash
|
||||
|
||||
| Component | Choice |
|
||||
|-----------|--------|
|
||||
| Compositor | Niri (Wayland) |
|
||||
| Shell | Noctalia |
|
||||
| Display Manager | Ly |
|
||||
| Terminal | Ghostty |
|
||||
| File Manager | Nautilus |
|
||||
| Editor | Zed |
|
||||
| Browser | Zen Browser, Firefox |
|
||||
### Security & Privacy
|
||||
- Full disk encryption (LUKS2)
|
||||
- Encrypted swap partition
|
||||
- Secure Boot with custom keys
|
||||
- Bitwarden password manager
|
||||
- Proton VPN
|
||||
|
||||
### Hardware Configuration
|
||||
## Structure
|
||||
|
||||
| Hardware | Configuration |
|
||||
|----------|---------------|
|
||||
| CPU | AMD Ryzen with `amd_pstate=active` |
|
||||
| GPU | AMD with RADV, VA-API, CoreCtrl |
|
||||
| Audio | PipeWire (ALSA, PulseAudio, JACK) |
|
||||
| Bluetooth | Enabled with LDAC, AAC, aptX codecs |
|
||||
|
||||
### Gaming Stack
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| Steam | With Proton-GE, remote play, LAN transfers |
|
||||
| Gamemode | CPU/GPU optimization during gaming |
|
||||
| Gamescope | Micro-compositor for games |
|
||||
| Lutris | Game launcher |
|
||||
| Heroic | Epic/GOG launcher |
|
||||
| Wine | Latest staging with winetricks |
|
||||
| Scheduler | `scx_lavd` low-latency scheduler |
|
||||
|
||||
### Development Tools
|
||||
|
||||
| Category | Tools |
|
||||
|----------|-------|
|
||||
| Containers | Docker, docker-compose, lazydocker |
|
||||
| Languages | Node.js, Bun, Python, Rust |
|
||||
| Build | gcc, cmake, make, pkg-config |
|
||||
| Version Control | git, gh, lazygit, delta |
|
||||
| CLI | ripgrep, fd, fzf, eza, bat, jq, yq |
|
||||
|
||||
## Shell Aliases
|
||||
|
||||
The Fish shell is configured with useful aliases:
|
||||
|
||||
```bash
|
||||
# NixOS
|
||||
rebuild # sudo nixos-rebuild switch --flake .
|
||||
rebuild-test # sudo nixos-rebuild test --flake .
|
||||
update # nix flake update
|
||||
gc-nix # sudo nix-collect-garbage -d
|
||||
|
||||
# Git shortcuts
|
||||
gs, gd, gl, ga, gc, gp, gpu, gco, gb
|
||||
|
||||
# Docker shortcuts
|
||||
dc, dps, dpa, dl, dex
|
||||
|
||||
# Modern replacements
|
||||
ll, ls, cat, find, grep, df, du # → eza, bat, fd, rg, duf, dust
|
||||
```
|
||||
.
|
||||
├── configuration.nix # Main entry point
|
||||
├── flake.nix # Flake inputs and outputs
|
||||
├── hardware-configuration.nix # Auto-generated hardware config
|
||||
├── modules/
|
||||
│ ├── core/ # Boot, users, networking
|
||||
│ ├── hardware/ # GPU, audio, power
|
||||
│ ├── desktop/ # WM, apps, theming
|
||||
│ ├── services/ # System services
|
||||
│ ├── dev/ # Development tools
|
||||
│ └── gaming/ # Steam, Wine, Gamemode
|
||||
├── overlays/ # Package patches
|
||||
├── scripts/ # Installation helpers
|
||||
└── wallpaper/ # Desktop backgrounds
|
||||
```
|
||||
|
||||
## Common Tasks
|
||||
## Installation
|
||||
|
||||
### Rebuild System
|
||||
### Prerequisites
|
||||
- NixOS installation media
|
||||
- Internet connection
|
||||
- Target disk (e.g., `/dev/nvme0n1`)
|
||||
|
||||
### Automated Install (Full Disk Encryption)
|
||||
|
||||
```bash
|
||||
# Test without switching (dry-run)
|
||||
sudo nixos-rebuild test --flake .#nixos
|
||||
|
||||
# Apply changes
|
||||
sudo nixos-rebuild switch --flake .#nixos
|
||||
|
||||
# Rebuild for next boot only
|
||||
sudo nixos-rebuild boot --flake .#nixos
|
||||
# Boot from NixOS ISO, then:
|
||||
curl -sL https://raw.githubusercontent.com/YOUR_USERNAME/nixos/main/scripts/install-fde.sh | sudo bash
|
||||
```
|
||||
|
||||
### Update Dependencies
|
||||
### Manual Install
|
||||
|
||||
```bash
|
||||
# Update all flake inputs
|
||||
# 1. Partition, format, and mount
|
||||
cryptsetup luksFormat /dev/nvme0n1p3
|
||||
cryptsetup open /dev/nvme0n1p3 cryptroot
|
||||
mkfs.xfs /dev/mapper/cryptroot
|
||||
mount /dev/mapper/cryptroot /mnt
|
||||
|
||||
# 2. Clone and install
|
||||
git clone https://github.com/YOUR_USERNAME/nixos.git /mnt/etc/nixos
|
||||
cd /mnt/etc/nixos
|
||||
nixos-install --flake .#atlas
|
||||
```
|
||||
|
||||
### Post-Install
|
||||
|
||||
```bash
|
||||
# Set up Secure Boot (optional but recommended)
|
||||
sudo /etc/nixos/scripts/setup-secureboot.sh
|
||||
|
||||
# Switch to new configuration
|
||||
sudo nixos-rebuild switch --flake /etc/nixos
|
||||
```
|
||||
|
||||
## Daily Usage
|
||||
|
||||
```bash
|
||||
# Rebuild system
|
||||
sudo nixos-rebuild switch --flake .
|
||||
|
||||
# Update flake inputs
|
||||
nix flake update
|
||||
|
||||
# Update specific input
|
||||
nix flake update nixpkgs
|
||||
```
|
||||
|
||||
### Garbage Collection
|
||||
|
||||
```bash
|
||||
# Manual cleanup (removes generations older than 14 days)
|
||||
sudo nix-collect-garbage --delete-older-than 14d
|
||||
|
||||
# List generations
|
||||
nix-env --list-generations
|
||||
|
||||
# Remove all old generations
|
||||
# Clean old generations
|
||||
sudo nix-collect-garbage -d
|
||||
|
||||
# Format all nix files
|
||||
nixfmt **/*.nix
|
||||
```
|
||||
|
||||
### Package Management
|
||||
## Hardware Requirements
|
||||
|
||||
```bash
|
||||
# Search for packages
|
||||
nix search nixpkgs <package>
|
||||
- **CPU**: AMD Ryzen (with x86_64-v3 support for CachyOS kernel)
|
||||
- **GPU**: AMD Radeon (ROCm supported)
|
||||
- **RAM**: 16GB+ recommended
|
||||
- **Storage**: NVMe SSD recommended
|
||||
|
||||
# Install user GUI apps (via nix profile)
|
||||
nix profile install nixpkgs#<package>
|
||||
## External Dependencies
|
||||
|
||||
# Update user apps
|
||||
nix profile upgrade '.*'
|
||||
This configuration uses the following flake inputs:
|
||||
|
||||
# List installed user apps
|
||||
nix profile list
|
||||
```
|
||||
- [nixpkgs](https://github.com/NixOS/nixpkgs) - Main package repository
|
||||
- [noctalia-shell](https://github.com/noctalia-dev/noctalia-shell) - Desktop environment
|
||||
- [nix-cachyos-kernel](https://github.com/xddxdd/nix-cachyos-kernel) - Optimized kernel
|
||||
- [zen-browser](https://github.com/youwen5/zen-browser-flake) - Zen Browser
|
||||
- [opencode](https://github.com/anomalyco/opencode) - AI coding assistant
|
||||
|
||||
### Validate Configuration
|
||||
## Acknowledgments
|
||||
|
||||
```bash
|
||||
# Quick syntax check
|
||||
nix flake check
|
||||
|
||||
# Show flake outputs
|
||||
nix flake show
|
||||
```
|
||||
|
||||
## Services
|
||||
|
||||
| Service | Port | Description |
|
||||
|---------|------|-------------|
|
||||
| Navidrome | 4533 | Music streaming (localhost only) |
|
||||
| Tailscale | - | Mesh VPN |
|
||||
| SSH | 22 | Remote access |
|
||||
|
||||
## System Optimizations
|
||||
|
||||
- **ZRAM Swap** - Compressed RAM swap with zstd
|
||||
- **SSD TRIM** - Weekly fstrim for SSD longevity
|
||||
- **EarlyOOM** - Prevents system freeze on memory exhaustion
|
||||
- **Profile Sync Daemon** - Browser profiles in RAM
|
||||
- **Auto GC** - Weekly garbage collection of old generations
|
||||
|
||||
## Kernel Tweaks
|
||||
|
||||
```nix
|
||||
# Gaming optimizations
|
||||
"fs.inotify.max_user_watches" = 524288 # Large games support
|
||||
"vm.swappiness" = 10 # Prefer RAM over swap
|
||||
"vm.vfs_cache_pressure" = 50 # Keep directory caches
|
||||
```
|
||||
|
||||
## Theming
|
||||
|
||||
| Element | Choice |
|
||||
|---------|--------|
|
||||
| GTK Theme | adw-gtk3-dark |
|
||||
| Icons | Papirus-Dark |
|
||||
| Cursor | Adwaita (24px) |
|
||||
| Fonts | Inter (UI), JetBrains Mono Nerd Font (mono) |
|
||||
| Color Scheme | Dark |
|
||||
|
||||
Configure with `nwg-look` or `dconf-editor`.
|
||||
|
||||
## Adding New Modules
|
||||
|
||||
1. Create `modules/newmodule.nix`:
|
||||
|
||||
```nix
|
||||
# modules/newmodule.nix
|
||||
# Brief description
|
||||
{
|
||||
config,
|
||||
pkgs,
|
||||
lib,
|
||||
...
|
||||
}:
|
||||
|
||||
{
|
||||
# Module content
|
||||
}
|
||||
```
|
||||
|
||||
2. Add import to `configuration.nix`:
|
||||
|
||||
```nix
|
||||
imports = [
|
||||
# ...
|
||||
./modules/newmodule.nix
|
||||
];
|
||||
```
|
||||
|
||||
3. Test: `sudo nixos-rebuild test --flake .#nixos`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Build Fails
|
||||
|
||||
```bash
|
||||
# Check for syntax errors
|
||||
nix flake check
|
||||
|
||||
# Build with verbose output
|
||||
sudo nixos-rebuild switch --flake .#nixos --show-trace
|
||||
```
|
||||
|
||||
### Rollback
|
||||
|
||||
```bash
|
||||
# Boot into previous generation from bootloader menu
|
||||
# Or switch to specific generation:
|
||||
sudo nixos-rebuild switch --rollback
|
||||
```
|
||||
|
||||
### GPU Issues
|
||||
|
||||
```bash
|
||||
# Check Vulkan
|
||||
vulkaninfo | grep deviceName
|
||||
|
||||
# Check VA-API
|
||||
vainfo
|
||||
|
||||
# Monitor GPU
|
||||
nvtop
|
||||
radeontop
|
||||
```
|
||||
|
||||
### Audio Issues
|
||||
|
||||
```bash
|
||||
# Check PipeWire status
|
||||
systemctl --user status pipewire pipewire-pulse wireplumber
|
||||
|
||||
# Restart audio stack
|
||||
systemctl --user restart pipewire pipewire-pulse wireplumber
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- **State Version**: `26.05` - Do not change unless migrating
|
||||
- **Username**: `pinj` - Configured throughout the system
|
||||
- **Locale**: English (US) with German regional settings
|
||||
- **Keyboard**: German (nodeadkeys)
|
||||
- **Timezone**: Europe/Berlin
|
||||
- [NixOS](https://nixos.org/) - The purely functional Linux distribution
|
||||
- [CachyOS](https://cachyos.org/) - Optimized kernel and packages
|
||||
- [Limine](https://limine-bootloader.org/) - Modern bootloader
|
||||
- [Niri](https://github.com/YaLTeR/niri) - Scrollable-tiling Wayland compositor
|
||||
|
||||
## License
|
||||
|
||||
Personal configuration. Feel free to use as inspiration for your own setup.
|
||||
This configuration is released into the public domain. Feel free to use, modify, and distribute as needed.
|
||||
|
||||
---
|
||||
|
||||
<p align="center">Made with ❄️ Nix</p>
|
||||
|
||||
Reference in New Issue
Block a user