coulomb/railiance-bootstrap
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
railiance-bootstrap/SCOPE.md
tegwick 0814ed3a19
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 1s
Details
Repurpose as the Railiance bootstrap path 
This repo carried a copied declaration identifying it as the S2 cluster runtime
layer - byte-similar to railiance-cluster, with which it shares no git history
but nearly all of its content. It was one of four repos (bootstrap, cluster,
hosts, infra) created by copying working trees as the S1/S2 layering idea
emerged, and the INTENT was copied along with everything else.

Its own QUICKSTART.md - set up your very first Railiance host - describes what
the repo is actually for. INTENT.md and SCOPE.md now declare that: turning a
single bare virtual machine into a working Railiance, then handing off to the
ordinary layers.

Inherited S2-era content in ansible/, helm/, docs/ and wiki/ is not yet sorted;
SCOPE records that restructuring is in progress rather than claiming it is done.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-11 22:41:29 +02:00

4.1 KiB
Raw Permalink Blame History

SCOPE

This file helps you quickly understand what this repository is about, when it is relevant, and when it is not. It is intentionally lightweight and may be incomplete.

One-liner

The Railiance bootstrap path — turning a single bare virtual machine into a working Railiance, then handing off to the ordinary layers.

Core Idea

Every Railiance layer describes how to operate a system that already exists. S1 converges a substrate, S2 runs a cluster on it, S3 provides shared services. None of them owns the first step: you have one virtual machine and an intention — now what?

This repo owns that step. It sequences the layers into a runnable path from nothing to a working Railiance, and then gets out of the way. One of Railiance's goals is that initiating a new Railiance should be easy; this repo is where that claim is made testable.

Repository status: this repo previously carried a copied declaration identifying it as the S2 cluster runtime layer, duplicating railiance-cluster. That was wrong and has been corrected — see INTENT.md → History. Restructuring of the inherited content is in progress; expect S2-era material still present in ansible/, helm/, docs/ and wiki/ that has not yet been sorted into "bootstrap path" versus "belongs to S1/S2".

In Scope

  • The newcomer path from bare VM to working Railiance (QUICKSTART.md)
  • Prerequisite and ordering contracts between substrate, cluster, secrets, forge
  • Bootstrap secret material: how it is introduced, and how it is retired once the real custody path (OpenBao, S3) exists
  • The handoff point where the ordinary layers take over
  • A rehearsable test that the bootstrap path still works

Out of Scope

  • OS provisioning, hardening, server baseline → railiance-infra (S1)
  • k3s, Helm, ingress, CNI, admission controllers, operators, kubeconfig management → railiance-cluster (S2)
  • Shared stateful services: databases, cache, secrets, object storage → railiance-platform (S3)
  • Ongoing operation of anything. After handoff this repo has no running role
  • Duplicating layer content — this repo sequences layers, it does not own what they own

Relevant When

  • Standing up a new Railiance from nothing
  • Establishing or changing the ordering between substrate, cluster and secrets
  • Resolving a bootstrap chicken-and-egg problem (needing a secret to fetch the code that manages secrets)
  • Testing that the adoption path still works by raising a fresh Railiance

Not Relevant When

  • Operating, upgrading, or troubleshooting an existing Railiance — that belongs to the layer that owns the concern
  • Deploying a workload (that is rapp-* and S5)

Current State

  • Status: repurposed, restructuring in progress
  • The bootstrap intent is declared (INTENT.md, 2026-08-11); the inherited S2 content has not yet been sorted
  • QUICKSTART.md is the existing seed of the newcomer path; a near-identical copy also exists in railiance-cluster and the two need consolidating
  • install/ exists in railiance-cluster but not here, and is a candidate to move
  • Open: whether the bootstrap path has ever been walked end to end from scratch

How It Fits

  • Sequences: railiance-infra (S1) → railiance-cluster (S2) → railiance-platform (S3), and hands off once they can run themselves
  • Downstream: everything, indirectly — this is the entry point
  • Often used with: railiance-master (which owns the layer model this sequences), railiance-platform (which takes over secret custody after bootstrap material is retired)

Terminology

  • Preferred terms: bootstrap path, ignition sequence, handoff point, bootstrap secret material
  • Potentially confusing: "bootstrap" here means initiating a whole Railiance, not cluster bootstrap in the k3s sense (that is S2), and not ArgoCD app-of-apps bootstrapping (that is S3's argocd/bootstrap/)

Getting Oriented

  • Start with: INTENT.md, then QUICKSTART.md
  • Context: railiance-platform/ArchitectureBlueprint.md §4 records this repo's lineage and status
  • Pre-conditions: one reachable virtual machine, and nothing else