Skip to content

README.md

Latest commit

 

History

History
269 lines (213 loc) · 9.63 KB

README.md

File metadata and controls

269 lines (213 loc) · 9.63 KB
Bleuprint Logo

Nix-Darwin Mac Setup Template

🎯 A template repository for bootstrapping a modern, reproducible Mac development environment with 120+ tools using Nix-Darwin.

Use this template Website Stars Forks

⭐ Star This Repository

If you find bleuprint helpful, please consider starring it! Your stars help others discover this template and motivate continued development.

✨ Features

  • 🚀 One-command setup - Bootstrap a new Mac in ~15 minutes
  • 🔒 Security-first design - Safe for public repos, manual configuration required
  • 📦 120+ modern CLI tools - Including Rust-based replacements for traditional Unix tools
  • 🔄 Fully reproducible - Same command = same environment, every time
  • ⚡ Instant rollbacks - Break something? Roll back in seconds
  • 🎛️ Highly configurable - Modular design makes customization easy
  • 🛡️ Security-first - Git hooks prevent sensitive data leaks, Touch ID sudo, encryption tools

🚀 Quick Start

🏃‍♂️ Ultra-Quick Setup (For the Laziest)

# One-liner: Download and run with sensible defaults
curl -fsSL https://bleulabs.github.io/bleuprint/install.sh | bash

What this does:

  • ✅ Downloads the latest bleuprint template
  • ✅ Installs Nix (if not present)
  • ✅ Sets up all 120+ tools with sensible defaults
  • ✅ Configures modern shell aliases
  • ✅ No manual configuration required!

⚠️ Note: Uses sensible defaults (Developer, dev@example.local, hostname: macbook). For production use with your personal details, follow the template setup below.

📋 Using This Template (Recommended)

  1. Click "Use this template" button above
  2. Clone your new repository
  3. Follow the Setup Guide

🔧 TL;DR for Experienced Users

# After creating from template, clone your new repository
git clone https://github.com/yourusername/your-dotfiles.git
cd your-dotfiles

# 🔒 REQUIRED: Update configuration (for security)
# Option A: Environment file (recommended - keeps sensitive data out of repo)
cp .env.example .env           # Copy template
nano .env                      # Edit with your details
./scripts/load-env-config.sh   # Apply configuration

# Option B: Manual configuration
# nano modules/home/default.nix  # Set Git name/email
# nano flake.nix                 # Set hostname/username

# Optional: Interactive configuration wizard
./scripts/auto-configure.sh

# Bootstrap your Mac
./scripts/bootstrap-mac.sh

# Verify installation
./scripts/smoke-test.sh

⚠️ Security Notice: This template requires manual configuration of personal details. It will NOT automatically write sensitive information like emails or SSH keys to avoid security risks in public repositories.

📁 Repository Structure

.
├── flake.nix                    # Main configuration entry point
├── scripts/                     # Setup and utility scripts
│   ├── bootstrap-mac.sh         # One-click setup script
│   ├── smoke-test.sh            # Verify installation
│   ├── auto-configure.sh        # Interactive configuration wizard
│   └── load-env-config.sh       # Environment-based configuration
├── docs/                        # Documentation files
│   ├── SETUP.md                 # Detailed setup guide
│   ├── CONFIG_OPTIONS.md        # All configuration options
│   └── CLI_CHEATSHEET.md        # Quick reference for tools
├── assets/                      # Images and media files
│   └── image.png                # Bleuprint logo
└── modules/
    ├── system/
    │   ├── core.nix            # Languages, build tools, system settings
    │   ├── cli-utils.nix       # 100+ CLI productivity tools
    │   └── ml-stack.nix        # Optional ML/data science tools
    ├── homebrew/
    │   └── apps.nix            # GUI apps and Mac-specific tools
    └── home/
        ├── default.nix         # User configuration (shell, git, etc.)
        └── aliases.nix         # Configurable modern tool aliases

📦 What's Included

