Runbook: Post-Install Source Reconciliation

Status: living

Use this after a fresh install when the installer source snapshot has produced local changes that should become normal Dubnium repo history.

The custom installer payload is an export-style source snapshot on the USB live system. It is suitable for running nixos-install, but it does not automatically become a durable checkout inside the installed OS. Even when the snapshot is copied into the target filesystem, it is not the long-term working copy because it does not include .git history.

Desired Shape

installed system has a normal Git checkout for Dubnium
install-time changes are reviewed as a Git diff
host-specific files are committed only when they belong in repo policy
secrets, tokens, model weights, local caches, and temporary installer state stay out of Git

1. Locate Or Recreate The Install Snapshot

After first boot, start by checking whether the installer source was copied into the installed filesystem:

test -e ~/local/src/dubnium/flake.nix

If it was not copied, boot the custom installer USB or mount the prepared source media again and import the same source snapshot into a temporary location, such as ~/local/src/dubnium-install-snapshot. The goal is to recover any install-time edits, especially the generated hardware config.

If the installed system already has the copied installer source at ~/local/src/dubnium, check whether it is a Git checkout:

cd ~/local/src/dubnium
git rev-parse --is-inside-work-tree

If that fails, keep the snapshot as evidence and make room for a real checkout:

cd ~/local/src
mv dubnium dubnium-install-snapshot

If the source was copied elsewhere, use that path as the snapshot path in the commands below. If there were no install-time source edits to preserve, skip the snapshot and create the canonical checkout directly.

2. Create The Canonical Checkout

Clone the private Dubnium repo using the installed system’s normal operator credential path. Prefer SSH keys or an intentional short-lived HTTPS token; do not reuse live-installer credentials as a persistent access mechanism.

mkdir -p ~/local/src
git clone <dubnium-private-repo-url> ~/local/src/dubnium
cd ~/local/src/dubnium
git submodule update --init --recursive

If the installed machine should use a different source root, keep the same pattern: one normal Git checkout, and one preserved installer snapshot until the diff has been reconciled.

3. Bring Across Intentional Install Changes

Copy only the changes that should become repo state. The most common first install candidate is the generated hardware config:

cp ~/local/src/dubnium-install-snapshot/hosts/workstation/hardware-configuration.nix \
  hosts/workstation/hardware-configuration.nix

Review any optional host-local file before copying it. For example, hosts/workstation/user.nix may be useful on the installed machine, but it should be committed only if the repo is meant to carry that exact user policy.

For a broader comparison between the preserved snapshot and the canonical checkout:

diff -ruN \
  ~/local/src/dubnium-install-snapshot/hosts/workstation \
  ~/local/src/dubnium/hosts/workstation

Prefer copying specific files over bulk-syncing the snapshot into the checkout.

4. Review, Test, Commit, Push

From the canonical checkout:

git status --short
git diff -- hosts/workstation modules docs

nix --extra-experimental-features 'nix-command flakes' \
  eval .#nixosConfigurations.workstation.config.networking.hostName

git add hosts/workstation/hardware-configuration.nix
git commit -m "Record workstation hardware configuration"
git push

Use a broader validation command when the reconciled change touches modules, services, or shared policy. If evaluation or rebuild fails, keep the snapshot and the Git checkout separate until the failure is understood.

5. Rebuild From The Canonical Checkout

After the change is committed or intentionally kept as local-only state, rebuild from the normal checkout rather than the installer snapshot:

sudo nixos-rebuild switch --flake ~/local/src/dubnium#workstation

Once the canonical checkout has the needed changes and the system rebuilds from it, the preserved install snapshot can be archived or deleted.

Keyboard shortcuts