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
|
## Build/Validation Commands
|
||||||
|
|
||||||
## 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
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Test configuration without switching (recommended first)
|
# Validate Nix syntax and build configuration
|
||||||
sudo nixos-rebuild test --flake .#nixos
|
|
||||||
|
|
||||||
# Switch to new configuration
|
|
||||||
sudo nixos-rebuild switch --flake .#nixos
|
|
||||||
|
|
||||||
# Quick syntax validation
|
|
||||||
nix flake check
|
nix flake check
|
||||||
|
|
||||||
# Update all flake inputs
|
# Build the configuration (dry-run, doesn't activate)
|
||||||
nix flake update
|
nixos-rebuild dry-build --flake .
|
||||||
|
|
||||||
# Garbage collection
|
# Format all .nix files with nixfmt
|
||||||
sudo nix-collect-garbage --delete-older-than 14d
|
nixfmt **/*.nix
|
||||||
|
|
||||||
|
# Check for common issues
|
||||||
|
nixos-rebuild dry-activate --flake .
|
||||||
```
|
```
|
||||||
|
|
||||||
## Code Style Guidelines
|
## Code Style Guidelines
|
||||||
|
|
||||||
### File Structure
|
### File Organization
|
||||||
|
- Entry point: `configuration.nix`
|
||||||
Each module follows this pattern:
|
- 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
|
```nix
|
||||||
# modules/example.nix
|
# modules/<category>/<name>.nix
|
||||||
# Brief description of what this module does
|
# Brief description of what this module configures
|
||||||
{
|
{
|
||||||
config,
|
config,
|
||||||
pkgs,
|
pkgs,
|
||||||
lib,
|
lib,
|
||||||
|
inputs, # Only if using flake inputs
|
||||||
|
username, # Custom arg passed from flake
|
||||||
...
|
...
|
||||||
}:
|
}:
|
||||||
|
|
||||||
{
|
{
|
||||||
# Module content here
|
# Configuration options here
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Formatting
|
### Imports Pattern
|
||||||
|
`default.nix` files should only contain imports:
|
||||||
- **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
|
|
||||||
|
|
||||||
```nix
|
```nix
|
||||||
environment.systemPackages = with pkgs; [
|
# modules/<category>/default.nix
|
||||||
# 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, ... }:
|
|
||||||
|
|
||||||
{
|
{
|
||||||
environment.systemPackages = [
|
imports = [
|
||||||
inputs.flakename.packages.${pkgs.system}.default
|
./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
|
```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
|
External flake inputs:
|
||||||
- Always test with `nixos-rebuild test` before `switch`
|
- `nixpkgs` - Main NixOS packages (nixos-unstable)
|
||||||
- Use `nix flake check` for quick syntax validation
|
- `noctalia` - Desktop shell
|
||||||
|
- `nix-cachyos-kernel` - CachyOS kernel with optimizations
|
||||||
## Custom Limine Boot Labels (MAINTENANCE REQUIRED)
|
- `zen-browser` - Zen browser
|
||||||
|
- `opencode` - AI coding assistant
|
||||||
**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`
|
|
||||||
|
|||||||
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
|
## Features
|
||||||
|
|
||||||
- **Nix Flakes** - Reproducible, declarative system configuration
|
### Gaming
|
||||||
- **CachyOS Kernel** - Performance-optimized kernel with sched-ext scheduler
|
- Steam with Proton-GE
|
||||||
- **Wayland Desktop** - Niri compositor with Noctalia shell
|
- Lutris, Heroic (Epic/GOG), Faugus Launchers
|
||||||
- **AMD GPU** - Full Vulkan, VA-API, and overclocking support via CoreCtrl
|
- GameMode optimizations
|
||||||
- **Gaming Ready** - Steam, Proton-GE, Gamemode, Gamescope, Wine, Lutris
|
- MangoHud & vkBasalt support
|
||||||
- **Development** - Docker, direnv, modern CLI tools, multiple language runtimes
|
- AMD GPU with ROCm acceleration
|
||||||
- **Audio** - PipeWire with high-quality Bluetooth codecs (LDAC, AAC, aptX)
|
|
||||||
- **Secure Boot** - Limine bootloader with Secure Boot support
|
|
||||||
|
|
||||||
## Quick Start
|
### Development
|
||||||
|
- Rust, Python, Node.js toolchains
|
||||||
```bash
|
- Docker & container tools
|
||||||
# Clone the repository
|
- Git, GitHub CLI, Lazygit
|
||||||
git clone https://github.com/ragusa-it/nixos.git
|
- Nix language server (nil, nixd)
|
||||||
cd nixos
|
- Claude Code & Opencode AI assistants
|
||||||
|
|
||||||
# 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
|
|
||||||
|
|
||||||
### Desktop Environment
|
### Desktop Environment
|
||||||
|
- Custom Noctalia desktop shell
|
||||||
|
- Wayland portals for screen sharing
|
||||||
|
- Flatpak support with Flathub
|
||||||
|
- Nordic theming
|
||||||
|
- Plymouth boot splash
|
||||||
|
|
||||||
| Component | Choice |
|
### Security & Privacy
|
||||||
|-----------|--------|
|
- Full disk encryption (LUKS2)
|
||||||
| Compositor | Niri (Wayland) |
|
- Encrypted swap partition
|
||||||
| Shell | Noctalia |
|
- Secure Boot with custom keys
|
||||||
| Display Manager | Ly |
|
- Bitwarden password manager
|
||||||
| Terminal | Ghostty |
|
- Proton VPN
|
||||||
| File Manager | Nautilus |
|
|
||||||
| Editor | Zed |
|
|
||||||
| Browser | Zen Browser, Firefox |
|
|
||||||
|
|
||||||
### Hardware Configuration
|
## Structure
|
||||||
|
|
||||||
| Hardware | Configuration |
|
```
|
||||||
|----------|---------------|
|
.
|
||||||
| CPU | AMD Ryzen with `amd_pstate=active` |
|
├── configuration.nix # Main entry point
|
||||||
| GPU | AMD with RADV, VA-API, CoreCtrl |
|
├── flake.nix # Flake inputs and outputs
|
||||||
| Audio | PipeWire (ALSA, PulseAudio, JACK) |
|
├── hardware-configuration.nix # Auto-generated hardware config
|
||||||
| Bluetooth | Enabled with LDAC, AAC, aptX codecs |
|
├── modules/
|
||||||
|
│ ├── core/ # Boot, users, networking
|
||||||
### Gaming Stack
|
│ ├── hardware/ # GPU, audio, power
|
||||||
|
│ ├── desktop/ # WM, apps, theming
|
||||||
| Component | Description |
|
│ ├── services/ # System services
|
||||||
|-----------|-------------|
|
│ ├── dev/ # Development tools
|
||||||
| Steam | With Proton-GE, remote play, LAN transfers |
|
│ └── gaming/ # Steam, Wine, Gamemode
|
||||||
| Gamemode | CPU/GPU optimization during gaming |
|
├── overlays/ # Package patches
|
||||||
| Gamescope | Micro-compositor for games |
|
├── scripts/ # Installation helpers
|
||||||
| Lutris | Game launcher |
|
└── wallpaper/ # Desktop backgrounds
|
||||||
| 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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Common Tasks
|
## Installation
|
||||||
|
|
||||||
### Rebuild System
|
### Prerequisites
|
||||||
|
- NixOS installation media
|
||||||
|
- Internet connection
|
||||||
|
- Target disk (e.g., `/dev/nvme0n1`)
|
||||||
|
|
||||||
|
### Automated Install (Full Disk Encryption)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Test without switching (dry-run)
|
# Boot from NixOS ISO, then:
|
||||||
sudo nixos-rebuild test --flake .#nixos
|
curl -sL https://raw.githubusercontent.com/YOUR_USERNAME/nixos/main/scripts/install-fde.sh | sudo bash
|
||||||
|
|
||||||
# Apply changes
|
|
||||||
sudo nixos-rebuild switch --flake .#nixos
|
|
||||||
|
|
||||||
# Rebuild for next boot only
|
|
||||||
sudo nixos-rebuild boot --flake .#nixos
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Update Dependencies
|
### Manual Install
|
||||||
|
|
||||||
```bash
|
```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
|
nix flake update
|
||||||
|
|
||||||
# Update specific input
|
# Clean old generations
|
||||||
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
|
|
||||||
sudo nix-collect-garbage -d
|
sudo nix-collect-garbage -d
|
||||||
|
|
||||||
|
# Format all nix files
|
||||||
|
nixfmt **/*.nix
|
||||||
```
|
```
|
||||||
|
|
||||||
### Package Management
|
## Hardware Requirements
|
||||||
|
|
||||||
```bash
|
- **CPU**: AMD Ryzen (with x86_64-v3 support for CachyOS kernel)
|
||||||
# Search for packages
|
- **GPU**: AMD Radeon (ROCm supported)
|
||||||
nix search nixpkgs <package>
|
- **RAM**: 16GB+ recommended
|
||||||
|
- **Storage**: NVMe SSD recommended
|
||||||
|
|
||||||
# Install user GUI apps (via nix profile)
|
## External Dependencies
|
||||||
nix profile install nixpkgs#<package>
|
|
||||||
|
|
||||||
# Update user apps
|
This configuration uses the following flake inputs:
|
||||||
nix profile upgrade '.*'
|
|
||||||
|
|
||||||
# List installed user apps
|
- [nixpkgs](https://github.com/NixOS/nixpkgs) - Main package repository
|
||||||
nix profile list
|
- [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
|
- [NixOS](https://nixos.org/) - The purely functional Linux distribution
|
||||||
# Quick syntax check
|
- [CachyOS](https://cachyos.org/) - Optimized kernel and packages
|
||||||
nix flake check
|
- [Limine](https://limine-bootloader.org/) - Modern bootloader
|
||||||
|
- [Niri](https://github.com/YaLTeR/niri) - Scrollable-tiling Wayland compositor
|
||||||
# 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
|
|
||||||
|
|
||||||
## License
|
## 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