Capstone: Rebuild a Workstation From Notes

By the end of this lesson, you will be able to...

• design a recovery dossier that separates machine configuration, package trust, services, secrets, valuable data, and host-specific facts;

• stage a workstation reconstruction so that each change has a predicted result, acceptance evidence, and a bounded recovery action;

• review a failed rebuild without confusing a copied command, a declarative generation, or a repository clone with proof that the workstation is usable.

Idea in one sentence: A recoverable workstation is not a pile of setup commands; it is a small, versioned recovery argument that says what to restore, in what order, what evidence proves each layer works, and what remains deliberately manual.

Core Insight

Maya's new laptop field is blank while her old machine is unavailable. A workstation is recovered when its important promises can be checked again, not when it merely looks familiar. The recovery dossier makes those promises inspectable: it separates state classes, orders their dependencies, and records the evidence that distinguishes a working layer from a plausible-looking one.

That is why the final artifact is an argument rather than an installation script. Automation can execute a good argument, but it cannot supply the missing trust decision, secret, host fact, or acceptance condition that the argument never named.

The Scenario

Maya has replaced her laptop cedar with a fresh machine called field. Her old machine still exists, but she treats it as unavailable for the exercise: no copying its home directory, no asking it which command worked last month, and no exporting every credential “just in case.” She has only the recovery dossier she prepared during this track, a backup of her notes, and the official installation media for the operating system she chooses.

Her definition of useful is deliberately modest:

• she can sign in as her normal user;
• a terminal, editor, and browser work;
• Git can reach a permitted repository without placing a credential in a configuration repository;
• her note-preview service starts after its non-secret configuration and secret reference are provisioned;
• one known note can be restored and opened;
• she can show evidence for every important claim.

That is not the same as recreating every preference. A font cache, old downloads, and a perfect panel layout can wait. The capstone judges repairability and explainability, not visual similarity.

The tempting recovery plan is short:

install Linux
clone dotfiles
install packages
copy home directory
keep trying commands until it feels normal

It can work when the machine is simple and the owner remembers every hidden dependency. It fails under pressure. A package may have come from an unrecorded source. A service may depend on an environment file that was never in Git. A file can exist but belong to the wrong user. A NixOS configuration can build while the user service or personal data is still absent. The plan produces activity, not evidence.

The stronger model is a recovery dossier: a versioned set of notes that turns a rebuild into small claims. Each claim names the object being changed, the source of trust, the expected result, the evidence to collect, and the smallest recovery action if that result is missing.

Constraints Before Tools

Maya writes constraints before deciding whether a step is a shell command, an Arch-style manual record, or a NixOS declaration. This prevents a tool from quietly deciding the design.

These are not universal rules. A fully automated installer can be an excellent choice when it is reviewed, tested, and fits the hardware. A manual sequence can be a good choice when the machine is unusual or the learner needs to inspect each transition. The requirement is the same in both cases: the recovery path must expose ownership and evidence.

Design Goal: A Dossier Another Person Can Use

Maya's dossier is a small repository plus protected references outside it. The repository is not a backup of her whole life. It is the explanation of how to restore the machine safely.

recovery-dossier/
  README.md
  hosts/
    field.md
  packages/
    explicit-packages.md
    third-party-or-foreign.md
  config/
    dotfiles/                 # non-secret configuration only
    nixos/                    # if this host uses NixOS
  services/
    note-preview.md
  data/
    restore-notes.md
  evidence/
    acceptance-checks.md
  decisions/
    manual-boundaries.md

The directory names are a teaching model, not a mandatory layout. What matters is that a future reader can find the answer to six questions:

1. What does this step change? A package database, a path, a unit, a user-owned configuration file, or a data store are different objects.
2. Why do we trust the input? An official repository, a reviewed configuration commit, a backup source, or a protected secret-provisioning process each needs its own statement.
3. Who owns the result? The package manager, root, Maya's normal user, an application, or a backup process may own different parts.
4. What should be true afterward? “The command exited successfully” is weaker than a visible condition such as “the service is active and returns its health response.”
5. What evidence records that condition? A package query, file metadata, a service status and log excerpt, a build result, or a restored document can earn the claim.
6. What is the bounded recovery action? Revert one configuration generation, remove one broken user config, re-provision one secret reference, or restore one data item—without deleting unrelated state.

This connects the whole track. The shell is a control surface, so every action needs a target and blast-radius prediction. Permissions are an access decision, so the dossier names which account must read a file. Packages import provenance and dependencies, so an unrecorded install source is not a harmless omission. Services have their own state and environment, so a successful interactive command cannot prove that a boot-time unit works. Declarative configuration helps describe a desired state, but it does not convert a secret, a note archive, or a host fact into configuration.

Proposed Model: Rebuild in Evidence-Bearing Stages

Maya does not aim to restore everything in one pass. She builds a ladder. A failed stage must leave enough evidence to choose the next check rather than repeat the whole rebuild.

The table gives an ordering rule: establish the thing a later check depends on before using that check as evidence. For example, Maya cannot diagnose an application service from logs until the base system can store and read logs. She cannot claim Git access is repaired because a public clone works if the real task requires a protected repository. She cannot treat a successful NixOS build as proof that a service is ready: a build is evidence about a candidate configuration, while runtime checks establish that the intended process actually has the inputs it needs.

Two administration paths, one recovery standard

The stages work for both administration styles introduced earlier in the track.

For an Arch-style host, the dossier may record an explicit package list, the configured repositories, any foreign or locally built packages, and the reasons they exist. Pacman can query the local package database and check whether package-owned files are present, but those facts do not prove that Maya's editor configuration or personal service is usable. The evidence needs to continue into the next stages. Arch Wiki: pacman

