Publish local repo state
This commit is contained in:
192
previous_setup.md
Normal file
192
previous_setup.md
Normal file
@@ -0,0 +1,192 @@
|
||||
# NixOS + Home Manager Setup Overview (sam/nixos)
|
||||
|
||||
This document is a practical overview of how this NixOS setup was built and how
|
||||
“dotfiles” are managed, so another AI session (or you later) can replicate it on
|
||||
another machine.
|
||||
|
||||
Repo: `ssh://git@gitea.lab.audasmedia.com.au:2222/sam/nixos.git`
|
||||
|
||||
## Goals of this setup
|
||||
|
||||
- Reproducible NixOS install via flakes (`nixos-rebuild` / `nixos-install`)
|
||||
- Home Manager managed user config (zsh, kitty, nvim config, etc.)
|
||||
- KDE Plasma + Hyprland selectable at SDDM login
|
||||
- Neovim works reliably on NixOS:
|
||||
- config tracked in git
|
||||
- plugins installed via lazy.nvim into a writable directory
|
||||
- avoid writing any lockfiles into `/nix/store` (read-only)
|
||||
|
||||
## High-level architecture
|
||||
|
||||
- System config: `hosts/<host>/configuration.nix`
|
||||
- Hardware config: `hosts/<host>/hardware-configuration.nix`
|
||||
- generated per-machine during install, then committed
|
||||
- Home Manager (as NixOS module): `home/sam/home.nix`
|
||||
- Neovim config stored in repo: `home/sam/nvim/...`
|
||||
|
||||
### Repo structure (typical)
|
||||
- `flake.nix`
|
||||
- `hosts/aspire-laptop/configuration.nix`
|
||||
- `hosts/aspire-laptop/hardware-configuration.nix`
|
||||
- `home/sam/home.nix`
|
||||
- `home/sam/nvim/` (init.lua, lua/, lazy-lock.json from old setup if needed)
|
||||
- `scripts/install-from-iso.sh`
|
||||
|
||||
## Installation procedure (wipe disk)
|
||||
|
||||
### BIOS notes
|
||||
- Secure Boot disabled on the Acer test laptop for easiest install.
|
||||
(If Secure Boot is locked by a BIOS Supervisor password, bare-metal install may
|
||||
be blocked; use a VM test instead.)
|
||||
|
||||
### From the NixOS graphical ISO (live environment)
|
||||
1. Connect to the internet.
|
||||
2. Clone repo to the live environment:
|
||||
- `git clone ssh://git@gitea.lab.audasmedia.com.au:2222/sam/nixos.git /tmp/nixos`
|
||||
|
||||
3. Partition/mount (WIPES DISK):
|
||||
- Identify disk (e.g. `/dev/sda` or `/dev/nvme0n1`)
|
||||
- Run:
|
||||
- `sudo DISK=/dev/<disk> bash /tmp/nixos/scripts/install-from-iso.sh`
|
||||
|
||||
This creates:
|
||||
- EFI partition (vfat)
|
||||
- Btrfs root with subvolumes `@` and `@home`
|
||||
- Mounts under `/mnt` and generates `/mnt/etc/nixos/hardware-configuration.nix`
|
||||
|
||||
4. Copy repo into target:
|
||||
- `sudo rm -rf /mnt/etc/nixos`
|
||||
- `sudo mkdir -p /mnt/etc`
|
||||
- `sudo cp -a /tmp/nixos /mnt/etc/nixos`
|
||||
|
||||
5. Copy generated hardware config into the repo host path:
|
||||
- `sudo cp -f /mnt/etc/nixos/hardware-configuration.nix /mnt/etc/nixos/hosts/<host>/hardware-configuration.nix`
|
||||
|
||||
6. Install:
|
||||
- `sudo nixos-install --flake /mnt/etc/nixos#<host>`
|
||||
- reboot
|
||||
|
||||
### After first boot
|
||||
- Set password for `sam` if needed:
|
||||
- `sudo passwd sam`
|
||||
- If using Tailscale:
|
||||
- `sudo tailscale up`
|
||||
|
||||
## SSH access (to administer remotely)
|
||||
|
||||
This setup enabled OpenSSH server via NixOS config.
|
||||
|
||||
- `services.openssh.enable = true;`
|
||||
- `services.openssh.openFirewall = true;`
|
||||
- Password auth was enabled for convenience in testing (not best practice).
|
||||
|
||||
To apply:
|
||||
- `sudo nixos-rebuild switch --flake /etc/nixos#<host>`
|
||||
|
||||
## “Dotfiles” / config management approach (what we actually did)
|
||||
|
||||
### The key rule
|
||||
Home Manager symlinks managed files into `/nix/store` (read-only). That is fine
|
||||
for config files, but NOT fine for files that apps need to write to at runtime.
|
||||
|
||||
### Neovim (special case)
|
||||
Neovim + lazy.nvim expects to write:
|
||||
- lockfile
|
||||
- plugin installs
|
||||
- cache/state
|
||||
|
||||
So:
|
||||
|
||||
1) The Neovim config code is kept in git and linked by Home Manager, but we do
|
||||
NOT have HM own the entire `~/.config/nvim` directory.
|
||||
|
||||
We link only:
|
||||
- `~/.config/nvim/init.lua`
|
||||
- `~/.config/nvim/lua/`
|
||||
|
||||
Example Home Manager linking (conceptual):
|
||||
- `xdg.configFile."nvim/init.lua".source = ./nvim/init.lua;`
|
||||
- `xdg.configFile."nvim/lua".source = ./nvim/lua;`
|
||||
|
||||
2) lazy.nvim is configured to write lockfile into a writable location:
|
||||
- lockfile path: `vim.fn.stdpath("data") .. "/lazy-lock.json"`
|
||||
(=> `~/.local/share/nvim/lazy-lock.json`)
|
||||
|
||||
3) Plugins are installed by lazy.nvim into:
|
||||
- `~/.local/share/nvim/lazy/`
|
||||
|
||||
4) After a new install / new machine, bootstrap plugins with:
|
||||
- `nvim --headless "+Lazy! sync" "+qa"`
|
||||
|
||||
### Why we avoided Nix-managed Neovim plugins in HM
|
||||
If `programs.neovim.plugins = ...` is used, Neovim may load plugins from a
|
||||
read-only Nix “vim pack dir” under `/nix/store/...`.
|
||||
Some plugins (notably treesitter) try to write build artifacts into the plugin
|
||||
directory, which fails on read-only paths.
|
||||
|
||||
Therefore:
|
||||
- Nix installs `nvim` + dependencies (node/python/rg/fd/compilers).
|
||||
- lazy.nvim installs the plugins at runtime into user-writable dirs.
|
||||
|
||||
### Other tools
|
||||
Most other CLI tools can be installed declaratively via NixOS or Home Manager.
|
||||
Their configs can be safely managed by HM as symlinks (read-only is fine).
|
||||
|
||||
## Notable fixes/decisions made during setup
|
||||
|
||||
- If you see errors like “Read-only file system” writing `lazy-lock.json`,
|
||||
it means HM is managing the lockfile path. Fix by moving lockfile to data dir
|
||||
and not linking `lazy-lock.json` into `/nix/store`.
|
||||
|
||||
- Treesitter module name mismatch was fixed in config to handle upstream changes:
|
||||
attempt `require("nvim-treesitter.config")` and fallback to
|
||||
`require("nvim-treesitter.configs")`.
|
||||
|
||||
- Avante was disabled on low-power machines by removing/renaming its plugin spec
|
||||
file so lazy.nvim does not load it.
|
||||
|
||||
- Git remote update issues were resolved using:
|
||||
- `git fetch origin`
|
||||
- `git pull --rebase origin main`
|
||||
- `git push`
|
||||
|
||||
## Adding programs (basic workflow)
|
||||
|
||||
### System-wide packages
|
||||
Edit:
|
||||
- `hosts/<host>/configuration.nix`
|
||||
Add to:
|
||||
- `environment.systemPackages = with pkgs; [ ... ];`
|
||||
Apply:
|
||||
- `sudo nixos-rebuild switch --flake /etc/nixos#<host>`
|
||||
|
||||
### User-only packages
|
||||
Edit:
|
||||
- `home/sam/home.nix`
|
||||
Add to:
|
||||
- `home.packages = with pkgs; [ ... ];`
|
||||
Apply:
|
||||
- `sudo nixos-rebuild switch --flake /etc/nixos#<host>`
|
||||
|
||||
### Then commit + push
|
||||
- `cd /etc/nixos`
|
||||
- `git add -A`
|
||||
- `git commit -m "..." && git push`
|
||||
|
||||
## Secrets (do not put in git)
|
||||
Do not commit API keys (Gemini/OpenAI/etc.) into this repo.
|
||||
|
||||
Preferred:
|
||||
- store secrets outside git (password manager) and export into your shell
|
||||
- or use a secret manager like `sops-nix` later
|
||||
|
||||
Example (local-only) environment file:
|
||||
- `~/.config/environment.d/10-secrets.conf`
|
||||
- contains `GEMINI_API_KEY=...`
|
||||
- not tracked in git
|
||||
|
||||
## References
|
||||
- NixOS Manual: https://nixos.org/manual/nixos/stable/
|
||||
- Home Manager Manual: https://nix-community.github.io/home-manager/
|
||||
- Flakes: https://nixos.wiki/wiki/Flakes
|
||||
- Packages/options search: https://search.nixos.org/
|
||||
Reference in New Issue
Block a user