Spinbox documentation

The documentation of Spinbox, at https://spin-stack.github.io/website/, built with Astro Starlight and published to GitHub Pages.

The rule this site keeps: a page is generated from the code it describes, or held to it by a check that fails the build, or it does not exist. Everything below is one of those checks.

go tool task install      # dependencies, through Socket Firewall (go tool sfw)
go tool task dev          # http://localhost:4321, live reload
go tool task sources      # spin, spin-terraform-aws and brand into .sources/, at the commits versions.yaml pins
go tool task check        # what CI runs: the reference against the sources, and the gate
go tool task gate         # the gates, the install, the tests, the public reference, the build, every link
go tool task exposure     # what this public repository shows: every ref, its PRs and issues
go tool task --list       # everything else

Task is a tool in go.mod, so go tool task is the version CI runs; the tasks below are named without it. task check is what CI runs: the reference against its sources, then task gate, which fails first on an install that skips the firewall (go tool sfw check) or a workflow step that is not one task (go tool taskgate).

• The sources are pinned in versions.yaml, go-tools' versions format, held by tools/sources/repo_test.go as every spin-stack repository is: spin, spin-terraform-aws and brand, each at one commit. task sources (tools/sources) fetches exactly those commits, with their history and tags, into .sources/, which is where SPIN, TERRAFORM and BRAND point unless given (SPIN=../spin for a checkout of your own). refgen fails when src/data/reference.json records another commit than the pins, so the two never disagree. spin is private: SOURCES_TOKEN, or git's own credentials, reads it. In CI the read-only sources App's token reaches git only as GIT_CONFIG_* in the one step that fetches.

• Without spin - a fork's pull request has no secret - CI runs task check:public: the gate, whose task reference:public fetches spin-terraform-aws and brand at their pins and runs refgen -only terraform,brand -check, which builds no CLI and keeps what the site says of spin as reference.json has it.

• The sync is .github/workflows/sync.yml, every day: task sources:bump moves the pins to the newest releases (spin only to one that holds the commit pinned, brand to its main), task reference regenerates, and the sync App force-pushes branch sync/sources and opens or updates its one pull request, which a person reviews; nothing merges it. spin is private and this repository public, so the pull request lists the pins that moved and the files that changed, and what spin's commits say - grouped by the pages each path of spin feeds - goes in one issue in spin, "Site vs spin main", with the release chain: spin-machine as spin pins it against its newest release, the last runs of machine.yml, propose.yml and fresh-install.yml, and what spinbox.dev runs. Every Monday the same issue says what spin main has past the pin. tools/sync writes all of it.

• The repository is public, and so is every pull request the moment it is opened. task exposure (go tool exposure) reads every ref's commits, pull request heads included, and the issues, pull requests and comments for secrets and for what is private without being one; .github/workflows/exposure.yml runs it every morning. A value public on purpose is answered in .github/exposure-allow.txt with why, a secret gitleaks takes for one in .gitleaks.toml.

• Pages are Markdown under src/content/docs/. Every page needs a description: it is its line in llms.txt. A page must be in src/lib/nav.mjs, or the build fails. Each group there belongs to a topic - Docs, Install and operate, Security, Reference - and the sidebar shows one topic's groups at a time (starlight-sidebar-topics). Images and diagrams zoom in place (starlight-image-zoom), and every page title offers its Markdown twin, copied or opened.

• Reference pages under src/content/docs/reference/ are generated by task reference from spin and spin-terraform-aws at their pins (SPIN=, TERRAFORM= to point elsewhere). Each names its source in its frontmatter (source: repository:path), and its footer links that source at the documented commit instead of an edit link. Edit the source, not the page. Every page's footer says which spin release an installation runs, and the tree the reference is generated from.

• Prose held to spin's own lists: a page's description is one line of at most 160 characters (it is its line in llms.txt), every SPIN_ variable a page names is one spin's hack/env-catalog.txt lists, and the table of states in concepts/workspaces.md is the API's WorkspaceState, both ways. task reference:check fails on each.

• What the site documents is src/data/reference.json, written by task reference. Two things it keeps apart: the spin release an installation runs (spin.installs, the newest release images.json has images of), and the spin commit the reference is generated from (spin.commit, with spin.tag empty when no release is cut from it, so the site says "generated from spin main at , not released"). With them, the commits of spin-terraform-aws and brand, and the feature board's counts, which the landing page shows. Every release a hand-written page names is pinned to the one an installation runs: task reference rewrites it, and task reference:check fails on another.

• The status page reference/status/ is written from spin features, the feature board a test in spin holds to the tree. A built row shows what says it exists, and the tests that check it end to end or what none checks yet (endToEnd, endToEndGap); the landing page counts the first. refgen fails on a field of the board it does not know, on a built row with both or neither, and on a test spin does not have. The bullets of overview/limitations.md are its limit rows, and task reference:check fails on a bullet that is not one, or a row no bullet leads with. The landing page's straight answers are limit rows too, and the check fails on one that is not.

