1#+TITLE: =home= monorepo
  2#+FILETAGS: #home infra configuration dotfiles monorepo
  3
  4A comprehensive monorepo containing personal infrastructure, system
  5configurations, and tools, primarily built using [[https://nixos.org/nix][Nix]].
  6
  7* Overview
  8
  9This repository serves as a centralized location for:
 10- NixOS system configurations for multiple machines
 11- Home-manager configurations
 12- Custom tools and personal configurations
 13- Infrastructure management
 14
 15See [[file:CLAUDE.md][CLAUDE.md]] for Claude Code-specific guidance on working with this repository.
 16
 17* Repository Structure
 18
 19** =/systems=
 20Contains NixOS system configurations organized as follows:
 21- Individual host configurations (aix, aomi, athena, demeter, kyushu, sakhalin, rhea, kerkouane, etc.)
 22- Common configurations shared across systems:
 23  + Base system setup
 24  + Desktop environments (Sway, Niri)
 25  + Hardware-specific configurations
 26  + Program configurations
 27  + Service configurations
 28  + User management
 29
 30** =/home=
 31Home-manager configurations for different users and environments:
 32- Common configurations for desktop environments
 33- Development tools and settings:
 34  + AI tooling configuration (aichat, AI prompts/roles)
 35  + Go, Python, Nix development environments
 36  + Emacs configuration
 37  + Container tooling
 38- Shell configurations (zsh, tmux, etc.)
 39- Service configurations (syncthing, etc.)
 40
 41** =/dots=
 42Traditional dotfiles managed outside of home-manager:
 43- Niri window manager configuration
 44- Makefile-based dotfile installation system
 45- Additional application-specific configurations
 46
 47** =/tools=
 48Custom tools and utilities:
 49- DNS management scripts (show-dns.sh, update-gandi-dns.sh)
 50- Media management (arr CLI for *arr services, music-playlist-dl for podcasts)
 51- GitHub tools (gh-pr for pull request management, claude-hooks for Claude Code)
 52- System utilities (battery-monitor, cliphist-cleanup, toggle-color-scheme)
 53- Content tools (download-kiwix-zim for offline Wikipedia)
 54- Emacs configuration and org-mode utilities (org-manager)
 55
 56See [[file:tools/README.org][tools/README.org]] for detailed tool documentation.
 57
 58** =/pkgs=
 59Custom Nix packages and overlays including:
 60- Development tools (govanityurl, manifest-tool)
 61- System utilities (battery-monitor, systemd-email, vrsync)
 62- Custom scripts and utilities (ape, ram, batzconverter)
 63- Emacs packages
 64
 65** =/modules=
 66NixOS modules providing additional functionality:
 67- Wireguard client/server configurations
 68- Go vanity URL service
 69- Gosmee service
 70
 71** =/lib=
 72Core library functions for flake configuration:
 73- =mkHost= - Generate NixOS configurations
 74- =mkHome= - Generate home-manager configurations
 75- =mkSystemManager= - Generate system-manager configurations
 76- Helper functions for configuration building
 77
 78** =/overlays=
 79Nix overlays for:
 80- Custom package additions
 81- Package modifications
 82- Unstable package access
 83
 84** =/keyboards=
 85Hardware keyboard configurations with complete build and flash tooling.
 86
 87See [[file:keyboards/README.org][keyboards/README.org]] for detailed keyboard documentation and usage.
 88
 89*** Moonlander
 90Located in =/keyboards/moonlander=:
 91- QMK-based configuration for the ZSA Moonlander keyboard
 92- 72-key split ergonomic keyboard with RGB backlighting
 93- Wired USB-C connectivity
 94- See [[file:keyboards/moonlander/README.org][keyboards/moonlander/README.org]] for full documentation
 95
 96*** Eyelash Corne
 97Located in =/keyboards/eyelash_corne=:
 98- ZMK-based configuration for the wireless Corne (crkbd) keyboard
 99- 42-key split ergonomic keyboard with nice!view display
100- Wireless Bluetooth connectivity with nice!nano v2
101- RGB underglow and custom animations
102- See [[file:keyboards/eyelash_corne/README.org][keyboards/eyelash_corne/README.org]] for full documentation
103
104*** Kanata (software)
105Located in =systems/kyushu/main.kbd=:
106- Software keyboard remapper configuration to mimic mechanical keyboards
107- System-level key remapping for non-keyboard hardware
108
109** =/imperative=
110Idempotent configuration scripts for systems not managed by NixOS, organized by hostname:
111- Each host has its own directory (e.g., =/imperative/nagoya/=)
112- Scripts are designed to be run repeatedly to maintain system state
113- Primary script in each host directory is typically =apply.sh=
114- Used for bootstrapping and ongoing configuration management of non-NixOS systems (Debian, Arch, Windows, etc.)
115
116Examples of hosts that may have imperative configurations:
117- =nagoya= - Debian-based system (server)
118- =wakasu= - Fedora-based system (desktop)
119- Additional systems running operating systems other than NixOS
120
121* Usage
122
123The main entry point is =flake.nix=, which provides:
124
125- NixOS configurations for various hosts
126- Home-manager configurations
127- System-manager configurations
128- Custom packages and overlays
129
130** Building a System
131
132To build and activate a system configuration:
133
134#+begin_src bash
135nixos-rebuild switch --flake .#<hostname>
136#+end_src
137
138** Installing a New System
139
140For new systems that already have a configuration in this repository,
141you can use the =install.sh= script which uses =disko= for disk
142partitioning and installation:
143
144#+begin_src bash
145./install.sh <hostname> [additional-disko-options]
146#+end_src
147
148This will:
1491. Use the disko-install tool to partition and format disks
1502. Install the system configuration for the specified hostname
151
152** Available Make Targets
153
154The repository includes several useful make targets for common operations:
155
156*** System Management
157- =make boot= - Build and boot the current system configuration
158- =make switch= - Build and switch to the new system configuration
159- =make build= - Build the system configuration without activating
160- =make dry-build= - Test build the configuration without making changes
161
162*** Remote Host Management
163- =make host/<hostname>/build= - Build configuration for a specific host
164- =make host/<hostname>/boot= - Build and boot configuration on a remote host
165- =make host/<hostname>/switch= - Build and switch configuration on a remote host
166
167*** Development
168- =make fmt= - Format Nix files using nixpkgs-fmt
169- =make pre-commit= - Run pre-commit checks
170
171*** Keyboards
172- =make keyboards/moonlander/build= - Build Moonlander QMK firmware
173- =make keyboards/moonlander/flash= - Build and flash Moonlander firmware
174- =make keyboards/moonlander/update= - Update QMK submodules
175- =make keyboards/moonlander/clean= - Clean Moonlander build artifacts
176- =make keyboards/eyelash_corne/build= - Build Eyelash Corne ZMK firmware
177- =make keyboards/eyelash_corne/flash= - Build and flash Eyelash Corne firmware
178- =make keyboards/draw= - Generate keymap SVGs for all keyboards
179- =make keyboards/moonlander/draw= - Generate keymap SVG for Moonlander
180- =make keyboards/eyelash_corne/draw= - Generate keymap SVG for Eyelash Corne
181
182See [[file:keyboards/README.org][keyboards/README.org]] for detailed keyboard documentation.
183
184*** DNS Management
185- =make dns-show= - Display DNS zone configuration from NixOS
186- =make dns-update-gandi= - Sync DNS records to Gandi Live DNS
187- =make dns-update-gandi-dry-run= - Preview DNS changes without applying
188
189See [[file:tools/README.org][tools/README.org]] for detailed DNS tool documentation.
190
191*** Media Management (*arr Stack)
192
193Default URLs and API keys (from passage) are configured for =*.sbr.pm= services.
194Override via environment variables or make arguments if needed.
195
196**** Lidarr
197- =make lidarr-rename= - Rename albums in Lidarr with confirmation
198- =make lidarr-rename EXTRA_ARGS="--dry-run"= - Preview album renames
199- =make lidarr-retag= - Retag albums in Lidarr with confirmation
200- =make lidarr-retag EXTRA_ARGS="--dry-run"= - Preview album retags
201- =make lidarr-update-paths= - Update artist paths (requires =LIDARR_ROOT_PATH=)
202
203**** Sonarr
204- =make sonarr-rename= - Rename TV series episodes with confirmation
205- =make sonarr-rename EXTRA_ARGS="--dry-run"= - Preview episode renames
206
207**** Radarr
208- =make radarr-rename= - Rename movies with confirmation
209- =make radarr-rename EXTRA_ARGS="--dry-run"= - Preview movie renames
210
211**** Examples
212#+begin_src bash
213# Use defaults (*.sbr.pm with passage API keys)
214make lidarr-rename
215
216# Dry-run mode
217make sonarr-rename EXTRA_ARGS="--dry-run"
218
219# Override URL and API key (e.g., for local testing)
220make radarr-rename RADARR_URL=http://localhost:7878 RADARR_API_KEY=mykey
221
222# Use --no-confirm flag
223make lidarr-retag EXTRA_ARGS="--no-confirm"
224#+end_src
225
226See [[file:tools/README.org][tools/README.org]] for detailed *arr tool documentation.
227
228*** Maintenance
229- =make clean= - Clean up old system generations and results
230- =make clean-system= - Remove system generations older than 15 days
231- =make clean-results= - Remove symlinks to build results
232- =nix flake update= - Update flake inputs (nixpkgs, home-manager, etc.)
233
234** Updating Home Configuration
235
236To update home-manager configuration:
237
238#+begin_src bash
239home-manager switch --flake .#<username>@<hostname>
240#+end_src
241
242** Managing Dotfiles
243
244For configurations not managed by home-manager, the =/dots= directory
245provides a Makefile-based installation system:
246
247#+begin_src bash
248cd dots
249make all  # Install all dotfiles
250make niri # Install only niri configuration
251#+end_src
252
253** Managing Non-NixOS Systems
254
255For systems not managed by NixOS, the =/imperative= directory provides
256idempotent configuration scripts organized by hostname.
257
258See [[file:imperative/README.org][imperative/README.org]] for detailed documentation.
259
260*** Running Configuration Scripts
261
262#+begin_src bash
263# Apply configuration for a specific host
264sudo ./imperative/<hostname>/apply.sh
265
266# With environment variables (e.g., for wireguard)
267sudo WG_PRIVATE_KEY="..." ./imperative/<hostname>/apply.sh
268#+end_src
269
270*** Available Hosts
271
272**** nagoya (Debian Server)
273#+begin_src bash
274# Configure nagoya with wireguard
275sudo WG_PRIVATE_KEY="your-key" ./imperative/nagoya/apply.sh
276#+end_src
277
278Installs: Docker, Kind, Wireguard, Syncthing
279
280See [[file:imperative/nagoya/README.org][imperative/nagoya/README.org]] for details.
281
282**** wakasu (Fedora Desktop)
283#+begin_src bash
284# Configure wakasu
285sudo ./imperative/wakasu/apply.sh
286
287# With wireguard
288sudo WG_PRIVATE_KEY="your-key" ./imperative/wakasu/apply.sh
289#+end_src
290
291Installs: Helix, ACPI, Wireguard, Syncthing
292
293See [[file:imperative/wakasu/README.org][imperative/wakasu/README.org]] for details.
294
295** Building and Installing Packages
296
297The repository provides various custom packages that can be built and installed directly from the flake:
298
299*** Building a Single Package
300To build a specific package:
301
302#+begin_src bash
303nix build .#<package-name>
304#+end_src
305
306*** Installing a Package
307To install a package in your profile:
308
309#+begin_src bash
310nix profile install .#<package-name>
311#+end_src
312
313*** Available Packages
314All packages are defined in the =/pkgs= directory and are available for both =x86_64-linux= and =aarch64-linux= systems. Notable packages include:
315
316**** Development Tools
317- =battery-monitor= - System battery monitoring utility
318- =govanityurl= - Go vanity URL service
319- =manifest-tool= - Container manifest tool
320- =ape= - Git mirror upstream updater
321- =ram= - Golang opinionated continuous testing tool
322
323**** Chmouzies (Helper Scripts)
324- =chmouzies-ai= - AI-assisted git tools
325- =chmouzies-git= - Git-related helper scripts and GitHub CLI extensions
326- =chmouzies-kubernetes= - Kubernetes and OpenShift helper scripts
327
328**** Claude Code Tools
329- =claude-hooks= - Claude Code hooks for session management, tool output capture, and documentation validation
330- =gh-pr= - GitHub PR management tool for approving, reviewing, and managing pull requests
331
332**** Media and Content Management
333- =arr= - Unified CLI for managing *arr services (Sonarr, Radarr, Lidarr) with Spotify sync support
334- =audible-converter= - Convert Audible AAX files to MP3
335- =download-kiwix-zim= - Browse and download ZIM files from the Kiwix library using fzf
336- =homepage= - Simple HTML homepage listing all services from globals.nix
337- =jellyfin-auto-collections= - Automated collection management for Jellyfin from external lists
338- =music-playlist-dl= - Automated downloader for electronic music podcasts with playlist generation
339
340**** System Utilities
341- =cliphist-cleanup= - Clipboard history cleanup utility
342- =vrsync= - Custom rsync utility
343- =vde-thinkpad= - ThinkPad-specific utilities
344- =systemd-email= - Email notifications for systemd
345- =nixfmt-plus= - Enhanced Nix formatter
346- =batzconverter= - Custom conversion utility
347- =toggle-color-scheme= - Toggle between light and dark color schemes
348
349**** Documentation and Organization
350- =scripts= - Collection of utility scripts for various tasks
351
352**** Emacs Packages
353- =bookmark-plus= - Enhanced bookmarking for Emacs
354
355To list all available packages:
356
357#+begin_src bash
358nix flake show
359#+end_src
360
361* Development
362
363A development shell is provided with necessary tools:
364- Git
365- Prettier
366- Deadnix
367- nixfmt-rfc-style
368- agenix
369
370To enter the development environment:
371
372#+begin_src bash
373nix develop
374#+end_src
375
376Pre-commit hooks are configured for:
377- Go formatting (gofmt)
378- Nix formatting (nixfmt-rfc-style) and linting (deadnix)
379- Python linting (flake8, ruff)
380- Shell script checking (shellcheck)
381
382** Continuous Integration
383
384GitHub Actions workflows automatically:
385- Build all NixOS system configurations
386- Build all custom packages
387- Build keyboard firmware (Corne, Moonlander)
388- Run automated flake updates via Dependabot
389
390* Supported Systems
391
392- =x86_64-linux=
393- =aarch64-linux=
394
395** Current Hosts
396
397*** Desktop Systems (unstable)
398- =kyushu= - Work laptop (Niri desktop)
399- =foobar= - Test VM (Niri desktop)
400
401*** Servers (unstable)
402- =aomi= - Server
403- =sakhalin= - Server
404
405*** Servers (stable, NixOS 25.11)
406- =athena= - Raspberry Pi 4
407- =demeter= - Raspberry Pi 4
408- =aix= - Raspberry Pi 4
409- =aion= - aarch64 server
410- =rhea= - aarch64 server
411- =kerkouane= - =x86_64= server
412
413*** Experimental/Test Systems
414- =foo= - Test VM (experimental configuration)
415
416*** Non-NixOS Systems (Imperative Configuration)
417- =nagoya= - Debian server (aarch64)
418- =wakasu= - Fedora desktop
419
420See [[file:imperative/README.org][imperative/README.org]] for details on managing these systems.
421
422* References
423
424Repositories that inspired or contributed to this configuration:
425
426** Active References
427- [[https://github.com/jordanisaacs/dotfiles][https://github.com/jordanisaacs/dotfiles]]
428- [[https://github.com/chvp/nixos-config][https://github.com/chvp/nixos-config]]
429- [[https://github.com/gytis-ivaskevicius/nixfiles][https://github.com/gytis-ivaskevicius/nixfiles]]
430- [[https://github.com/davidtwco/veritas][https://github.com/davidtwco/veritas]]
431- [[https://github.com/buckley310/nixos-config][https://github.com/buckley310/nixos-config]]
432- [[https://github.com/eadwu/nixos-configuration][https://github.com/eadwu/nixos-configuration]]
433- [[https://github.com/berbiche/dotfiles][https://github.com/berbiche/dotfiles]]
434- [[https://github.com/hlissner/dotfiles][https://github.com/hlissner/dotfiles]]
435- [[https://github.com/Mic92/dotfiles][https://github.com/Mic92/dotfiles]]
436- [[https://github.com/lovesegfault/nix-config][https://github.com/lovesegfault/nix-config]]
437- [[https://github.com/bqv/nixrc][https://github.com/bqv/nixrc]]
438- [[https://github.com/leotaku/nixos-config][https://github.com/leotaku/nixos-config]]
439- [[https://github.com/rasendubi/dotfiles][https://github.com/rasendubi/dotfiles]]
440- [[https://git.tazj.in/about/][https://git.tazj.in/about/]]
441- [[https://github.com/danieldk/nix-home][https://github.com/danieldk/nix-home]]
442- [[https://github.com/terlar/nix-config][https://github.com/terlar/nix-config]]
443  + [[https://github.com/terlar/emacs-config][https://github.com/terlar/emacs-config]]
444- [[https://github.com/foo-dogsquared/nixos-config][https://github.com/foo-dogsquared/nixos-config]]
445- [[https://github.com/barrucadu/nixfiles][https://github.com/barrucadu/nixfiles]]
446- [[https://github.com/EmergentMind/nix-config][https://github.com/EmergentMind/nix-config]]
447- [[https://github.com/shahinism/45r4r][https://github.com/shahinism/45r4r]]
448- [[https://github.com/wimpysworld/nix-config][https://github.com/wimpysworld/nix-config]]
449- [[https://github.com/Hoverbear-Consulting/flake][https://github.com/Hoverbear-Consulting/flake]]
450- [[https://github.com/jnsgruk/nixos-config][https://github.com/jnsgruk/nixos-config]]
451- [[https://gitlab.com/ahoneybun/nix-configs][https://gitlab.com/ahoneybun/nix-configs]]
452- [[https://github.com/akirak/homelab][https://github.com/akirak/homelab]]
453- [[https://git.sr.ht/~akirak/nix-config][https://git.sr.ht/~akirak/nix-config]]
454- [[https://github.com/akirak/nix-desktop][https://github.com/akirak/nix-desktop]]
455- [[https://git.rossabaker.com/ross/cromulent][https://git.rossabaker.com/ross/cromulent]]
456- [[https://github.com/thiagokokada/nix-configs][https://github.com/thiagokokada/nix-configs]]
457- [[https://github.com/JRMurr/NixOsConfig][https://github.com/JRMurr/NixOsConfig]]
458- [[https://github.com/dzervas/dotfiles][https://github.com/dzervas/dotfiles]]
459- https://github.com/mirdaki/computer-config
460- https://github.com/Suya1671/commafiles
461- https://github.com/caelestia-dots/shell
462
463** Historical References
464- [[https://gitlab.com/samueldr/nixos-configuration][https://gitlab.com/samueldr/nixos-configuration]]
465- [[https://github.com/yurrriq/dotfiles][https://github.com/yurrriq/dotfiles]]
466- [[https://github.com/akirak/nixos-config][https://github.com/akirak/nixos-config]]
467- [[https://github.com/akirak/home.nix][https://github.com/akirak/home.nix]]
468- [[https://github.com/cstrahan/nixos-config][https://github.com/cstrahan/nixos-config]]
469- [[https://github.com/jwiegley/nix-config][https://github.com/jwiegley/nix-config]]
470- [[https://github.com/arianvp/nixos-stuff][https://github.com/arianvp/nixos-stuff]]
471- [[https://github.com/romatthe/ronix][https://github.com/romatthe/ronix]]
472- [[https://github.com/rummik/nixos-config][https://github.com/rummik/nixos-config]]
473- [[https://github.com/a-schaefers/nix-config.old][https://github.com/a-schaefers/nix-config.old]]
474- [[https://github.com/auntieNeo/nixrc][https://github.com/auntieNeo/nixrc]]
475- [[https://github.com/glines/nixrc][https://github.com/glines/nixrc]]
476- [[https://github.com/therealpxc/pxc.nix.d][https://github.com/therealpxc/pxc.nix.d]]
477- [[https://github.com/tycho01/nix-config][https://github.com/tycho01/nix-config]]
478- [[https://github.com/ghuntley/dotfiles-nixos][https://github.com/ghuntley/dotfiles-nixos]]
479- [[https://github.com/budevg/nix-conf][https://github.com/budevg/nix-conf]]
480- [[https://github.com/cleverca22/nixos-configs][https://github.com/cleverca22/nixos-configs]]
481- [[https://github.com/coreyoconnor/nix_configs][https://github.com/coreyoconnor/nix_configs]]
482- [[https://github.com/dejanr/dotfiles][https://github.com/dejanr/dotfiles]]
483- [[https://github.com/Ericson2314/nixos-configuration][https://github.com/Ericson2314/nixos-configuration]]
484- [[https://gitlab.com/garry-cairns/nixos-config][https://gitlab.com/garry-cairns/nixos-config]]
485- [[https://github.com/grahamc/nixos-config][https://github.com/grahamc/nixos-config]]
486- [[https://github.com/HugoReeves/nix-home][https://github.com/HugoReeves/nix-home]]
487- [[https://github.com/kampfschlaefer/nixconfig][https://github.com/kampfschlaefer/nixconfig]]
488- [[https://github.com/lambdael/nixosconf][https://github.com/lambdael/nixosconf]]
489- [[https://github.com/puffnfresh/nix-files][https://github.com/puffnfresh/nix-files]]
490- [[https://github.com/talyz/nixos-config][https://github.com/talyz/nixos-config]]
491- [[https://github.com/uwap/nixos-configs][https://github.com/uwap/nixos-configs]]
492- [[https://github.com/yacinehmito/yarn-nix][https://github.com/yacinehmito/yarn-nix]]
493- [[https://github.com/yrashk/nix-home][https://github.com/yrashk/nix-home]]
494- [[https://github.com/pSub/configs][https://github.com/pSub/configs]]
495- [[https://github.com/periklis/nix-config][https://github.com/periklis/nix-config]]
496- [[https://github.com/peel/dotfiles][https://github.com/peel/dotfiles]]
497- [[https://github.com/bennofs/etc-nixos][https://github.com/bennofs/etc-nixos]]
498- [[https://github.com/Baughn/machine-config][https://github.com/Baughn/machine-config]]
499- [[https://github.com/gvolpe/nix-config][https://github.com/gvolpe/nix-config]]
500- [[https://github.com/myme/dotfiles][https://github.com/myme/dotfiles]]
501- [[https://github.com/jedimahdi/.dotfiles][https://github.com/jedimahdi/.dotfiles]]
502- [[https://github.com/moni-dz/nix-config][https://github.com/moni-dz/nix-config]]
503- [[https://github.com/Aylur/dotfiles][https://github.com/Aylur/dotfiles]]
504- [[https://gitlab.com/Zaney/zaneyos][https://gitlab.com/Zaney/zaneyos]]
505- [[https://github.com/spikespaz/dotfiles][https://github.com/spikespaz/dotfiles]]
506- [[https://github.com/fufexan/dotfiles][https://github.com/fufexan/dotfiles]]
507- [[https://github.com/hlissner/dotfiles][https://github.com/hlissner/dotfiles]]
508- [[https://github.com/librephoenix/nixos-config][https://github.com/librephoenix/nixos-config]]
509- [[https://github.com/AntonHakansson/nixos-config][https://github.com/AntonHakansson/nixos-config]]
510
511* Licensing
512
513Unless otherwise stated in a subdirectory, all code is licensed under the GNU GPL v3. See [[file:COPYING][COPYING]] for details.