Development Core (modules/system/core.nix)

  • Languages: Go 1.24, Rust (via rustup), Python 3.13, Node.js 22 LTS
  • Build Tools: CMake, Make, Just, Ninja
  • Environment: direnv, nix-direnv
  • System Settings: Touch ID sudo, fast key repeat, Nix hardening (fsync)

CLI Tools (modules/system/cli-utils.nix)

  • Modern Replacements: eza/lsd (ls), bat (cat), fd (find), ripgrep (grep), erd (tree)
  • Productivity: fzf/sk, zoxide, tldr, atuin/mcfly, starship
  • Development: gh, lazygit/gitui, delta, httpie/xh/curlie, jq/yq
  • System Monitoring: btop/bottom, duf, dust, procs, bandwhich
  • Text Processing: sd, gron, choose, grex, hexyl
  • Security: age, sops, gpg, yubikey-manager
  • Containers: act, podman, dive
  • Performance: hyperfine, flamegraph, perf
  • Additional: helix, zellij, broot, silicon, mdbook

GUI Apps (modules/homebrew/apps.nix)

  • Essentials: Raycast, VS Code, OrbStack, Kitty
  • Productivity: Obsidian, Slack, Notion
  • Dev Tools: GitHub Desktop, Insomnia, TablePlus
  • Utilities: Stats, Rectangle, iTerm2, WezTerm
  • Security: 1Password, 1Password CLI

Optional: ML/Data Science Stack (modules/system/ml-stack.nix)

  • Deep Learning: PyTorch, TensorFlow (with Metal support)
  • Data Science: scikit-learn, pandas, numpy, matplotlib
  • Notebooks: Jupyter, IPython
  • Big Data: Apache Spark, DuckDB, Polars
  • Visualization: Plotly

User Config (modules/home/default.nix)

  • Shell: Zsh with syntax highlighting, autosuggestions
  • Git: Delta diffs, useful aliases, better defaults
  • Tmux: Vi mode, better keybindings, mouse support
  • SSH: Connection multiplexing for speed

🔧 Common Commands

# Apply changes after editing
darwin-rebuild switch --flake ".#testhost"

# Rollback to previous generation
darwin-rebuild rollback

# Update all packages
nix flake update
darwin-rebuild switch --flake ".#testhost"

# Search for packages
nix search nixpkgs <package-name>

# Clean old generations
nix-collect-garbage -d

📝 Customization

Enable Modern Tool Replacements

To replace traditional commands with modern alternatives, edit modules/home/default.nix:

# Change from:
programs.modernTools.enable = false;

# To:
programs.modernTools.enable = true;

This will set up aliases like:

  • ls → eza --icons
  • cat → bat
  • grep → rg
  • find → fd
  • top → btop
  • df → duf
  • du → dust
  • And more...

Add a CLI tool

Edit modules/system/cli-utils.nix:

environment.systemPackages = with pkgs; [
  # ... existing packages ...
  your-new-tool  # https://link-to-docs.com
];

Add a GUI app

Edit modules/homebrew/apps.nix:

casks = [
  # ... existing casks ...
  "your-app-name"
];

Change shell aliases

Edit modules/home/default.nix:

shellAliases = {
  # ... existing aliases ...
  myalias = "my-command";
};

Enable ML/Data Science Stack

Edit flake.nix to add the ML module:

modules = [
  ./modules/system/core.nix
  ./modules/system/cli-utils.nix
  ./modules/system/ml-stack.nix  # Add this line
  ./modules/homebrew/apps.nix
  # ...
];

🔗 Quick Links

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📄 License

This template is available under the MIT License - see LICENSE for details.

🙏 Acknowledgments

  • Nix-Darwin for the excellent macOS Nix integration
  • Home Manager for user environment management
  • The Nix community for amazing packages and support

💡 Pro Tips

  • Use tldr <command> for quick command examples
  • z <partial-path> to jump to directories (via zoxide)
  • Ctrl+R for fuzzy history search (via fzf)
  • lazygit for visual Git operations
  • btop for beautiful system monitoring
  • Run ./test-modern-tools.sh to see your current configuration

Made with ❤️ for the Mac development community
⭐ Star this repo • 🐛 Report an issue • 💬 Discussions