From 000e285d283c4eb6dd5c41055ffb856a88288fd3 Mon Sep 17 00:00:00 2001 From: swaphb Date: Wed, 8 Jan 2025 00:38:00 -0500 Subject: [PATCH] Readme updates --- README.md | 303 +++++++++++++----------------------------------------- 1 file changed, 70 insertions(+), 233 deletions(-) diff --git a/README.md b/README.md index 5ea4b0b..fdb1b69 100644 --- a/README.md +++ b/README.md @@ -6,14 +6,70 @@ This repository contains a multi-host, multi-user Darwin system configuration us The flake configuration is designed to support multiple hosts and users with specific configurations for each. It uses let-bindings and strict commas for better readability and maintainability. -## Structure +These variables can then be used throughout the flake configuration to customize settings for each host and user. -- **Host Variables**: Define host-specific settings such as hostname, architecture, and home directory. -- **User Variables**: Define user-specific settings such as username, home directory, and shell. -- **Base Darwin Config Function**: A reusable function to set up base configurations for each host. -- **Host Configurations**: Specific configurations for each host, including `nix-darwin` and `home-manager` modules. +## License -## Usage +This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details. + +## Table of Contents + +- [Overview](#overview) +- [Requirements](#requirements) +- [Modules](#modules) +- [How to Use](#how-to-use) +- [Building and Switching](#building-and-switching) +- [Common Commands](#common-commands) +- [Troubleshooting](#troubleshooting) +- [Dirty Git Tree](#dirty-git-tree) +- [Path Does Not Exist](#path-does-not-exist) +- [References](#references) + +## Overview + +- **nix-darwin**: Brings the power of Nix on macOS for system-wide configurations. +- **Home Manager**: Manages user-level configuration (dotfiles, shells, packages) using Nix. +- **nix-homebrew**: Allows declarative management of Homebrew (including taps, casks, etc.) via Nix. + +By splitting the configuration into multiple files under `./modules/`, each file focuses on a specific area (e.g., system packages, services, dotfiles, etc.). + +## Requirements + +- **Nix**: You need Nix installed. +- **nix-darwin**: The Darwin modules rely on nix-darwin. +- **Git**: This is a Flake-based workflow, so your configuration should be in a Git repository. + +After installing Nix, you can install nix-darwin (one recommended approach is from the official Nix-Darwin docs). + +## Modules +- **flake.nix**: The top-level file defining all inputs (nixpkgs, nix-darwin, home-manager, nix-homebrew) and outputs (your nix-darwin configuration). Imports each module (e.g., `./modules/darwin/homebrew.nix`) into `darwinConfigurations..modules`. +- **modules/darwin/apps/**: + - `homebrew.nix`: Holds Homebrew-related configurations (brew packages, casks, etc.). + - `nixpackages.nix`: Holds your `environment.systemPackages`. + - `services.nix`: Configures system services (e.g., Tailscale, nix-daemon, security/pam). + - `default.nix`: Aggregates all .nix files in the directory for easier reference by the flake. +- **modules/darwin/security/**: + - `default.nix`: Consolidated configurations for security related settings. +- **modules/darwin/system/**: + - `appearance.nix`: Appearance related settings (e.g., dock, interface, login window settings, etc ). + - `finder.nix`: Finder related customizations. + - `system.nix`: System configuration (e.g., trackpad, keyboard mapping, screenshot default location, etc...). + - `default.nix`: Aggregates all .nix files in directory for easier reference by the flake +- **modules/home/**: + - `/dotfiles.nix`: Holds user-level dotfiles managed by Home Manager (e.g., `~/.gitconfig`, `~/.ssh/config`). +- **rebuild.sh**: A convenience script that typically runs something like: + ```sh + #!/usr/bin/env bash + darwin-rebuild switch --flake .# + ``` + +## How to Use + +In the `flake.nix` file, you can define host-specific and user-specific variables using let-bindings. Examples shown in the `flake.nix` file. + +To add a new host or user, update the `hostVars` and `userVars` sections in the `flake.nix` file with the new configurations. Follow the existing structure to ensure consistency. + +Execution: 1. **Clone the repository**: ```sh @@ -40,233 +96,6 @@ The flake configuration is designed to support multiple hosts and users with spe Replace `` with the actual hostname defined in the `flake.nix` file (e.g., `swaphb-mba`). -## Adding New Hosts or Users - -To add a new host or user, update the `hostVars` and `userVars` sections in the `flake.nix` file with the new configurations. Follow the existing structure to ensure consistency. - -## Example: Setting Variables in the Flake File - -In the `flake.nix` file, you can define host-specific and user-specific variables using let-bindings. Here is an example: - -```nix -let - ################################### - # 1. Host variables - ################################### - hostVars = { - host1 = { - hostname = "swaphb-mba"; - arch = "aarch64-darwin"; - homeDirectory = "/Users/stephen"; - }; - host2 = { - hostname = "example"; - arch = "aarch64-darwin"; - homeDirectory = "/Users/example"; - }; - }; - - ################################### - # 2. User variables - ################################### - userVars = { - userA = { - username = "stephen"; - homeDirectory = "/Users/stephen"; - shell = "zsh"; - }; - userB = { - username = "example"; - homeDirectory = "/Users/example"; - shell = "fish"; - }; - }; -in -{ - // ...existing code... -} -``` - -These variables can then be used throughout the flake configuration to customize settings for each host and user. - -## License - -This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details. - -## Table of Contents - -- [Overview](#overview) -- [Requirements](#requirements) -- [Repository Layout](#repository-layout) -- [Key Modules](#key-modules) -- [How to Use](#how-to-use) -- [Building and Switching](#building-and-switching) -- [Common Commands](#common-commands) -- [Troubleshooting](#troubleshooting) -- [Dirty Git Tree](#dirty-git-tree) -- [Path Does Not Exist](#path-does-not-exist) -- [References](#references) - -## Overview - -- **nix-darwin**: Brings the power of Nix on macOS for system-wide configurations. -- **Home Manager**: Manages user-level configuration (dotfiles, shells, packages) using Nix. -- **nix-homebrew**: Allows declarative management of Homebrew (including taps, casks, etc.) via Nix. - -By splitting the configuration into multiple files under `./modules/`, each file focuses on a specific area (e.g., system packages, services, dotfiles, etc.). - -## Requirements - -- **Nix**: You need Nix installed. -- **nix-darwin**: The Darwin modules rely on nix-darwin. -- **Git**: This is a Flake-based workflow, so your configuration should be in a Git repository. - -After installing Nix, you can install nix-darwin (one recommended approach is from the official Nix-Darwin docs). - -## Repository Layout - -A typical directory structure might look like this: - -``` -. -├── flake.nix -├── modules -│ ├── darwin -│ │ ├── homebrew.nix -│ │ ├── nixpackages.nix -│ │ └── services.nix -│ └── home -│ └── -│ └── dotfiles.nix -├── rebuild.sh -└── README.md -``` - -- **flake.nix**: The top-level file defining all inputs (nixpkgs, nix-darwin, home-manager, nix-homebrew) and outputs (your nix-darwin configuration). Imports each module (e.g., `./modules/darwin/homebrew.nix`) into `darwinConfigurations..modules`. -- **modules/darwin/**: - - `homebrew.nix`: Holds Homebrew-related configurations (brew packages, casks, etc.). - - `nixpackages.nix`: Holds your `environment.systemPackages`. - - `services.nix`: Configures system services (e.g., Tailscale, nix-daemon, security/pam). -- **modules/home/**: - - `/dotfiles.nix`: Holds user-level dotfiles managed by Home Manager (e.g., `~/.gitconfig`, `~/.ssh/config`). -- **rebuild.sh**: A convenience script that typically runs something like: - ```sh - #!/usr/bin/env bash - darwin-rebuild switch --flake .# - ``` - Replace `` with your actual hostname if needed. - -## Key Modules - -1. **modules/darwin/homebrew.nix** - - ```nix - { config, pkgs, lib, ... }: - - { - homebrew = { - enable = true; - onActivation.cleanup = "uninstall"; - taps = []; - brews = [ - "cowsay" # install brews - "git" - "k9s" - "helm" - "podman" - "podman-compose" - ]; - casks = [ - "1password" # install casks - "podman-desktop" - "teleport-connect" - "utm" - "localsend" - ]; - masApps = { - "1Password for Safari" = 1569813296; # install Mac Appstore apps! - "wireguard" = 1451685025; - "wipr" = 1320666476; - }; - }; - } - ``` - -2. **modules/darwin/nixpackages.nix** - - ```nix - { config, pkgs, ... }: - - { - environment.systemPackages = with pkgs; [ - vim # Install packages from nix package store - lens - vscode - spotify - slack - kubectl - discord - _1password-cli - brave - teleport - tenv - google-cloud-sdk - awscli - azure-cli - go - starship - ]; - } - ``` - -3. **modules/darwin/services.nix** - - ```nix - { config, pkgs, ... }: - - { - services = { - nix-daemon.enable = true; - tailscale.enable = true; # Install and enable tailscale - }; - - security.pam.enableSudoTouchIdAuth = true; - } - ``` - -4. **modules/home/dotfiles.nix** - - ```nix - { config, pkgs, lib, ... }: - - { - home.file = { - ".ssh/config".text = '' - Host * - IdentityAgent "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock" # enables 1password ssh agent integration - ''; - - ".gitconfig".text = '' - [user] - name = - email = - signingkey = - - [gpg] - format = ssh - - [gpg "ssh"] - program = "/Applications/1Password.app/Contents/MacOS/op-ssh-sign" # Specify gpg sign key location, This uses 1password's provider. - - [commit] - gpgSign = true - ''; - }; - } - ``` - -## How to Use - ## Building and Switching 1. Clone this repo (or ensure you have your local copy). @@ -302,6 +131,14 @@ which should do the same command under the hood. ```sh nix flake show ``` +- **Build with switching** + ```sh + darwin-rebuild switch --flake .# + ``` +- **Update upstream flakes** + ```sh + nix flake update + ``` ## Troubleshooting