dotfiles

1. Target OS

• macOS (Apple Silicon)
• Ubuntu 24.04 LTS (including WSL2)

2. Common Setup

2.1. GitHub Authentication

1. Connect to the machine via SSH with OpenSSH or so if needed

   # server side
   hostname -I

   # client side
   ssh username@hostname

2. Generate SSH key

   ssh-keygen -t ed25519 -N "" -f ~/.ssh/github

3. Copy public key

   cat ~/.ssh/github.pub

4. Add SSH key to GitHub

   • Go to https://github.com/settings/keys
   • Click "New SSH key"
   • Title: any name (e.g., PC name)
   • Key type: Authentication Key
   • Paste the public key

5. Add Signing key to GitHub

   • Click "New SSH key" again
   • Title: any name
   • Key type: Signing Key
   • Paste the same public key

6. Configure SSH

   cat >> ~/.ssh/config << 'EOF'
   Host github.com
   	IdentityFile ~/.ssh/github
   	User git
   EOF

7. Verify connection

   ssh -T github.com

2.2. Install Nix

sh <(curl --proto '=https' --tlsv1.2 -L https://nixos.org/nix/install) --daemon

or

curl --proto '=https' --tlsv1.2 -L https://nixos.org/nix/install | sh -s -- --daemon

Open a new terminal to verify:

nix --version

cf. https://nixos.org/download/#nix-install-linux

2.3. Enable Nix Flakes

mkdir -p ~/.config/nix

echo "experimental-features = nix-command flakes" > ~/.config/nix/nix.conf

2.4. Clone dotfiles

nix run nixpkgs#git -- clone git@github.com:i9wa4/dotfiles ~/ghq/github.com/i9wa4/dotfiles

cd ~/ghq/github.com/i9wa4/dotfiles

2.5. Create .envrc for direnv

echo "use flake" > .envrc

3. Ubuntu

3.1. Create a User with sudo Privileges

sudo adduser <username>

sudo usermod -aG sudo <username>

To delete a user and their home directory:

sudo deluser --remove-home <username>

3.2. Configure /etc/nix/nix.conf

/etc/nix/nix.conf is a real file (not managed by Nix). Configure it manually with sudo.

Add the current user to trusted-users so that binary caches (e.g., cache.numtide.com) work. Without this, caches are silently ignored and packages are compiled from source.

cat /etc/nix/nix.conf

Ensure there is exactly one trusted-users line that includes your username:

sudo vim /etc/nix/nix.conf

Example:

# Bad: last line wins, earlier entries are ignored
trusted-users = root userA
trusted-users = root userB

# Good: all users in one line
trusted-users = root userA userB

Also consider setting max-jobs = auto to use all available CPU cores for builds (default is 1):

max-jobs = auto

Restart nix-daemon to apply:

sudo systemctl restart nix-daemon

3.3. Expand Ubuntu LVM Root If Needed

Ubuntu's installer can leave / as a 100G logical volume even when the disk and LVM physical volume are much larger. Check this before regular use:

sudo bash ./bin/ubuntu/extend-root-lvm.sh --check

If the check reports free VG extents for the root logical volume, extend / with the managed helper:

sudo bash ./bin/ubuntu/extend-root-lvm.sh --apply

The helper only handles the common case where / is already on LVM and the VG has free extents. It does not resize disk partitions or physical volumes.

3.4. Initial home-manager switch

nix run home-manager -- switch --flake '.#ubuntu' --impure -b backup

3.5. Set zsh as default shell (optional)

~/.bashrc auto-switches to zsh, but setting the login shell is useful for regular SSH connections:

sudo chsh -s $(which zsh) $(id -un)

3.6. Docker Engine And Dev Containers (optional)

Home Manager installs the Docker CLI/tooling from Nix. Configure the rootful Ubuntu daemon/socket with the flake app:

nix run '.#docker-socket' -- --setup

Open a new login session after first setup. Then choose one socket mode:

nix run '.#docker-socket' -- --start

nix run '.#docker-socket' -- --enable

Devcontainers use /var/run/docker.sock; docker.service starts only when the socket is used. --start is for the current boot, while --enable keeps socket activation available after reboot.

Note: standalone Home Manager can declare systemd.user.*, but rootful Docker needs root systemd units, /var/run/docker.sock, and docker group state. The helper makes that Ubuntu root setup repeatable via sudo systemctl; use NixOS virtualisation.docker.enable for fully declarative root Docker. Rootless Docker is the user-service alternative, with devcontainer compatibility tradeoffs.

4. macOS

4.1. Backup Shell Configs

nix-darwin will fail if /etc/zshenv or /etc/zshrc exist with unrecognized content.

sudo mv /etc/bashrc /etc/bashrc.before-nix-darwin 2>/dev/null || true

sudo mv /etc/zshrc /etc/zshrc.before-nix-darwin 2>/dev/null || true

cf. nix-darwin/nix-darwin#149

4.2. Install Homebrew

nix-darwin manages Homebrew packages, but Homebrew itself must be installed manually.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

cf. https://brew.sh/

4.3. Initial darwin-rebuild

sudo nix run nix-darwin -- switch --flake '.#macos-p' --impure --no-update-lock-file

or

sudo nix run nix-darwin -- switch --flake '.#macos-w' --impure --no-update-lock-file

Open a new terminal after completion.

5. Post Installation

5.1. gh (GitHub CLI)

gh auth login
# Choose SSH for Git operation protocol
# Skip uploading SSH public key
# Login with a web browser

To copy auth to another machine:

gh auth status --show-token

gh auth login --with-token

5.2. AWS CLI

• Configuring IAM Identity Center authentication with the AWS CLI
• Configuration and credential file settings

5.3. Web Browser

5.3.1. Setting Synchronization

• Password: No
• Address: No
• Google Pay: No
• The Others: Yes

5.3.2. Search Engine

• Google Japanese: https://www.google.com/search?q=%s
• Google English: https://www.google.com/search?q=%s&gl=us&hl=en&gws_rd=cr&pws=0

5.3.3. Extensions

• Okta Browser Plugin
• Slack Channels Grouping

6. Daily Usage

Command	Description
nix run '.#switch'	Rebuild and activate configuration. After a successful switch, Linux expires Home Manager generations older than 1 day and macOS expires system generations older than 1 day. Scheduled daemon GC remains separate and uses 1 day on both Linux and macOS
nix run '.#update'	Update flake inputs
nix run '.#check'	Check flake configuration
nix run '.#storage-report' -- --self --summary	Summarize Linux home-directory storage

7. Upgrade Nix

Nix upgrade ownership differs by OS. On macOS, nix-darwin manages nix-daemon declaratively, so the daily update + switch flow covers upgrades. On Ubuntu, the system nix-daemon is outside home-manager's scope, so upgrade it separately from the root Nix profile.

7.1. Ubuntu

For a normal upgrade, do not re-run the curl installer. Upgrade the system Nix profile as root, then reload and restart nix-daemon. --remove-all avoids a profile conflict with the nix-manual output from the original installer:

sudo -i sh -c 'nix-channel --update &&
  nix-env --install --remove-all \
    --attr nixpkgs.nix nixpkgs.cacert &&
  systemctl daemon-reload &&
  systemctl restart nix-daemon'

Verify:

nix --version
systemctl is-active nix-daemon.service nix-daemon.socket

7.2. macOS

Part of the daily flow. nix-darwin rewrites /Library/LaunchDaemons/org.nixos.nix-daemon.plist and reloads the daemon whenever pkgs.nix resolves to a new store path.

nix run '.#update'    # Bump flake.lock (nixpkgs → new Nix)
nix run '.#switch'    # Rebuild; nix-darwin reloads nix-daemon

Do NOT re-run the curl installer on macOS. The next nix run '.#switch' reverts the daemon plist to what nixpkgs pins, effectively undoing (or even downgrading) any version the installer put in place.

Verify:

nix --version

7.3. Recover After macOS Update

macOS updates can break nix-darwin in two ways:

• Replace /etc/zshrc and /etc/zshenv symlinks with Apple defaults
• Corrupt files in the Nix store (APFS volume at /nix), leaving them empty

1. Source Nix manually (if nix is not found)

   . '/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh'

2. Rename conflicting /etc files

   sudo mv /etc/bashrc /etc/bashrc.before-nix-darwin 2>/dev/null || true
   sudo mv /etc/zshrc /etc/zshrc.before-nix-darwin 2>/dev/null || true
   sudo mv /etc/zshenv /etc/zshenv.before-nix-darwin 2>/dev/null || true
   sudo mv /etc/zprofile /etc/zprofile.before-nix-darwin 2>/dev/null || true

3. Repair corrupted store paths

   sudo nix-store --verify --check-contents --repair

4. Re-run darwin-rebuild

   sudo -i /nix/var/nix/profiles/system/sw/bin/darwin-rebuild switch \
     --flake '.#macos-p' --impure

5. Open a new terminal

cf. nix-darwin/nix-darwin#149