• What a page says Spinbox does is a link to the feature board's row that says so: [idle suspend](<feature:Idle suspend, with a question before it that a keep answers>). The build points it at the row's area on the status page (src/lib/feature-links.mjs) and fails on a row the board does not have; task reference:check also fails on a row that is not built. The board is src/data/features.json, written by task reference.

• Commands on the other pages are held to the same checkouts: every spin command in a shell block must be one the CLI has, with flags its help lists, and every task one spin's Taskfile has (after a cd into another checkout, that one's). So is every spin command a string of src/lib/*.ts or src/components/*.astro holds - the landing page's story. task reference:check fails on one that is not.

• The landing page claims only what a test checks end to end: every feature="…" of a component and every step of src/lib/story.ts must name a built row of the board that names an end-to-end test.

• The AWS pages are held to spin-terraform-aws. Updating and removing an installation are the module's README, included verbatim between its <!-- BEGIN website:aws/update --> and <!-- BEGIN website:aws/remove --> markers and their END: edit the README, not aws/update.md or aws/remove.md. On every aws/ page, a tofu state rm or tofu import address must be a resource of the module, a -var and a tofu output a variable and an output of the root, and a snake_case name in backticks a variable or output of a module, or one of notTerraformNames with why. The names aws/prerequisites.md lists are the ones the installation's Route 53 records give, and the optional modules' beside them. A module ref, ?ref=, is the module's newest release (terraform.release in reference.json, the newest tag the documented commit holds), which task reference rewrites it to.

• Figures the code decides - a volume's commit size, how much older a runner may be, how long CloudWatch keeps the logs - are src/data/constants.json, read from spin's constants and the module's defaults by task reference, and a page shows one with <Value name="…" />.

• What a release is made of, reference/release.md, is written from spin's versions.yaml at the release installations run (its spin-machine), images.json and the module's newest release.

• Diagrams are the ones spin and spin-terraform-aws draw beside their sources (.dot, .d2): task reference copies each into src/assets/diagrams and writes its words to src/data/figures.json, which a Markdown twin carries in the picture's place. The site draws none of its own. <Figure name="…" caption="…" /> shows one.

• For models, the build writes llms.txt (every page, with its description), llms-full.txt (every page's Markdown) and a .md twin of each page, all from the same content (src/pages/). The build fails on a twin that still carries MDX: a component, an expression or a directive src/lib/pages.ts does not translate.

• The look is spin-stack/brand's: its palette, checked there for contrast and perceptual distance on real panels and through colour-vision deficiencies, and the organization's mark. task reference copies them from brand at its pin (BRAND= to point elsewhere) into src/styles/brand-*.css, src/assets/ and public/, and task reference:check fails on a copy that is not brand's; src/styles/custom.css says only how the site's parts use them.

• The dashboard's screenshots are the documented spin release's own: spin's site-shots.yml takes them on the KVM fleet (dashboard/e2e/site.spec.ts) and puts them on the release as site-shots.tar.gz, which task sources unpacks into .sources/spin-site-shots with the sources token. task reference copies the one of each test that shoots into src/assets/shots and records the release, the commit and the test in src/data/shots.json; task reference:check fails on a picture that is not the release's, and on a record of another release than the site documents. A release without the asset fails task sources, saying to give it one: gh workflow run site-shots.yml -R spin-stack/spin -f tag=<tag>. IBM Plex is served from the site, and a hero draws a workspace's disk as its layers, worked step by step (src/components/Hero.astro, Disk.astro). task links fails a page that loads a script, a stylesheet, a font or an image from another site.

• The site is served at SITE_URL + BASE_PATH, by default https://spin-stack.github.io and /website (a GitHub project page). Content links from the root (/concepts/network/) and the build puts the base in front; task links fails on one it cannot resolve.

• Links out of the site are opened by task links:external, with no credential, as a reader would: every link to another site and every ghcr.io reference a page quotes. A page links only to spin-stack repositories a reader can open (publicRepos in tools/refgen).

• Pushing to main builds and publishes to GitHub Pages (.github/workflows/pages.yml).

Contributing

Pull requests are welcome. One from a fork runs the Gate once a maintainer approves it, and never deploys: only main publishes. Dependencies are locked and installed through Socket Firewall, which go tool sfw check holds every install and every workflow to; pnpm-workspace.yaml names the few that may run an install script, and a release must be a week old before it is taken.

A security problem in Spinbox goes to a private advisory, never an issue: see Reporting a vulnerability.

License

Apache License 2.0, the code and the pages alike. See LICENSE.