feat: first boot screens for the role of this node and a Keel Cloud key #15

Merged

marcos-mendez merged 2 commits from feat/first-boot-role into master

2026-09-30 07:05:43 -03:00

marcos-mendez commented

2026-09-30 06:38:19 -03:00

(Migrated from github.com)

Summary

The first boot flow handbook decision 0020 requires: the role is chosen at installation, by hand, on each node, and a Keel Cloud API key is an option, never a precondition. The maintainer tested Template B2 and installation never asked Standalone or Cloud.

keelfirstboot.py role|cloud, the entry point the inithooks hooks 75keel-role and 80keel-cloud run (Keel-Linux/inithooks companion PR).
Role of this node: Standalone (default), Primary, Replica. Primary and Replica go through the Overlay network screen's own actions (wgscreen) and the Database mode screen of the role, loaded as confconsole loads it: nothing duplicated. Every step that needs the other node says exactly what to do there, and Later names the confconsole entry that finishes it. The role reaches the description only through the Database mode screen, so a node left half way is still standalone. A fresh Standalone records database.server.role: standalone (validated, nothing applied).
Console confirm at first boot: the overlay screen offers keel network confirm from the console, as it already did. It is sound at first boot: the window exists so a change cannot lock the operator out, the screen never moves the uplink (--skip-uplink), so the console is the one path it cannot break. What it does not test (the overlay, SSH over the uplink) the screens say to test from the other node. In LXC the console is /dev/lxc/tty1, accepted from keel 0.11.2 (Keel-Linux/keel#51); Recommends keel (>= 0.11.2).
Keel Cloud API key: empty means standalone (hub.api_key: skip); a key goes to /etc/keel/secrets/cloud_api_key (root, 0600) and the description references it as hub.api_key: {file: ...}. The screen says: "The key takes effect once the Keel Cloud service exists; nothing on this appliance contacts any service now." Also an Instance menu entry, Keel Cloud.
Non-interactive: not asked when the description declares database.server.role or hub.api_key, or HUB_APIKEY is preseeded (SKIP, or a key, stored without a screen), nor without a terminal or keel. keel-init asks again. The screens draw on the terminal of standard input when standard output is not one (the dbpass.py fix).
Usage screen: no TKLBAM status line and no "TurnKey Backups and Cloud Deployment / https://hub.turnkeylinux.org" footer.
Found on a 24 row LXC console, fixed for confconsole as well: the Primary and Replica forms left no room for their fields ("Can't make sub-window"), so a long text is read first in a box that scrolls; dialog cut 'Answer on' at 44 characters, so fields hold up to 1024; password boxes are sized to their text; the first boot console is no taller than the terminal.

Test plan

tests/test_first_boot.py (63 tests), usage, database mode and menu tests updated: 636 passed with a keel 0.11.2 at hand (631 and 5 skipped without), 100 percent lines and branches over the measured package, which gains keelfirstboot
Live, Template B2 image in LXC (role-a, role-b) with the built debs of this PR, inithooks and keel#51:
- Primary: overlay address, console confirm (confirmed from the console /dev/lxc/tty1), Later on the database step, key saved 0600; finished from confconsole (Overlay network > Add peer, Database mode > Primary, handout)
- Replica: overlay on the primary's /64, primary as peer, the "on the PRIMARY" instructions, pasted password, destroy confirmation, replication running over the overlay (Slave_IO_Running: Yes), empty key recorded as skip, keel diff no drift
- Standalone: recorded, no apply, no drift
- Non-interactive: a description declaring both, no screen, reasons in the journal
- Usage screen without the TKLBAM and hub lines
CI green

## Summary The first boot flow handbook decision 0020 requires: the role is chosen at installation, by hand, on each node, and a Keel Cloud API key is an option, never a precondition. The maintainer tested Template B2 and installation never asked Standalone or Cloud. - `keelfirstboot.py role|cloud`, the entry point the inithooks hooks `75keel-role` and `80keel-cloud` run (Keel-Linux/inithooks companion PR). - **Role of this node**: Standalone (default), Primary, Replica. Primary and Replica go through the Overlay network screen's own actions (`wgscreen`) and the Database mode screen of the role, loaded as confconsole loads it: nothing duplicated. Every step that needs the other node says exactly what to do there, and Later names the confconsole entry that finishes it. The role reaches the description only through the Database mode screen, so a node left half way is still standalone. A fresh Standalone records `database.server.role: standalone` (validated, nothing applied). - **Console confirm at first boot**: the overlay screen offers `keel network confirm` from the console, as it already did. It is sound at first boot: the window exists so a change cannot lock the operator out, the screen never moves the uplink (`--skip-uplink`), so the console is the one path it cannot break. What it does not test (the overlay, SSH over the uplink) the screens say to test from the other node. In LXC the console is `/dev/lxc/tty1`, accepted from keel 0.11.2 (Keel-Linux/keel#51); Recommends `keel (>= 0.11.2)`. - **Keel Cloud API key**: empty means standalone (`hub.api_key: skip`); a key goes to `/etc/keel/secrets/cloud_api_key` (root, 0600) and the description references it as `hub.api_key: {file: ...}`. The screen says: "The key takes effect once the Keel Cloud service exists; nothing on this appliance contacts any service now." Also an Instance menu entry, Keel Cloud. - **Non-interactive**: not asked when the description declares `database.server.role` or `hub.api_key`, or `HUB_APIKEY` is preseeded (SKIP, or a key, stored without a screen), nor without a terminal or keel. keel-init asks again. The screens draw on the terminal of standard input when standard output is not one (the dbpass.py fix). - **Usage screen**: no TKLBAM status line and no "TurnKey Backups and Cloud Deployment / https://hub.turnkeylinux.org" footer. - Found on a 24 row LXC console, fixed for confconsole as well: the Primary and Replica forms left no room for their fields ("Can't make sub-window"), so a long text is read first in a box that scrolls; dialog cut 'Answer on' at 44 characters, so fields hold up to 1024; password boxes are sized to their text; the first boot console is no taller than the terminal. ## Test plan - [x] `tests/test_first_boot.py` (63 tests), usage, database mode and menu tests updated: 636 passed with a keel 0.11.2 at hand (631 and 5 skipped without), 100 percent lines and branches over the measured package, which gains `keelfirstboot` - [x] Live, Template B2 image in LXC (role-a, role-b) with the built debs of this PR, inithooks and keel#51: - Primary: overlay address, console confirm (`confirmed from the console /dev/lxc/tty1`), Later on the database step, key saved 0600; finished from confconsole (Overlay network > Add peer, Database mode > Primary, handout) - Replica: overlay on the primary's /64, primary as peer, the "on the PRIMARY" instructions, pasted password, destroy confirmation, replication running over the overlay (`Slave_IO_Running: Yes`), empty key recorded as skip, `keel diff` no drift - Standalone: recorded, no apply, no drift - Non-interactive: a description declaring both, no screen, reasons in the journal - Usage screen without the TKLBAM and hub lines - [x] CI green