For a NixOS host, the dossier may put the system configuration and host module under version control, then use a test or switch workflow with a rollback plan. NixOS generations make configuration changes inspectable and can provide previous boot or switch targets when retained; they do not recreate an external account, private key, or user data backup. NixOS Manual: changing configuration and rollback

This is the trade-off, stated precisely: declaration reduces unrecorded drift for the state it describes, while explicit manual records can make unusual choices visible. Both approaches still need a boundary for secrets, mutable data, and host facts. Neither is a substitute for an acceptance test.

Walkthrough: The Service That Worked Only in a Terminal

At stage 4, Maya's note-preview service does not start. Her first thought is reasonable: the package must be missing. She ran the program from her terminal yesterday, and it responded on a local port.

The first evidence changes that model. The package query shows the executable is installed. The unit status says the service exits soon after start. Its log mentions that NOTES_TOKEN is missing. The following synthetic unit fragment makes the boundary visible:

[Service]
User=maya
WorkingDirectory=/home/maya/notes
EnvironmentFile=/home/maya/.config/note-preview/runtime.env
ExecStart=/usr/local/bin/note-preview --listen 127.0.0.1:8811

The terminal test used an environment variable exported in an interactive shell. The service starts in its own configured environment. The program file exists; the service's input does not. Reinstalling the package would add noise, not fix the failure.

Maya walks the dossier's evidence chain:

The capstone does not require a particular secret manager. It requires an interface: who can provision the value, where the service reads it, what happens if it is absent, and how Maya revokes or replaces it. That is enough information to recover the service without teaching a broader threat-modeling program.

So far: Maya did not solve the problem by remembering a magic command. She used the earlier service model: distinguish package presence, process identity, working path, configured environment, and runtime evidence. Each check ruled out one plausible cause.

Failure Review: What a Successful Rebuild Can Still Hide

Maya completes stages 1 through 5. The desktop looks familiar. That is encouraging, but it is not the final proof. She reviews the recovery path for failures that visual similarity can hide.

The common error is treating presence as correctness. A file can be present but unreadable. A process can run but receive the wrong environment. A configuration can be declared but not active. A backup can copy bytes without restoring the data the learner needs. The dossier needs an acceptance check for the user-facing claim, not merely for the previous command.

Trade-offs and Deliberate Manual Steps

A recovery dossier costs time. Writing acceptance checks, recording a third-party package, and separating data from configuration feel slower than cloning everything. That cost is real. On a small personal machine, some details may remain manual because automating them would be harder to review than doing them carefully once.

Maya records these deliberately manual boundaries:

• physical disk encryption passphrase and recovery-code handling are not stored in the repository;
• browser sign-in and hardware-token enrollment require an interactive, account-specific procedure;
• display calibration remains host-specific and is checked after login;
• caches are regenerated after the core workstation works;
• any unrecorded command discovered during a repair becomes a candidate for the dossier only after Maya understands its target, evidence, and rollback.

This improves the next rebuild because another person can see what they must supply and what they must not copy. It can still fail when a dependency, account provider, hardware device, or backup source has changed since the notes were tested. The boundary signal is simple: an acceptance check requires a hidden assumption that the dossier never named. When that happens, add the assumption and retest; do not hide it inside a longer setup script.

Evidence and Readiness

Before calling field recovered, Maya runs a tabletop review. She gives the dossier to a careful peer and asks them to explain the next action at each stage without using cedar or guessing. The peer does not need to execute destructive commands. They need to find the correct object, source, evidence, and recovery boundary.

Use this rubric for the review:

If one row is not ready, the appropriate result is not failure as a person. It is an identified recovery gap. Add the missing decision or evidence, then repeat the relevant stage. That is exactly what makes the platform maintainable.

Final Challenge: Write and Tabletop-Test Your Dossier

Create a recovery dossier for a real or imagined Linux workstation. You do not need to reinstall a machine for this exercise. Design the path, then tabletop-test it against one failure.

Your dossier must include:

1. a one-sentence definition of the minimum useful workstation;
2. six or more ordered recovery stages, each with its object, trusted input, acceptance evidence, and bounded recovery action;
3. one package provenance decision and one package verification check;
4. one configuration item, one secret reference, one mutable-data restore action, one cache policy, and one host-specific fact;
5. a service that could fail because its runtime environment differs from an interactive shell;
6. a failure trace that shows at least two rejected hypotheses before the repair;
7. a list of intentionally manual steps and the constraints that justify them.

A strong answer does not need many commands. It shows dependency order, distinguishes state classes, and proves each useful claim with an observable check. A weak answer says “clone the repo, install packages, restore backup” without naming what may leak, what may drift, what owns the files, or what tells the next person that the machine is actually usable.

Resources

• [WIKI] Arch Wiki: pacman — Focus: inspect installed-package ownership, queries, and file checks without treating the package database as proof of application readiness.
• [DOC] NixOS Manual — Focus: compare configuration changes, testing, generations, and rollback with the separate recovery of user state.
• [DOC] systemd.exec — Focus: inspect the execution environment of a service and why an interactive shell is not the service's configured runtime.
• [DOC] Git credentials — Focus: model a credential as a separately delivered input rather than ordinary repository configuration.

Key Takeaways

• A recovery dossier turns a rebuild into a chain of small, testable claims; a command list alone does not show whether the machine is usable.
• Rebuild in dependency order: base host, trusted software, non-secret configuration, runtime services, then sensitive and changing state.
• Package presence, a successful build, or a familiar desktop are partial signals. User-facing acceptance checks earn the stronger claim.
• Keep configuration, secrets, mutable data, caches, and host facts on separate recovery paths with explicit owners and boundaries.
• A manual step is acceptable when its constraint is visible and its result is checked; a hidden manual step is future repair debt.