diff options
| -rw-r--r-- | INSTALL.md | 224 | ||||
| -rw-r--r-- | README.md | 29 |
2 files changed, 244 insertions, 9 deletions
diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..c00cc23 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,224 @@ +# Installation + +Full setup guide, from a freshly unboxed machine to a working environment. +For the short version, see [README.md](README.md). + +- [macOS (nix-darwin)](#macos-nix-darwin) +- [NixOS](#nixos) +- [Linux (standalone home-manager)](#linux-standalone-home-manager) +- [Day-to-day](#day-to-day) +- [Troubleshooting](#troubleshooting) + +## macOS (nix-darwin) + +### 1. Xcode Command Line Tools + +Needed for `git` and the system toolchain before Nix is in place. + +```shell +xcode-select --install +``` + +Sign in to the **App Store** now as well — `mas` installs the App Store apps +during the first switch and fails if no account is signed in. + +### 2. Install Determinate Nix + +```shell +curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install --determinate +``` + +`--determinate` matters: `modules/darwin/default.nix` sets `nix.enable = false`, +which hands Nix management to the Determinate installer instead of nix-darwin. +Installing plain upstream Nix here leaves the daemon unmanaged. + +Open a new shell afterwards so `nix` is on `PATH`. + +### 3. Install Homebrew + +nix-darwin declares Homebrew packages but does **not** install Homebrew itself. +The first switch fails without it. + +```shell +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +eval "$(/opt/homebrew/bin/brew shellenv)" +``` + +### 4. Clone the repository + +The clone path is not arbitrary — the `rebuild` and `update` aliases in +`modules/home/zsh.nix` point at `~/ghq/github.com/simenandre/dotfiles`, so +clone it there. + +```shell +mkdir -p ~/ghq/github.com/simenandre +git clone https://github.com/simenandre/dotfiles.git ~/ghq/github.com/simenandre/dotfiles +cd ~/ghq/github.com/simenandre/dotfiles +``` + +HTTPS on purpose: SSH access depends on 1Password's SSH agent, which is not +installed yet. After the first switch, git rewrites GitHub HTTPS remotes to SSH +(`url."ssh://git@github.com/".insteadOf`), so this remote keeps working. + +### 5. First switch (bootstrap nix-darwin) + +```shell +sudo nix run nix-darwin#darwin-rebuild -- switch --flake .#default +``` + +This is the long one: it installs every Homebrew cask, the Mac App Store apps, +all nixpkgs packages, and applies the macOS defaults. Expect Homebrew to prompt +for your password, and expect to approve a few system dialogs. + +Subsequent switches use the installed binary: + +```shell +sudo darwin-rebuild switch --flake .#default +``` + +Restart the terminal (or log out and back in) so the new zsh config, `PATH`, and +Ghostty configuration take effect. + +### 6. 1Password and SSH + +Git commits are signed through 1Password's SSH agent +(`/Applications/1Password.app/Contents/MacOS/op-ssh-sign`), so this has to be +set up before committing anything. + +1. Open **1Password**, sign in, and unlock it. +2. Settings → Developer → enable **Use the SSH agent**. +3. Settings → Developer → enable **Integrate with 1Password CLI** (for `op`). +4. Verify the signing key matches the one pinned in `modules/home/git.nix`: + + ```shell + ssh-add -l + ``` + +5. Confirm GitHub over SSH works: + + ```shell + ssh -T git@github.com + ``` + +### 7. Sign in to the rest + +Each of these is a one-time manual login: + +```shell +gh auth login # GitHub CLI +op signin # 1Password CLI +gcloud auth login # Google Cloud +gcloud auth application-default login +``` + +GUI apps that need a login or permission grant: Tailscale (App Store), Slack, +Discord, Signal, Obsidian, Proton Mail, ProtonVPN, Spotify, Raycast (grant +Accessibility), Google Drive. + +### 8. Container runtime + +Docker CLIs come from Homebrew, but the VM has to be started once: + +```shell +colima start +``` + +`DOCKER_HOST` is already pointed at `~/.colima/default/docker.sock` by +`modules/home/zsh.nix`. + +### 9. Rust toolchain + +`rustup` is installed, but ships without a toolchain: + +```shell +rustup default stable +``` + +### 10. Tools not managed by Nix + +These are installed with `go install` and live in `~/go/bin`. Shell completions +for them are generated on every switch, and the generator quietly skips any that +are missing: + +```shell +go install github.com/sokkelorg/cli/cmd/so@latest +go install github.com/simenandre/bobbin/cmd/bobbin@latest +go install github.com/simenandre/robin-cli/cmd/robin@latest +go install github.com/dinacomputer/api/cmd/dinactl@latest +go install github.com/sokkelorg/identity/cmd/identityctl@latest +``` + +### 11. Loose ends + +```shell +mkdir -p ~/Screenshots # macos.nix points screencapture here; it is not created for you +``` + +`~/.gitignore_global` is referenced by `core.excludesfile` but is not managed by +this repo. Create it if you want it: + +``` +.DS_Store +.twm.yaml +.twm.yml + +**/.claude/settings.local.json +``` + +Some macOS defaults (Dock, Finder, trackpad) only take effect after a logout or +restart. + +## NixOS + +```shell +sudo nixos-generate-config --show-hardware-config > hosts/nixbox/hardware-configuration.nix +sudo nixos-rebuild switch --flake .#nixbox +``` + +The `nixbox` host expects the user `simenandre`. Git commit signing is disabled +outside macOS, so no 1Password setup is required. + +## Linux (standalone home-manager) + +```shell +# x86_64 +home-manager switch --flake .#simenandre + +# aarch64 +home-manager switch --flake .#simenandre@aarch64-linux +``` + +## Day-to-day + +Aliases defined in `modules/home/zsh.nix` (macOS): + +| Alias | Does | +| --------- | ------------------------------------------------- | +| `rebuild` | `darwin-rebuild switch` against this flake | +| `update` | `nix flake update`, then rebuild | +| `nix-gc` | Garbage-collect store paths older than 14 days | + +`scripts/cleanup.sh` is a separate macOS cleanup utility (caches, logs, trash). + +## Troubleshooting + +**`error: Homebrew is not installed`** — step 3 was skipped, or `brew` is not on +`PATH` for the shell running the switch. Run `eval "$(/opt/homebrew/bin/brew shellenv)"`. + +**Mac App Store apps fail to install** — sign in to the App Store, then re-run +the switch. `mas` cannot authenticate on its own. + +**home-manager refuses to overwrite an existing file** — files it would clobber +are backed up with a `.bak` suffix (`backupFileExtension = "bak"`). If a switch +still fails on a collision, a stale `.bak` from an earlier run is usually in the +way; delete it and re-run. + +**A cask fails to install because the app already exists** — remove the +hand-installed copy from `/Applications` and re-run the switch. + +**`warning: failed to generate _<tool>`** during activation — that tool is not +installed (see step 10). Harmless; only its completions are missing. + +**A `nixpkgs` package suddenly fails to build** — check `flake.lock`. Pinned +overrides live in `modules/darwin/default.nix` (for example WhatsApp's version +and hash). @@ -4,17 +4,21 @@ My Development Setup, managed with [Nix](https://nixos.org), [nix-darwin](https: ## Quickstart -### 1. Install Nix +Setting up a new machine? Follow [INSTALL.md](INSTALL.md) — it covers the +prerequisites (Homebrew, App Store, 1Password SSH agent) that the commands below +assume are already in place. + +### 1. Install Determinate Nix ```shell -curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install +curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install --determinate ``` ### 2. Clone the repository ```shell -git clone git@github.com:simenandre/dotfiles.git ~/dotfiles -cd ~/dotfiles +git clone https://github.com/simenandre/dotfiles.git ~/ghq/github.com/simenandre/dotfiles +cd ~/ghq/github.com/simenandre/dotfiles ``` ### 3. Apply the configuration @@ -24,13 +28,13 @@ cd ~/dotfiles On first run, bootstrap nix-darwin: ```shell -nix run nix-darwin -- switch --flake .#default +sudo nix run nix-darwin#darwin-rebuild -- switch --flake .#default ``` On subsequent runs: ```shell -darwin-rebuild switch --flake .#default +sudo darwin-rebuild switch --flake .#default ``` #### NixOS @@ -38,7 +42,7 @@ darwin-rebuild switch --flake .#default Generate hardware config and rebuild: ```shell -sudo nixos-generate-config --show-hardware-config > modules/nixos/hardware-configuration.nix +sudo nixos-generate-config --show-hardware-config > hosts/nixbox/hardware-configuration.nix sudo nixos-rebuild switch --flake .#nixbox ``` @@ -56,17 +60,24 @@ home-manager switch --flake .#simenandre@aarch64-linux ``` flake.nix # Entry point – inputs & all configurations +INSTALL.md # Full setup guide for a new machine +hosts/ + nixbox/ + hardware-configuration.nix modules/ darwin/ - default.nix # System-level configuration (nix settings, core packages) + default.nix # System-level configuration (nix settings, core packages) homebrew.nix # Homebrew packages (taps, brews, casks, Mac App Store) macos.nix # macOS system defaults home/ default.nix # home-manager entry point (platform-aware home directory) + claude.nix # Claude Code instructions and skills git.nix # Git configuration (platform-aware SSH signing path) - zsh.nix # Zsh configuration (zshenv, zshrc, aliases, path, extras) + zsh.nix # Zsh configuration (zshenv, zshrc, aliases, path, completions) starship.nix # Starship prompt tmux.nix # Tmux configuration + lazygit.nix # Lazygit configuration + twm.nix # twm workspace manager configuration ghostty.nix # Ghostty terminal configuration nixos/ default.nix # NixOS system configuration |