Fresh Install Checklist

This checklist is for installing dubnium onto a machine from scratch using a NixOS live USB.

Use this when:

the target machine does not already run NixOS
you are replacing the current OS
you want the flake to be the source of truth from first boot

If the machine already runs NixOS, use docs/first-bring-up-checklist.md instead.

Each top-level step has:

Start when: what must already be true before starting the step
Outcomes: what should be true when the step is complete

1. Prepare a NixOS Installer USB

Current preferred path: use the Dubnium custom installer USB, not a stock ISO. The custom installer bakes a source export of this private repo plus external/dotfiles into the live image. Write it to USB as a raw disk image, matching Rufus “DD image mode”. Use separate writable media for a local model seed bundle.

Build the ISO and prepare the seed model:

scripts/build-installer-iso.sh \
  --iso ./dubnium-installer.iso

This writes ./dubnium-installer.iso into the checkout. By default the helper uses the current Dubnium default model bundle, but the USB layout only requires a materialized model directory with config.json and SHA256SUMS. Pass --seed-model when using a different local bundle.

Then prepare the USB with the guarded writer for the current platform.

Windows PowerShell:

.\scripts\write-installer-usb.ps1 `
  -IsoPath .\dubnium-installer.iso `
  -DiskNumber 7 `
  -ExpectedFriendlyName "USB SanDisk 3.2Gen1"

The writer requires the disk identity check and final y/N confirmation. It overwrites the whole USB disk with the ISO image.

Optional one-shot Windows path:

.\scripts\build-installer-usb.ps1 `
  -DiskNumber 7 `
  -ExpectedFriendlyName "USB SanDisk 3.2Gen1"

Optional one-shot Linux or macOS path:

bash scripts/build-installer-usb.sh \
  --disk /dev/sdX \
  --expected SanDisk

On macOS, use a whole disk such as /dev/diskN. On Linux, use a whole USB disk such as /dev/sdX, not a partition.

Manual Linux USB write path:

scripts/write-installer-usb.sh \
  --iso ./dubnium-installer.iso \
  --disk /dev/sdX \
  --expected SanDisk

Expected USB layout:

dubnium-installer.iso -> whole USB disk

Verify the installer media from whichever drive letter Windows assigns:

Test-Path I:\EFI\BOOT\BOOTX64.EFI
Test-Path I:\nix-store.squashfs
Get-Volume -DriveLetter I

Separate seed media should contain:

models/selected-model-bundle/

See docs/runbooks/custom-installer-iso.md for the full USB process and docs/runbooks/model-seeding.md for the seed bundle commands.

Start when

existing Nix-capable build machine with the Dubnium repo checkout
USB stick that can be erased
materialized model bundle is available locally, if seeding the model now
permission to run the guarded USB writer for the platform

Outcomes

custom Dubnium ISO is built from the intended flake source
USB device identity was checked by the platform helper before erase
USB has a bootable raw-written Dubnium installer image
separate seed media has the local model bundle, if seeding now
the install path requires no GitHub token, private SSH key, or Hugging Face download in the live installer

1.1 USB Security And Drift Check

Before leaving the build machine, confirm:

git status --short
git -C external/dotfiles status --short

The ISO bakes tracked flake source, including external/dotfiles, into the installer. Stage or commit intentional changes before building, and do not bake decrypted secrets, long-lived tokens, SSH private keys, local caches, or model weights into the repo.

The USB is private media. The installer payload contains private source, and separate seed media contains unencrypted model files.

1.2 Seamless USB Acceptance Check

Before booting the target, verify the prepared stick:

EFI/BOOT/BOOTX64.EFI
nix-store.squashfs
seed-media/models/selected-model-bundle/config.json
seed-media/models/selected-model-bundle/SHA256SUMS

If the model bundle is not on the USB yet, use docs/runbooks/model-seeding.md before booting the target.

1.3 Stock ISO Fallback

A stock NixOS ISO remains useful for rescue, but it is not the preferred fresh Dubnium install path. If using stock media, you must bring the Dubnium source and initialized dotfiles submodule on separate private media, then install from that local checkout. Do not depend on live-session GitHub credentials for a private-repo install.

2. Boot the Target Machine From USB

Start when

prepared NixOS installer USB
physical access to the target machine
firmware access or boot-menu access

Outcomes

target machine is booted into the NixOS live environment
firmware boot mode and target disk visibility are confirmed
keyboard, display, disk visibility, and network are usable
source import tools are available before repo setup steps begin
private repo source is reachable from the live environment
optional SSH access to the live environment is available if needed

2.1 Confirm Firmware Settings

Before booting the installer, review firmware settings:

boot mode should be UEFI, not legacy/CSM
Secure Boot should be disabled unless you intentionally handle it
internal install disk should be visible
primary display GPU should be the one you expect
Above 4G decoding should be enabled if the firmware exposes it and you plan to use multiple GPUs
virtualization/IOMMU can be enabled if you expect to use it later

Do not proceed if the firmware cannot see the target install disk.

Insert the USB stick into the target machine, power it on, and enter the firmware boot menu.

Common boot-menu keys:

F8
F11
F12
Esc
Del

Choose the USB entry. Prefer the UEFI entry if the firmware shows both legacy and UEFI options.

2.3 Confirm Live Environment Basics

After the NixOS live environment boots, open a terminal.

Check that the machine sees CPU, memory, disks, and network devices:

lscpu | head
free -h
lsblk -o NAME,SIZE,MODEL,TYPE,MOUNTPOINTS
ip link

Check network connectivity:

ip addr
ping -c 3 1.1.1.1
ping -c 3 github.com

If networking is not up:

connect Ethernet if available
use the graphical network manager in the GNOME ISO
on the minimal ISO, use nmtui if available:

sudo nmtui

Exit criteria:

keyboard works
display works
target install disk is visible
internet access works

2.4 Ensure Source Import Tools Are Available In the Live Environment

On the custom Dubnium installer USB, confirm the baked source helper exists:

command -v unpack-dubnium
tar --version

If unpack-dubnium is available, section 3 can use the baked source snapshot directly and does not need GitHub credentials.

Before importing the repo source from the live USB session, confirm git and basic archive tools are available:

git --version
tar --version

If git is missing and you need it for validation, install it in the live environment:

nix-shell -p git --run 'git --version'

If you need git for more than one command, enter a shell with it available:

nix-shell -p git
git --version

Exit criteria:

git --version succeeds in the current shell or in the shell you will use to inspect the repo
tar --version succeeds if you are extracting an archive

2.5 Optional: Enable SSH Into the Live Environment

Use this if the target machine is easier to drive from another computer. Note: If using the Custom Installer, your SSH keys may already be authorized. Otherwise:

Set a temporary password: passwd
Or add your key: mkdir -p ~/.ssh && echo "ssh-ed25519 ..." >> ~/.ssh/authorized_keys

Start SSH:

sudo systemctl start sshd
ip addr

Then connect from another machine using the live environment IP address:

ssh nixos@<target-ip>

This access is temporary and only applies to the live USB environment.

3. Make the Repo Available in the Live Environment

Start when

live NixOS environment is running
the custom installer source snapshot is available, or a separate private source export is attached to the machine

Outcomes

Dubnium repo exists in the live environment
repo contains flake.nix
repo contains hosts/workstation/default.nix
repo contains external/dotfiles/flake.nix
commands are being run from the repo root

3.0 Preferred: Unpack From Custom Installer Media

For the current one-shot install path, run the guarded installer helper:

install-dubnium-from-usb

This replaces the manual section 3 through section 9 flow for the simple unencrypted layout. The helper prints lsblk, prompts for the target whole disk, and asks for final y/N confirmation before erasing anything. Defaults are btrfs, dubnium home profile, passwd password mode, and copying the install snapshot into the installed system. Use --password-mode hash to write a host-local initial password hash before install, or --password-mode skip when another login path already exists. Use --dry-run first if disk identity is not yet obvious.

If booted from the Dubnium custom installer USB, use the baked source snapshot:

unpack-dubnium
cd ~/local/src/dubnium

This is the token-free private repo path. It does not clone from GitHub during install.

To choose the installed normal user, create hosts/workstation/user.nix before install:

{
  dubnium.user.name = "alice";
  dubnium.user.description = "Example User";
}

3.1 Alternate: Copy Source From Local Media

If you brought the repo on separate media, attach it now and identify it:

lsblk -o NAME,SIZE,MODEL,TRAN,TYPE,MOUNTPOINTS

Mount the removable media read-only if practical, then extract or copy the exported source into your working directory.

Example for a separate git archive-style export:

mkdir -p ~/installer-src
cd ~/installer-src
tar -xzf /path/to/dubnium-installer-src.tgz
cd dubnium

Example for a plain copied export tree:

mkdir -p ~/Projects
cp -a /path/to/dubnium ~/Projects/dubnium
cd ~/Projects/dubnium

This path avoids depending on live-session GitHub credentials. Prefer the custom installer payload when available, because it keeps the source path and helper behavior consistent.

3.2 Alternate: Extract A Separate Source Archive

If you are not using the current custom installer payload, bring a separate source archive and extract it to the same live-session path:

mkdir -p ~/local/src
tar -xzf /path/to/dubnium-installer-src.tgz -C ~/local/src
cd ~/local/src/dubnium

3.3 Verify Repo Contents

pwd
ls
git status --short
test -f flake.nix
test -f hosts/workstation/default.nix
test -f external/dotfiles/flake.nix

Exit criteria:

repo is present locally, whether copied, extracted, or imported
flake.nix exists
hosts/workstation/default.nix exists
external/dotfiles/flake.nix exists

4. Partition the Target Disk

Start when

target install disk is visible in lsblk
disk encryption decision is made
swap/hibernation decision is made
target disk has been positively identified and is safe to erase

Outcomes

target disk has a new GPT partition table
EFI system partition exists
root partition exists
EFI_PART and ROOT_PART point to real block devices
no partitioning commands have touched the USB installer

This repo does not yet prescribe a disk layout.

The example below uses a simple UEFI layout:

EFI system partition: 1 GiB, FAT32, mounted at /boot
root partition: rest of disk, ext4, mounted at /

This example does not create a separate /home partition and does not create a swap partition. Add those only if you deliberately want them.

This example does not enable disk encryption. If you want LUKS or a separate encrypted data layout, stop here and use a different partition/filesystem plan.

This example also does not create a swap partition. If hibernation is required, stop here and design swap explicitly. If hibernation is not required, zram can be handled later in NixOS configuration.

4.1 Identify the Install Disk

List disks:

lsblk -o NAME,SIZE,MODEL,TRAN,TYPE,MOUNTPOINTS

Example NVMe disk:

nvme0n1  1.8T Samsung_SSD disk

Example SATA/SAS/USB-style disk:

sda  1.8T Samsung_SSD disk

Set the target disk variable:

DISK=/dev/nvme0n1

or:

DISK=/dev/sda

Important:

this must be the internal install disk
this must not be the USB installer
all data on this disk will be destroyed once partitioning begins

4.2 Confirm Existing Layout

Before touching the disk:

echo "$DISK"
lsblk -o NAME,SIZE,MODEL,TYPE,FSTYPE,MOUNTPOINTS "$DISK"
sudo fdisk -l "$DISK"

Before touching disks, decide:

disk device name
EFI size
root filesystem choice
whether you want swap or zram only
whether you want a separate /home

Minimum sane layout:

EFI system partition
root partition

Example tools:

lsblk
blkid
fdisk
parted
gdisk

Do not proceed until you are sure which disk you are installing to.

4.3 Preview and Clear Existing Signatures

Preview existing filesystem and partition signatures:

sudo wipefs -n "$DISK"

If the disk is definitely the install target, clear old signatures:

sudo wipefs -a "$DISK"

This is destructive. Do not run it against the USB installer or any disk you intend to preserve.

4.4 Create a GPT Partition Table

This is destructive. Only run it after confirming DISK.

echo "About to partition: $DISK"
lsblk -o NAME,SIZE,MODEL,TYPE,MOUNTPOINTS "$DISK"

Create the partition table and partitions:

sudo parted "$DISK" -- mklabel gpt
sudo parted "$DISK" -- mkpart ESP fat32 1MiB 1025MiB
sudo parted "$DISK" -- set 1 esp on
sudo parted "$DISK" -- mkpart primary ext4 1025MiB 100%

Ask the kernel to re-read the partition table:

sudo partprobe "$DISK"
sleep 2
lsblk -o NAME,SIZE,MODEL,TYPE,FSTYPE,MOUNTPOINTS "$DISK"

4.5 Set Partition Variables

For NVMe disks, partitions are usually named with p1 / p2:

EFI_PART="${DISK}p1"
ROOT_PART="${DISK}p2"

For SATA/SAS-style disks, partitions are usually named 1 / 2:

EFI_PART="${DISK}1"
ROOT_PART="${DISK}2"

Verify:

echo "EFI_PART=$EFI_PART"
echo "ROOT_PART=$ROOT_PART"
test -b "$EFI_PART"
test -b "$ROOT_PART"
lsblk -o NAME,SIZE,MODEL,TYPE,FSTYPE,MOUNTPOINTS "$DISK"

5. Create Filesystems and Mount Them

Start when

EFI_PART points to the EFI partition
ROOT_PART points to the root partition
both partition variables have been verified with test -b

Outcomes

EFI partition is formatted FAT32
root partition is formatted ext4
root partition is mounted at /mnt
EFI partition is mounted at /mnt/boot
mount layout matches the future NixOS filesystem config

5.1 Format the Partitions

This is destructive to the selected partitions.

sudo mkfs.fat -F 32 -n NIXBOOT "$EFI_PART"
sudo mkfs.ext4 -L nixos "$ROOT_PART"

5.2 Mount the Root Filesystem

sudo mount "$ROOT_PART" /mnt

5.3 Mount the EFI Filesystem

The current host config expects systemd-boot, so mount the EFI filesystem at /mnt/boot:

sudo mkdir -p /mnt/boot
sudo mount "$EFI_PART" /mnt/boot

5.4 Verify Mount Layout

Once mounted, verify:

findmnt /mnt
findmnt /mnt/boot
lsblk -o NAME,SIZE,FSTYPE,LABEL,MOUNTPOINTS "$DISK"

Expected:

root partition mounted at /mnt
EFI partition mounted at /mnt/boot

6. Generate Hardware Configuration Into the Repo

Start when

repo is available and current shell is at repo root
target root filesystem is mounted at /mnt
target EFI filesystem is mounted at /mnt/boot

Outcomes

hosts/workstation/hardware-configuration.nix reflects the target hardware
generated filesystem entries match /mnt and /mnt/boot
placeholder hardware config has been replaced
git diff shows the hardware config change

6.1 Generate Config

From the repo root:

sudo nixos-generate-config --root /mnt --dir ./hosts/workstation

This should populate:

hosts/workstation/hardware-configuration.nix

Important:

this file must reflect the real disk layout you just mounted
this replaces the scaffold placeholder currently in the repo

6.2 Review Generated Hardware Config

sed -n '1,220p' hosts/workstation/hardware-configuration.nix

Confirm:

root filesystem points at the root partition or its filesystem label/UUID
/boot points at the EFI partition
generated imports look normal
no obvious reference to the USB installer disk exists

6.3 Confirm Git Diff

git diff -- hosts/workstation/hardware-configuration.nix

Exit criteria:

hardware config changed from placeholder to real host config
filesystem entries match the mounted target disk

7. Review Host Config Before Install

Start when

generated hardware config exists
host config exists at hosts/workstation/default.nix
hardware facts are known well enough to set GPU options accurately
login/access strategy is known

Outcomes

hostname, bootloader, SSH, GPU, vLLM, and k3s settings are reviewed
GPU settings reference only installed/visible GPUs
vLLM first-install stance is explicit
k3s first-install stance is explicit
at least one installed-system login path is known

7.1 Inspect Host Config

Check hosts/workstation/default.nix.

sed -n '1,240p' hosts/workstation/default.nix

At minimum confirm:

hostname
current GPU assumptions
vLLM model choice
any network or SSH expectations
bootloader settings
k3s enablement

Current scaffold assumptions:

boot default is desktop
studio-local is a desktop overlay
vLLM is compute-only
planned topology is 2 GPUs
currently present GPU set defaults to [ 0 ]

7.2 Confirm GPU Settings

If the target currently has only one NVIDIA GPU:

dubnium.hardware.presentGpus = [ 0 ];
dubnium.hardware.displayGpu = 0;
dubnium.hardware.computeGpus = [ 0 ];

If the target has two NVIDIA GPUs and you are ready to expose both to compute, update only after confirming nvidia-smi ordering:

dubnium.hardware.presentGpus = [ 0 1 ];
dubnium.hardware.displayGpu = 0;
dubnium.hardware.computeGpus = [ 0 1 ];

For first bring-up, prefer the most conservative accurate setting. Do not list a GPU that is not installed and visible.

7.3 Confirm vLLM Settings

Current host config disables vLLM by default so the workstation can prove the base desktop system before model/runtime work:

dubnium.vllm.enable = false;

If opting into vLLM for compute testing, set dubnium.vllm.enable = true and consider explicit first-run guardrails:

dubnium.vllm.extraArgs = [
  "--max-model-len" "8192"
  "--gpu-memory-utilization" "0.70"
  "--enforce-eager"
];

7.4 Confirm k3s Settings

Current host config has:

dubnium.k3s.enable = false;

Keep k3s disabled for the first install unless you specifically want to validate k3s during the first boot.

7.5 Confirm User and Access Settings

Before installing, confirm how you will log into the installed system:

rg -n "users\\.users|openssh|authorizedKeys|initialPassword|hashedPassword" hosts modules

The current host config enables SSH, but this checklist should not assume a normal user account exists unless the NixOS config declares it.

Choose one access strategy before install:

root password set by nixos-install
declared normal user with password or SSH key
SSH key access configured in NixOS

For the default workstation user, keep the password hash local by adding hosts/workstation/user.nix before install:

{
  users.users.ryjen.initialHashedPassword = "$y$j9T$...";
}

Generate the hash in the live environment with:

mkpasswd -m yescrypt

Do not reboot into the installed system without knowing at least one login path.

8. Optional Dry Evaluation Before Install

Start when

repo is at install-ready state
generated hardware config exists
network access is working in the live environment
Nix can evaluate flakes in the live environment

Outcomes

flake evaluation has been attempted
mode-tools package build has been attempted
any evaluation/build failure is understood before install
no unknown evaluation error is carried into nixos-install

8.1 Build the Target System

If the live environment has working Nix daemon support and networking, try:

sudo nixos-rebuild build --flake .#workstation

This is optional but useful.

If it fails:

fix evaluation problems before running the installer

8.2 Build the Mode Tools Package

nix build .#packages.x86_64-linux.mode-tools

8.3 Inspect Common Evaluation Failures

Common buckets:

hardware configuration references the wrong disk
NVIDIA package/options fail to evaluate
vLLM package is unavailable or expensive to build in the live environment
unfree packages are blocked
host option assertions fail

Exit criteria:

the flake evaluates
the system build either succeeds or fails for a known reason you have decided to accept before nixos-install

9. Install From the Flake

Start when

/mnt and /mnt/boot are mounted correctly
hardware config and host config are reviewed
dirty repo state is intentional
installed-system login path is known
repo persistence plan is explicit

Outcomes

NixOS is installed from .#workstation
bootloader installation result is known
root password or equivalent access path is established
repo is copied into the installed filesystem or a post-boot source import plan is explicit

9.1 Final Preinstall Check

Before installing:

findmnt /mnt
findmnt /mnt/boot
lsblk -o NAME,SIZE,FSTYPE,LABEL,MOUNTPOINTS "$DISK"
git status --short

Confirm:

/mnt is the target root filesystem
/mnt/boot is the target EFI filesystem
generated hardware config is present
host config is reviewed
any dirty repo state is intentional

9.2 Confirm Repo Persistence Plan

The live USB environment is temporary. The install itself uses the live checkout at ~/local/src/dubnium, but that path does not automatically become an installed-system checkout.

If you want the flake source to be available immediately after first boot, copy the current repo into the target filesystem before installing.

Example target location:

sudo mkdir -p /mnt/home/<user>/Projects
sudo cp -a "$(pwd)" /mnt/home/<user>/Projects/dubnium

If the installed system will have a different user or home path, adjust the destination.

If you prefer not to copy from the live environment, plan how you will import the repo source again after first boot. Do not assume the live-environment checkout survives reboot.

The custom installer source payload belongs to the USB live system. It is enough to install from, but it does not automatically become a checkout on the installed system. If install-time changes need to go back to the private Dubnium repo, reconcile them after first boot using Post-Install Source Reconciliation.

9.3 Run Installer

From the repo root:

sudo nixos-install --flake .#workstation

If the installer asks for a root password, set one unless you have already configured another access path.

9.4 Capture Install Result

If install succeeds, note:

whether bootloader installation succeeded
whether any warnings appeared
whether a root password was set

If install fails, do not reboot yet. Inspect the error while still in the live environment.

10. Reboot Into the Installed System

Start when

nixos-install --flake .#workstation completed successfully
bootloader result is known
root password or other access path exists
no unresolved install error remains

Outcomes

machine boots from the internal disk
USB installer is removed or not selected
installed NixOS system reaches a login/session path
if boot fails, rescue path is known and documented

10.1 Unmount and Reboot

If install succeeded:

sync
sudo reboot

Remove the USB stick when appropriate so the machine boots from disk.

10.2 Select Installed Disk

If the machine boots back into the USB installer:

remove the USB stick
enter firmware boot menu
select the internal disk or Linux Boot Manager

10.3 Recovery If Boot Fails

If the installed system does not boot:

boot the USB installer again
mount root and EFI partitions back under /mnt
inspect /mnt/etc/nixos and the generated hardware config
check firmware boot entries with bootctl from a chroot if needed

Concrete rescue mount:

sudo mount "$ROOT_PART" /mnt
sudo mount "$EFI_PART" /mnt/boot

Enter the installed system:

sudo nixos-enter --root /mnt

Inside the chroot:

bootctl status
nixos-rebuild boot --flake /home/<user>/Projects/dubnium#workstation
exit

If the repo was not copied into the installed filesystem, use the path where it actually exists or import it again from your prepared source media.

11. First Boot Verification

Start when

installed system has booted from internal disk
operator can log in locally or over SSH
repo exists on the installed system or can be imported immediately

Outcomes

installed system identity is verified
repo source is available on the installed system
mode CLI works
runtime state files exist
first observed mode is desktop
vLLM and studio overlay services are inactive in desktop
NVIDIA basics are verified before any compute testing

11.1 Verify Basic System Identity

After booting the installed system:

hostname
uname -a
ip addr

11.2 Verify Repo Location

If you copied the repo before install:

test -d ~/Projects/dubnium
cd ~/Projects/dubnium
git status --short

If the repo is missing, import it now before treating the system as fully owned by the flake source.

11.3 Verify Mode CLI

mode status
mode current
mode desired

11.4 Verify systemd Units

systemctl status desktop.target
systemctl status compute.target
systemctl status vllm.service
sudo ls -la /run/mode-controller

11.5 Verify Runtime State Files

sudo cat /run/mode-controller/desired
sudo cat /run/mode-controller/current
sudo cat /run/mode-controller/capability-placement.json
sudo cat /run/mode-controller/hardware-topology.json

Expected first-boot posture:

current mode should be desktop
vLLM should not be active in desktop
studio-local-policy.service should not be active
audio-priority.service should not be active

11.6 Verify NVIDIA Before Compute Testing

Before testing compute, verify NVIDIA basics:

nvidia-smi
lsmod | grep nvidia

Do not run mode request compute from the fresh-install checklist. Compute transition testing belongs in the bring-up and transition-testing runbooks after the desktop baseline, observer, and NVIDIA runtime all look correct.