# cairn: start here to build your own > For a coding agent whose person wants a homelab stack like cairn. cairn is > the stack we run at home. Each server's operating system is a container > image built and boot-tested in public CI, signed with our own keys, and > sealed so a disk unlocks only for a system we signed. It is published as a > reference to copy: the method and the code carry over, and the keys do > not. Our images are built for our hardware and boot under our keys. This file holds addresses and an order of work. The facts live in the pages and repositories it names. Where this file and a source disagree, the source is right. ## Read first 1. https://cairn.dunn.dev/llms.txt The index of the site. 2. https://cairn.dunn.dev/llms-full.txt The architecture and install pages as text: principles, the image, the pipeline, the trust chain, sealing, running a host, verification. 3. https://cairn.dunn.dev/guide/ The same ideas built up from first principles. Send the person here when a concept is new to them. Its last chapter, "Your lab", lays the work out as seven rungs, with one thing for a fork to supply at each. 4. The repositories, each from its own entry file: - https://gitlab.com/dunn.dev/cairn/example README.md, then the README.md and docs/decisions.md of each lane under lanes/. - https://gitlab.com/dunn.dev/cairn/pipeline README.md, then the README.md of each component that has its own directory under templates/. - https://gitlab.com/dunn.dev/cairn/base AGENTS.md, then README.md, then the decision in docs/decisions.md behind any topic AGENTS.md names. ## Ask the person - Which machines, and does each have a TPM and firmware that lets its owner replace the Secure Boot keys? - Who is there when a machine boots: someone to type a passphrase, or nobody? - Does any machine need ZFS or an NVIDIA GPU? base's README lists a flavor for each. - Where will the images be built and stored? The pipeline is written as GitLab CI/CD components. On another forge the method carries over and the components need rewriting. ## What to fork - cairn/example first. Fork it, keep the one lane that fits the answers above and delete the others, as its README describes. The fork builds on our published base image, on GitLab's shared runners, and pushes to its own registry. - cairn/base when the person wants the whole chain to be theirs: a base image of their own, signed with keys they minted. base's README, under "Fork and roll", names the files and CI variables that carry the keys. - cairn/pipeline only to change a component. Otherwise include it from the GitLab CI/CD catalog at a major version, as example does. ## What to change - Keys. Mint a new set with the ceremony in base (`just sb-ceremony-mint`) and replace every public half baked into the image. Private halves go in protected CI variables or stay offline, never in a repository. Never reuse ours. - Registry paths. Every registry.gitlab.com/dunn.dev/cairn/ reference that should point at the person's own images. - Runner tags. The defaults in base and pipeline name our runners. - Hosts. Users, SSH keys, services and hardware specifics belong in a private repository layered on the public image. Ours are kept that way. - Names. cairn and our host names are ours. Pick new ones. ## What to keep - The gate. The stable tag on a sealed image moves only after that exact artifact boots in CI. - Sealing. The root filesystem that boots is the one that was signed, and disk unlock is tied to the key behind that signature. - Promotion by tag. A host pulls a promoted image on its owner's timeline. CI never reaches a running host. - Published anchors. The public half of every key and its fingerprint, with a command that checks each claim from outside. - A decision log in every repository. - A recovery passphrase on every encrypted disk before its unlock changes. ## First steps 1. Read the sources above. Tell the person in a few lines what cairn does and which rung of "Your lab" their answers put them on. 2. Fork cairn/example and keep one lane. Change its Containerfile to add one thing they want, push to main, and watch CI build and promote the image into their registry. 3. Install that image on one machine they can afford to wipe. The lane's README says what that lane needs at boot, and https://cairn.dunn.dev/how-we-install/ shows how we install ours. 4. Once that holds, and if they want the chain to be theirs: fork cairn/base, mint keys, set the runner tags and CI variables, and get a sealed base to boot in their own CI. 5. Publish their public keys and fingerprints the way https://cairn.dunn.dev/architecture/#verify does. ## Take care - Never install one of our images with the firmware in Setup Mode. That can enrol our Secure Boot keys on the machine. - Stop and ask before any step that writes to a disk, enrols firmware keys or changes how a disk unlocks. - Say so when a source does not answer a question. We would like to hear what was missing; the contact is at the foot of https://cairn.dunn.dev/.