{"id":30348880,"url":"https://github.com/ricoledan/nix-config","last_synced_at":"2025-10-09T00:44:57.300Z","repository":{"id":304284154,"uuid":"1018290327","full_name":"Ricoledan/nix-config","owner":"Ricoledan","description":"📦 my personal cross-platform development environment using Nix flakes + native package managers","archived":false,"fork":false,"pushed_at":"2025-10-06T09:07:31.000Z","size":170,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-06T11:17:11.283Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ricoledan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-12T00:49:05.000Z","updated_at":"2025-09-09T13:00:18.000Z","dependencies_parsed_at":"2025-07-12T06:12:45.972Z","dependency_job_id":"5ed6d199-70b6-452c-b943-127ce42853cb","html_url":"https://github.com/Ricoledan/nix-config","commit_stats":null,"previous_names":["ricoledan/nix-config"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Ricoledan/nix-config","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ricoledan%2Fnix-config","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ricoledan%2Fnix-config/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ricoledan%2Fnix-config/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ricoledan%2Fnix-config/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ricoledan","download_url":"https://codeload.github.com/Ricoledan/nix-config/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ricoledan%2Fnix-config/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000641,"owners_count":26082879,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-18T19:14:29.980Z","updated_at":"2025-10-09T00:44:57.279Z","avatar_url":"https://github.com/Ricoledan.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rico's Development Environment\n\n[![CI](https://github.com/Ricoledan/nix-config/actions/workflows/ci.yml/badge.svg)](https://github.com/Ricoledan/nix-config/actions/workflows/ci.yml)\n[![CI Simple](https://github.com/Ricoledan/nix-config/actions/workflows/ci-simple.yml/badge.svg)](https://github.com/Ricoledan/nix-config/actions/workflows/ci-simple.yml)\n[![Update Dependencies](https://github.com/Ricoledan/nix-config/actions/workflows/update-deps.yml/badge.svg)](https://github.com/Ricoledan/nix-config/actions/workflows/update-deps.yml)\n[![Nix Flake](https://img.shields.io/badge/nix-flake-blue.svg)](https://nixos.wiki/wiki/Flakes)\n[![Home Manager](https://img.shields.io/badge/home--manager-24.05-green.svg)](https://github.com/nix-community/home-manager)\n\nCross-platform Nix flake configuration with Home Manager integration, following best practices for maintainability and security.\n\n## Core Principles\n\n1. **Reproducibility First**: Prefer declarative, reproducible configurations over imperative setups\n   - Use Nix for package management when possible\n   - Version-control all configuration\n   - Minimize manual setup steps\n\n2. **Cross-Platform Compatibility**: Support both macOS and Linux seamlessly\n   - Use conditional logic for platform-specific needs\n   - Document platform differences clearly\n   - Test on both platforms regularly\n\n3. **Pragmatic Over Pure**: Choose practical solutions when ideal ones are too complex\n   - It's okay to use platform-native tools (like Homebrew) when Nix falls short\n   - Prioritize working solutions over theoretical purity\n   - Document and justify exceptions clearly (see [DECISIONS.md](DECISIONS.md))\n\n4. **User Experience**: Make the setup process as smooth as possible\n   - Provide clear error messages and guidance\n   - Automate what can be automated\n   - Document manual steps thoroughly\n\n5. **Maintainability**: Keep the configuration simple and well-documented\n   - Prefer clarity over cleverness\n   - Document the \"why\" not just the \"what\"\n   - Regular cleanup of unused components\n\n## Features\n\n- **Cross-platform**: Works seamlessly on macOS (aarch64) and Linux (x86_64)\n- **Declarative**: All configuration in code, fully reproducible\n- **Automated**: Multiple CI/CD workflows, automated dependency updates, format checking\n- **Secure**: Built-in secret management guidelines, security scanning (when available)\n- **Fast**: Optimized with Nix caches and direnv integration\n- **Pragmatic**: Uses platform-native tools when optimal (see [DECISIONS.md](DECISIONS.md))\n- **Well-documented**: Comprehensive guides for modules, workflows, and troubleshooting\n\n## Documentation\n\n- **[Module Documentation](docs/modules.md)** - Detailed information about each module\n- **[Common Workflows](docs/workflows.md)** - Day-to-day usage and tasks\n- **[Troubleshooting Guide](docs/troubleshooting.md)** - Solutions to common issues\n- **[Architectural Decisions](DECISIONS.md)** - Rationale behind design choices\n\n## Quick Start\n\n### Prerequisites\n- Nix installed (with flakes enabled)\n- Git installed\n\n### Initial Setup on a New Machine\n\n```bash\n# 1. Clone this repository\ngit clone https://github.com/ricoledan/nix-config.git\ncd nix-config\n\n# 2. Run initial setup (installs Homebrew on macOS)\n./setup.sh\n\n# 3. Apply the configuration (works for any user)\n./sync-hm.sh\n\n# The sync-hm.sh script automatically:\n# - Detects your username ($USER)\n# - Detects your home directory ($HOME)\n# - Detects your system architecture\n# - Applies the configuration\n\n# For manual runs, use:\n# nix run home-manager/master -- switch --flake .#user@$(nix eval --impure --expr 'builtins.currentSystem' --raw) --impure\n\n# 4. Enter development shell (optional, for development work)\nnix develop\n\n# 5. Allow direnv for automatic environment loading\ndirenv allow\n```\n\n### What This Does\n1. **setup.sh**: Installs Homebrew (macOS only) and ensures Nix flakes are enabled\n2. **Home Manager activation**:\n   - Installs all packages defined in `home/modules/packages.nix`\n   - Configures Zsh with Oh My Zsh and Powerlevel10k (with instant prompt)\n   - Sets up Neovim with LazyVim\n   - Applies all dotfiles and configurations\n   - Enables direnv for automatic environment loading\n3. **nix develop**: Provides a minimal shell (git, nixpkgs-fmt) before Home Manager activation\n\n## Components Overview\n\n### Core Technologies\n- **Nix Flakes**: Reproducible, declarative package management\n- **Home Manager**: User environment and dotfile management\n- **Homebrew** (macOS): GUI applications and system packages\n- **Oh My Zsh + Powerlevel10k**: Enhanced terminal experience\n- **Direnv**: Automatic environment loading\n\n### Development Tools (via Nix)\n- **Editors**: VSCode, Neovim\n- **Version Control**: Git, GitHub CLI (gh)\n- **Containers**: Managed via Homebrew on macOS (see [docs/podman.md](docs/podman.md))\n- **Languages**: Node.js 22, Python 3 (with pip)\n- **Code Quality**: pre-commit, nixpkgs-fmt\n- **CLI Tools**:\n  - Text processing: jq, ripgrep, bat, fd\n  - System utilities: curl, tree, openssh\n  - Media: yt-dlp\n  - AI: claude-code\n\n### Shell Configuration\n- **Zsh** with:\n  - Oh My Zsh (git, podman plugins)\n  - Powerlevel10k theme\n  - Syntax highlighting\n  - Auto-suggestions\n  - Custom aliases (ll, gs, gc, gp)\n  - 10k line history\n  - Fastfetch on startup\n\n### Editor Configuration\n- **Neovim** with:\n  - LazyVim distribution (full IDE experience)\n  - LSP support for multiple languages\n  - Auto-installed plugins via Nix\n  - Custom plugin support in `~/.config/nvim/lua/plugins/`\n\n### Window Management\n- **Aerospace**: Tiling window manager for macOS\n  - Configuration in `config/aerospace.toml`\n  - Managed by Home Manager\n  - i3-like keybindings\n\n### macOS Applications (via Homebrew)\n- **Development**: Ghostty (terminal), JetBrains Toolbox, Podman Desktop\n- **Productivity**: Alfred, Todoist, Fantastical, Notion, Bear, Obsidian\n- **Utilities**: 1Password, CleanMyMac, Caffeine, Aerospace (window manager)\n- **Media**: Plex, mpv\n- **Communication**: Discord\n- **Creative**: Adobe Creative Cloud\n- **Research**: Zotero\n- **Browser**: Zen Browser\n\n## Architecture Diagrams\n\n### System Architecture\n\nThis diagram shows the high-level architecture of the Nix configuration system. It illustrates how the three main entry scripts (`setup.sh`, `sync-hm.sh`, and `update.sh`) interact with the Nix flake system, which then configures the user environment through Home Manager. The platform layer shows how macOS uses Homebrew for certain packages while Linux uses pure Nix packages.\n\n```mermaid\ngraph TB\n    subgraph \"Entry Points\"\n        Setup[setup.sh]\n        Sync[sync-hm.sh]\n        Update[update.sh]\n    end\n\n    subgraph \"Nix Flake System\"\n        Flake[flake.nix]\n        HM[Home Manager]\n        Nixpkgs[nixpkgs]\n    end\n\n    subgraph \"Platform Layer\"\n        Darwin[macOS/Darwin]\n        Linux[Linux]\n        Homebrew[Homebrew\u003cbr/\u003emacOS only]\n    end\n\n    subgraph \"Configuration Modules\"\n        Home[home/home.nix]\n        Packages[modules/packages.nix]\n        Zsh[modules/zsh.nix]\n        Neovim[modules/neovim.nix]\n    end\n\n    subgraph \"User Environment\"\n        Shell[Zsh + Oh My Zsh]\n        Editor[Neovim + LazyVim]\n        Tools[CLI Tools]\n        Apps[GUI Apps]\n    end\n\n    Setup --\u003e Homebrew\n    Setup --\u003e Flake\n    Sync --\u003e Flake\n    Update --\u003e Flake\n\n    Flake --\u003e HM\n    Flake --\u003e Nixpkgs\n    HM --\u003e Home\n\n    Home --\u003e Packages\n    Home --\u003e Zsh\n    Home --\u003e Neovim\n\n    Packages --\u003e Tools\n    Zsh --\u003e Shell\n    Neovim --\u003e Editor\n\n    Darwin --\u003e Homebrew\n    Homebrew --\u003e Apps\n\n    Linux --\u003e Tools\n    Darwin --\u003e Tools\n```\n\n### Module Dependencies\n\nThis diagram illustrates the relationships between different configuration files and modules. The core `flake.nix` defines the overall system and references `home.nix`, which then imports various modules for packages, shell (zsh), and editor (neovim) configuration. External scripts interact with these files to set up, sync, or update the system.\n\n```mermaid\ngraph LR\n    subgraph \"Core\"\n        F[flake.nix]\n        H[home.nix]\n    end\n\n    subgraph \"Modules\"\n        P[packages.nix]\n        Z[zsh.nix]\n        N[neovim.nix]\n    end\n\n    subgraph \"External Configs\"\n        A[aerospace.toml]\n        B[Brewfile]\n    end\n\n    subgraph \"Scripts\"\n        S1[setup.sh]\n        S2[sync-hm.sh]\n        S3[update.sh]\n    end\n\n    F --\u003e|defines| H\n    H --\u003e|imports| P\n    H --\u003e|imports| Z\n    H --\u003e|imports| N\n    H --\u003e|references| A\n\n    S1 --\u003e|installs| B\n    S2 --\u003e|activates| F\n    S3 --\u003e|updates| F\n\n    P --\u003e|provides packages to| H\n    Z --\u003e|configures shell for| H\n    N --\u003e|configures editor for| H\n```\n\n### Data Flow\n\nThis sequence diagram shows the step-by-step process that occurs when you run `./sync-hm.sh`. It demonstrates how the script detects your user environment, invokes Nix flake evaluation, passes configuration to Home Manager, and ultimately results in a fully configured user environment with all packages installed and configurations applied.\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant Script as sync-hm.sh\n    participant Nix as Nix Flake\n    participant HM as Home Manager\n    participant Env as User Environment\n\n    User-\u003e\u003eScript: Run ./sync-hm.sh\n    Script-\u003e\u003eScript: Detect $USER, $HOME, system\n    Script-\u003e\u003eNix: nix run home-manager -- switch\n    Nix-\u003e\u003eNix: Evaluate flake.nix\n    Nix-\u003e\u003eHM: Pass configuration\n    HM-\u003e\u003eHM: Read home.nix\n    HM-\u003e\u003eHM: Import modules\n    HM-\u003e\u003eEnv: Install packages\n    HM-\u003e\u003eEnv: Create symlinks\n    HM-\u003e\u003eEnv: Apply configurations\n    Env--\u003e\u003eUser: Environment ready\n```\n\n### Platform-Specific Components\n\nThis diagram clearly separates common components that work across all platforms from platform-specific implementations. It shows how the configuration handles differences between macOS and Linux, particularly highlighting that macOS uses Homebrew for GUI applications and Podman, while Linux can use pure Nix packages for everything. The `isDarwin` and `isLinux` conditions in the configuration determine which components are activated.\n\n```mermaid\ngraph TD\n    subgraph \"Common Components\"\n        NC[Nix Core]\n        HMC[Home Manager]\n        CLI[CLI Tools\u003cbr/\u003eripgrep, fzf, bat, etc.]\n        Dev[Development Tools\u003cbr/\u003egit, nodejs, python]\n    end\n\n    subgraph \"macOS Specific\"\n        HB[Homebrew]\n        Aero[AeroSpace WM]\n        GUI[GUI Apps\u003cbr/\u003eAlfred, Ghostty, etc.]\n        Pod[Podman via Homebrew]\n    end\n\n    subgraph \"Linux Specific\"\n        Pure[Pure Nix Packages]\n        PodNix[Podman via Nix]\n    end\n\n    NC --\u003e HMC\n    HMC --\u003e CLI\n    HMC --\u003e Dev\n\n    HMC --\u003e|isDarwin| HB\n    HMC --\u003e|isDarwin| Aero\n    HB --\u003e GUI\n    HB --\u003e Pod\n\n    HMC --\u003e|isLinux| Pure\n    Pure --\u003e PodNix\n```\n\n## Automation \u0026 Maintenance\n\n### Update Dependencies\n```bash\n# Run the update script to update all flake inputs\n./update.sh\n```\n\nThis script will:\n- Update nixpkgs and home-manager to latest versions\n- Show you what changed\n- Optionally commit the updates with detailed messages\n- Run flake checks to ensure everything works\n\n### Code Quality \u0026 Pre-commit Hooks\n\nThis repository uses [pre-commit](https://pre-commit.com/) to ensure code quality and consistency.\n\n#### Installed Hooks\n- **nixpkgs-fmt**: Automatically formats `.nix` files to the standard style\n- **shellcheck**: Lints shell scripts for common errors and best practices\n- **trailing-whitespace**: Removes unnecessary whitespace at line endings\n- **end-of-file-fixer**: Ensures all files end with a newline\n- **check-merge-conflict**: Prevents committing merge conflict markers\n- **gitleaks**: Scans for hardcoded secrets and credentials\n\n#### Usage\n```bash\n# Hooks run automatically on git commit\ngit commit -m \"Your message\"\n\n# Run hooks manually on all files\npre-commit run --all-files\n\n# Run a specific hook\npre-commit run nixpkgs-fmt\n\n# Update hook versions\npre-commit autoupdate\n\n# Skip hooks temporarily (not recommended)\ngit commit --no-verify -m \"Emergency fix\"\n```\n\n### Code Formatting\n```bash\n# Format all Nix files\nnix fmt\n\n# Check formatting without changes\nnix fmt -- --check\n```\n\n### Run Checks\n```bash\n# Run all flake checks\nnix flake check\n\n# Show flake metadata\nnix flake metadata\n```\n\n## Common Workflows\n\n### Daily Development\n```bash\n# Start your day - enter the development environment\nnix develop\n\n# Your shell will have all tools available\n# Fastfetch runs automatically on first shell\n```\n\n### Making Configuration Changes\n```bash\n# Edit configuration files\nvim home/home.nix              # Home Manager config\nvim home/modules/packages.nix  # Nix packages\nvim home/modules/zsh.nix       # Shell config\nvim Brewfile                   # macOS apps\n\n# Apply changes\n./sync-hm.sh\n\n# For Brewfile changes\nbrew bundle\n```\n\n### Checking Home Manager News\n```bash\n# View Home Manager news (updates, breaking changes, new features)\nhome-manager news --flake \".#user@aarch64-darwin\" --impure\n\n# For Linux:\nhome-manager news --flake \".#user@x86_64-linux\" --impure\n```\n\n### Updating Packages\n```bash\n# Update all Nix packages (recommended method)\n./update.sh\n\n# Or manually:\nnix flake update\n./sync-hm.sh\n\n# Update Homebrew packages\nbrew update \u0026\u0026 brew upgrade\nbrew bundle  # Ensure Brewfile apps are installed\n```\n\n### Adding New Tools\n```bash\n# For CLI tools (cross-platform)\n# Edit flake.nix or home/modules/packages.nix\n# Add package name to the list\n\n# For macOS GUI apps\n# Edit Brewfile\n# Add: cask \"app-name\"\n# Run: brew bundle\n```\n\n## File Structure\n\n```\n.\n├── flake.nix                 # Main Nix configuration with formatter \u0026 checks\n├── flake.lock               # Locked dependencies\n├── home/\n│   ├── home.nix            # Home Manager entry point\n│   ├── modules/\n│   │   ├── packages.nix    # Nix packages for home\n│   │   ├── zsh.nix        # Shell configuration with P10k\n│   │   └── neovim.nix     # Neovim config with LazyVim\n│   └── systems/\n│       └── default.nix    # System-specific configurations\n├── dotfiles/\n│   └── .p10k.zsh          # Powerlevel10k config\n├── config/\n│   └── aerospace.toml    # Aerospace window manager config\n├── docs/\n│   └── podman.md         # Podman setup documentation\n├── .github/\n│   └── workflows/\n│       └── check.yml      # CI/CD checks\n├── Brewfile               # macOS applications\n├── .pre-commit-config.yaml # Pre-commit hooks configuration\n├── setup.sh              # Initial setup script\n├── sync-hm.sh            # Sync Home Manager configuration\n├── update.sh             # Update automation script\n├── .envrc                # Direnv configuration\n├── .gitignore            # Includes .env for secrets\n├── DECISIONS.md          # Architectural decisions log\n├── CLAUDE.md            # Claude AI context file\n└── README.md            # This file\n```\n\n## Troubleshooting\n\n### Home Manager Not Found\n```bash\n# Run the sync script:\n./sync-hm.sh\n```\n\n### LazyVim Not Working\n```bash\n# Clear Neovim cache and plugins\nrm -rf ~/.local/share/nvim\nrm -rf ~/.cache/nvim\nrm -rf ~/.config/nvim/lazy-lock.json\n\n# Rebuild Home Manager configuration\n./sync-hm.sh\n\n# Launch Neovim - LazyVim will auto-install\nnvim\n```\n\n### Zsh/P10k Issues\n```bash\n# To modify p10k configuration:\n# Edit dotfiles/.p10k.zsh directly\n# Then rebuild: ./sync-hm.sh\n```\n\n### Nix Build Failures\n```bash\n# Clear Nix store and rebuild\nnix-collect-garbage -d\nnix flake update\n./sync-hm.sh\n```\n\n### Environment Not Loading\n```bash\n# Ensure direnv is allowed\ndirenv allow\n\n# Manually reload\nnix develop\n```\n\n### Podman Issues on macOS\nPodman is managed via Homebrew on macOS. See [docs/podman.md](docs/podman.md) for setup instructions.\n\n## Security Best Practices\n\n### Secret Management\n- **Never commit secrets** to this repository\n- Use environment variables for API keys and tokens\n- Store secrets in 1Password and use the CLI integration (already configured)\n- For persistent secrets, consider:\n  - `.env` files (git-ignored)\n  - macOS Keychain\n  - 1Password CLI: `op read \"op://vault/item/field\"`\n\n### Flake Configuration Trust\nWhen first using this flake, you'll be prompted to trust the cache configuration. Accept with:\n```bash\nnix flake metadata --accept-flake-config\n```\n\n### Missing Commands\n```bash\n# Check if in Nix shell\nwhich \u003ccommand\u003e\n\n# If not found, ensure you're in nix develop\nexit\nnix develop\n```\n\n## Platform-Specific Notes\n\n### macOS\n- Homebrew handles GUI applications\n- System Integrity Protection may affect some tools\n- Use `mas` for Mac App Store apps\n\n### Linux\n- GUI apps would use apt/snap/flatpak\n- Home directory is automatically detected\n- Some macOS-specific tools won't be available\n\n### Multi-User/Multi-System Support\n- Configuration automatically detects:\n  - Current username via `$USER` environment variable\n  - Home directory via `$HOME` environment variable\n  - System architecture (aarch64-darwin, x86_64-linux)\n- No need to edit configuration files when switching between machines\n- Works seamlessly across different usernames and home directory locations\n- Just run `./sync-hm.sh` on any machine\n\n## CI/CD Integration\n\nThis repository includes GitHub Actions workflows that:\n- Run on every push to `main` and on pull requests\n- Check flake validity across macOS and Linux\n- Verify code formatting\n- Build the development shell for both platforms\n\nThe CI uses [Determinate Systems' Nix actions](https://github.com/DeterminateSystems) for optimal performance.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fricoledan%2Fnix-config","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fricoledan%2Fnix-config","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fricoledan%2Fnix-config/lists"}