nix-darwin/README-ko.md

nix-darwin

nix-darwin, home-manager, nix-homebrew, sops-nix 기반의 선언적 macOS 설정 저장소입니다.

이 저장소가 관리하는 것

• modules/flake/의 flake 조립 및 호스트 구성 생성
• modules/aspects/의 자동 발견 Darwin/Home Manager aspect
• hosts/의 자동 발견 멀티 호스트 선언
• secrets/ + .sops.yaml의 SOPS 암호화 시크릿

사전 요구사항

• Apple Silicon macOS (aarch64-darwin)
• flakes가 활성화된 Nix (nix-command + flakes)
• just (명령 실행기)
• 아래 경로의 SOPS age 키:

~/.config/sops/age/keys.txt

저장소 구조

• flake.nix: flake-parts 진입점과 flake input
• Justfile: 일상 명령(darwin, darwin-debug, fmt, up, gc 등)
• modules/flake/: 저장소 옵션, Darwin 조립, 공유 context 모듈
• modules/aspects/: base, homebrew, shell, editor, desktop 같은 이름 있는 자동 발견 aspect 진입 모듈
• modules/aspects/_*/: 공개 aspect를 뒷받침하는, 자동 로딩에서 제외되는 내부 구현 트리
• hosts/: system과 flat features 목록을 등록하는 자동 발견 호스트 선언
• secrets/: 암호화된 시크릿 파일(poby.yaml)

자주 쓰는 명령

# 사용 가능한 작업 보기
just

# 현재 머신 hostname 기준으로 빌드 및 스위치
just darwin $(hostname)

# trace/verbose 로그와 함께 빌드 및 스위치
just darwin-debug $(hostname)

# Nix 파일 포맷팅(저장소 루트 기준)
just fmt .

# flake input 전체 업데이트
just up

# 특정 input 하나만 업데이트
just upp nixpkgs

# 스위치 없이 빌드 검증(예시 호스트: fenrir)
nix build .#darwinConfigurations.fenrir.system --extra-experimental-features 'nix-command flakes'

# 실제 빌드 없이 dry-run 검증
nix build .#darwinConfigurations.fenrir.system --dry-run --extra-experimental-features 'nix-command flakes'

# 시스템 프로필 히스토리 확인 / 오래된 generation 정리
just history
just clean
just gc

설정 노트

• flake.nix는 이제 flake-parts를 사용하고 ./modules/flake는 명시적으로 유지한 채 import-tree로 ./modules/aspects와 ./hosts를 자동 발견합니다.
• hosts/fenrir.nix가 현재 호스트 선언이며 fenrir를 하나의 flat feature 목록에 매핑합니다.
• modules/flake/darwin-configurations.nix가 각 호스트의 darwinConfigurations.<host>를 만들고, 사용자 poby의 Home Manager를 nix-darwin 안에 통합합니다.
• modules/aspects/가 호스트가 선택하는 기능 vocabulary입니다. 현재 feature 집합은 base, nix-core, system-packages, homebrew, macos-defaults, activation, fonts, sudo-auth, shell, cli-tools, git, ssh, secrets, terminal, editor, desktop, fenrir 입니다.
• cli-tools aspect가 zoxide를 포함한 CLI 사용자 도구 묶음을 담당합니다.
• modules/aspects/_*/는 자동 발견에서 제외되는 내부 구현 경로입니다. 이 저장소는 /_가 포함된 경로를 import-tree가 건너뛴다는 규칙을 사용해 NVF 같은 서브트리를 보호합니다.
• 이번 단계에서는 Home Manager를 Darwin 내부에서만 사용하며, 별도의 homeConfigurations 출력은 만들지 않습니다.

호스트 추가 방법

• hosts/<hostname>.nix 파일을 만듭니다.
• repo.hosts.<hostname>.system을 등록합니다.
• repo.hosts.<hostname>.features에 사용할 aspect 이름 목록을 등록합니다.
• 호스트 전용 동작은 공유 feature를 수정하지 말고 modules/aspects/에 새 aspect로 추가합니다.

시크릿

• 시크릿은 secrets/*.yaml에 암호화해서 보관합니다.
• .sops.yaml이 secrets/.*\.yaml에 대한 암호화 규칙을 강제합니다.
• Home Manager는 secrets aspect를 통해 secrets/poby.yaml에서 아래 항목을 읽습니다.
  • github_ssh_key
  • github_cli_token

트러블슈팅

• 자세한 평가/빌드 로그가 필요하면 just darwin-debug <hostname>을 사용하세요.
• 특정 호스트 평가가 실패하면 해당 호스트가 darwinConfigurations에 정의됐는지 확인하세요.
• 의존성 그래프만 확인하고 싶다면 nix build .#darwinConfigurations.<host>.system --dry-run을 먼저 실행하세요.
• 빌드 성공 후에도 설정 반영이 이상하면 switch를 다시 실행하고 활성 hostname/config를 확인하세요.