Install a Windows desktop

Use this runbook to install or update the owner's Windows configuration on a desktop, such as tallboy or atomic. It also adds or replaces the NixOS WSL distro and tests a change to the Windows dotfiles. The dotfiles live in the owner's dotfiles repository, not in this one. One script, windows/bootstrap.ps1 in that repository, clones it and installs the parts in this table.

Part	What it installs
`windows/configuration.winget`	Applications and OS settings
`mise run bootstrap`	CLI tools and the dotfile links
Nerd Font	A terminal font with icons
vibranceGUI	A tool that sets the GPU color saturation (digital vibrance)

note

Windows and the WSL distro each have their own checkout. No link crosses between the two, so the PowerShell profile works when WSL is not running.

The distro keeps /home on its own virtual disk, the homelab.wsl.homeDisk option in nix/images/wsl-home.nix. At each boot the distro attaches that disk and mounts it on /home. Without the disk, a user shell waits 30 seconds for /home, then exits. Root still gets a shell. Replacing the distro deletes only its root disk, so home stays.

Before you start#

You need winget 1.11 or later, from App Installer.
You need an account that can approve administrator prompts.
To add the WSL distro, you need the operator age key. See Manage SOPS secrets.

The bootstrap script clones the dotfiles repository to $HOME\src\github.com\jonpulsifer\dotfiles.

Install the desktop#

Open PowerShell.
Run the bootstrap script. Approve each administrator prompt.
```
irm https://raw.githubusercontent.com/jonpulsifer/dotfiles/main/windows/bootstrap.ps1 | iex
```
Result: The command prints Done. Open a new PowerShell 7 tab to pick up the profile. as its last line.
Open a new PowerShell 7 tab.
If the desktop must send metrics and logs to folly's Prometheus and VictoriaLogs, do Install Windows monitoring.

Update the desktop#

Open PowerShell 7.

Go to the checkout.

cd $HOME\src\github.com\jonpulsifer\dotfiles

Pull main.
```
git pull --ff-only
```
Result: The command prints Already up to date. or the changed files.
If configuration.winget changed, apply it. Accept each prompt. To see the changes first, add --what-if.
```
winget configure --file windows\configuration.winget
```
Result: The command prints Configuration successfully applied.
Run the dotfiles bootstrap.
```
mise run bootstrap
```
Result: The command prints Windows dotfiles deployed. as its last line.

Add the NixOS WSL distro#

Open PowerShell 7.

Run the bootstrap script with -WithWsl.

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/jonpulsifer/dotfiles/main/windows/bootstrap.ps1))) -WithWsl

Result: The command prints Distro 'NixOS' is up. Finish inside it: and the next commands.

Stage the wsl configuration. It takes effect at the next boot.

wsl -d NixOS -- sudo nixos-rebuild boot --flake github:jonpulsifer/infra#wsl

Stop the distro.
```
wsl --terminate NixOS
```
Create the home disk. If the desktop is not tallboy, set homelab.wsl.homeDisk for it first.
```
wsl -d NixOS -u root -- wsl-home-init
```
Result: The command prints Created D:\WSL\home.vhdx., or The home disk is already attached. when it exists.
Stop the distro again, so that the next boot mounts the home disk.
```
wsl --terminate NixOS
```
Open the distro.
```
wsl -d NixOS
```
Clone the repository.
```
git clone https://github.com/jonpulsifer/infra ~/src/github.com/jonpulsifer/infra
```
Result: The command prints Cloning into and the path of the checkout.
Put the operator age key in ~/.config/age/keys.txt.

Replace the WSL distro#

Replace the distro to start from a fresh root disk. Home stays on the home disk.

In the distro, build the image from main.
```
gh workflow run nix-image-builder.yaml -f image=wsl
```
Result: The run uploads nixos.wsl to the homelab-ng-free bucket.

Copy the image to the Windows downloads folder. Replace <user> with the Windows user name.

gcloud storage cp gs://homelab-ng-free/nixos.wsl /mnt/c/Users/<user>/Downloads/nixos.wsl

Open PowerShell 7 and go to the dotfiles checkout.
```
cd $HOME\src\github.com\jonpulsifer\dotfiles
```
Replace the distro. -Location is the folder that holds the distro's folder, such as D:\WSL on tallboy.
```
.\windows\Install-Wsl.ps1 -TarballPath $HOME\Downloads\nixos.wsl -Location D:\WSL -Replace
```
Result: The command prints Distro 'NixOS' is up. The script refuses a distro whose /home is not on the home disk.
Open the distro and check that /home is on the home disk.
```
findmnt -no LABEL /home
```
Result: The command prints nixos-home.
Install the tools that the home disk does not keep, such as mise's installs.
```
mise install
```

Test a Windows dotfiles change#

On the desktop, go to the dotfiles checkout.
Make sure every file that a dotfiles link points to exists.
```
mise run dotfiles:check
```
Result: The command prints no source missing warning, and prints Windows dotfiles deployed. as its last line.

If something goes wrong#

Symptom	Cause	Action
`winget configure` fails on a Store package.	The package needs a license prompt, and the bootstrap script turns prompts off.	Do step 4 of Update the desktop.
`mise run bootstrap` stops with `Developer Mode is off and this shell is not elevated`.	The winget configuration did not run.	Do step 4 of Update the desktop.
Windows Terminal does not use the settings from the checkout.	A Terminal update replaced `settings.json`.	Do step 5 of Update the desktop. The old file stays as `settings.json.bak-<timestamp>`.
`mise install` fails for a tool on Windows only.	The tool has no Windows build.	In `mise/global.toml` of the dotfiles repository, give the tool an `os` filter without `windows`.
vibranceGUI stops with `Hash mismatch`.	The download is not the pinned file.	Find why the upstream file changed. Change `-Url` and `-Sha256` in `Install-VibranceGui.ps1` together.
The prompt shows the branch with `?`.	`git status` took more than 150 ms, so the prompt does not check for uncommitted changes in that repository.	Open a new shell to check again. To remove the git segment, set the user environment variable `DOTFILES_PROMPT_GIT` to `0`.
Step 2 of Add the NixOS WSL distro prints `distro 'NixOS' already exists`.	The script replaces a distro only with `-Replace`.	Use the existing distro, or do Replace the WSL distro.
The distro prints `/home is not mounted` and closes the shell.	The home disk did not attach.	Run `wsl -d NixOS -u root -- systemctl status wsl-home-disk`. If the VHDX is missing, do steps 5 and 6 of Add the NixOS WSL distro.

Install Windows monitoring
Deploy a NixOS host
tallboy and atomic: the Windows desktops