Skip to main content

Docs components demo

This page exercises every docs component. It doubles as a visual test page.

UiScreen​

/stacks
The stacks view, live from the UI mock.
/nodes

UiCli​

Open Stacks and press New stack.

SetupForm and Cmd​

Your setup
On your laptop
ssh {{user}}@{{ip}}
[arch] sudo pacman -S docker
[debian,raspbian] sudo apt install docker.io
clouduler init --name {{cluster}}
Not set yet: {{user}}{{ip}}{{cluster}} (fill in the setup form above)

DistroTabs​

sudo pacman -S docker

OptionTable​

Option
Type / default
Reload
Description
cluster.namerequired
stringdefault "homelab"
needs restart
Name of the cluster.
Watch out: Cannot change after init.
proxy.enabled
booldefault true
live reload
Turn the built-in proxy on.
proxy.dns_publish
enumdefault all-nodes
live reload
Which nodes publish DNS records.
alerts.discord
urlno default
live reload
Discord webhook for alerts.
drives.default
stringno default
n/a
Default drive.
a.b
intdefault 1
live reload
Filler.
a.c
intdefault 2
live reload
Filler.
a.d
intdefault 3
live reload
Filler.
a.e
intdefault 4
needs restart
Filler (the filter box appears above 8 rows).

Quirk​

Mermaid​

How screens are produced​

<UiScreen> does not show hand-made screenshots. It embeds the real web UI, built against an in-memory mock backend (ui/src/mock/). All network access in the UI goes through one transport seam, and the mock swaps it for fake routes backed by a scenario, so every screen is clickable and always matches the current UI code.

  • Scenarios (ui/src/mock/scenarios/) describe a whole cluster: nodes, networks, stacks, instances. Pick one with the scenario prop.
  • Contract tests (ui/src/mock/contract.test.ts) check the mock against the real API client, so the mock cannot silently drift from the backend. An unmocked route logs [mock] to the console and answers 501.
  • Fallback images: if the mock is not served (no JavaScript, or the mock is missing), <UiScreen> shows static/img/ui/<slug>.png, generated by Playwright from the same mock. Each live screen also has an "Open full screen" link.

Add a scenario​

  1. Create ui/src/mock/scenarios/my-scenario.ts exporting a function that returns a MockDb built with ScenarioBuilder.
  2. Register it in ui/src/mock/scenarios/index.ts.
  3. Use it: <UiScreen scenario="my-scenario" route="/stacks" alt="..." />.

The contract and render tests pick it up automatically. Use example.com domains and documentation IPs only. See ui/src/mock/README.md for the builder API.

Regenerate screenshots​

npm run setup:browsers   # once: installs Playwright chromium
npm run build:ui-mock    # builds the UI against the mock into static/ui-mock/
npm run screenshots      # renders light and dark PNGs for every <UiScreen>
npm run build:full       # all of the above, then the site build

npm run screenshots scans content/**/*.mdx, so a new <UiScreen> is picked up without configuration. It skips PNGs newer than both the mock build and the page; pass -- --force to redo everything. It exits non-zero if any page throws or logs a [mock] error, listing them all. static/ui-mock/ and static/img/ui/ are gitignored and must be generated at build time.