Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/techofourown/sw-ourbox-installer

Host-side mission media composer for OurBox installers
https://github.com/techofourown/sw-ourbox-installer

Last synced: 3 months ago
JSON representation

Host-side mission media composer for OurBox installers

Awesome Lists containing this project

README 

          
# OurBox Installer



`sw-ourbox-installer` is the host-side front door for composing OurBox mission

media.



Current scope:



- target support: `woodbox` and `matchbox`

- host-side selection: choose an exact target OS artifact on the host

- host-side application selection:

  - Woodbox: choose one or more application catalogs, merge them into one

    effective catalog, and select the desired app set

  - Matchbox: choose one published arm64 application bundle for the selected

    target architecture

- mission output: write a `mission-manifest.json` plus staged OS bytes,

  staged application bytes, and selected metadata

- media compose: delegate to a vendored target adapter snapshot while pulling

  the published target installer substrate artifact automatically



What this repo still does not do yet:



- Tinderbox support

- target-independent substrate composition



The immediate win is no longer Woodbox-only. The host now resolves the selected

target OS artifact, the selected application input for that target, and the

published target installer substrate up front, stages the mission directory,

and invokes a vendored target adapter to compose installer media that installs

from local mission bytes.



For both Woodbox and Matchbox, the supported install path now purges

target-side artifact browsing and pulling. The target installer consumes only

the embedded local mission bytes.



## Usage



From a normal checkout of `sw-ourbox-installer`:



```bash

git clone --recurse-submodules https://github.com/techofourown/sw-ourbox-installer.git

cd sw-ourbox-installer

./tools/prepare-installer-media.sh

# move the installer media to the target machine, boot it, follow the prompts,

# let it power off, remove the installer media, then boot the installed system disk

```



When run from a terminal, the host composer now mirrors the old installer UX:



- it prompts for the target type first

- it prompts for the OS artifact first

- the default OS path must resolve through the upstream OS catalog; if that

  catalog is unavailable or malformed, the run fails fast

- `ENTER` accepts the default lane choice

- `c` chooses a different lane

- `l` lists catalog rows newest-first with `n`/`p` page navigation

- `r` enters a custom OCI ref

- `o` overrides the upstream repo/catalog

- after OS selection, it prompts for one or more application catalogs

- for official Woodbox catalogs, the default catalog ids must come from

  upstream `sw-ourbox-os` install-defaults data

- if that upstream defaults artifact is missing or malformed, the installer

  fails fast instead of falling back to adapter-local default policy

- official Woodbox catalog ids resolve through each catalog repo's published

  `catalog.tsv`, so the installer picks a pinned bundle for the requested

  channel and target architecture instead of trusting floating bundle tags

- if an upstream catalog cannot be fetched or does not expose a compatible

  row for the requested channel and architecture, the official default path

  fails fast instead of degrading to mutable non-catalog tags

- if the selected catalogs provide the same app uid from multiple catalogs, it

  only stops when the duplicated app definitions differ; identical duplicates

  are deduped automatically

- after duplicate app sources are resolved, it merges the catalogs into one

  effective catalog and prompts for the applications:

  - `ENTER` uses the merged default app set

  - `a` installs all apps from the merged catalog

  - `c` chooses a custom app set by number

- after application selection, it asks whether you want to stage installed-target

  SSH access at all:

  - `ENTER` or `n` continues without any installed-target SSH key

  - `y` opens the named-key chooser

  - in the named-key chooser, pick an existing named key to reuse it across

    installs and target families

  - `n` creates a new named key

  - `d` deletes one named key

  - `x` deletes all named keys

- then it lists removable USB target media, makes you choose by number, and

  requires `SELECT` before the compose/flash step continues

- the normal no-flag path flashes removable media; it does not keep extra build

  artifacts by default



Passing `--target`, `--os-channel`, or `--substrate-channel` changes the default

choice shown in those prompts. Passing `--os-ref` or `--substrate-ref` skips the

corresponding prompt and uses the exact ref non-interactively. Passing

`--all-apps` or `--app-ids` skips the interactive application chooser.



Useful flags:



- `--target TARGET` to preselect the target type instead of using the interactive target picker

- `--os-channel CHANNEL` to change the default OS lane offered in the host-side prompt

- `--os-ref REF` to choose an explicit OS artifact ref instead of the interactive picker

- `--substrate-channel CHANNEL[,CHANNEL...]` to preselect one or more application catalog ids in the prompt flow

- `--substrate-ref REF[,REF...]` to choose one or more explicit application catalog refs instead of the interactive picker; a ref may point at an exact bundle or at a catalog index such as `ghcr.io/example/catalog:catalog-amd64`, which will be resolved to the newest pinned bundle for the requested channel and architecture

- `--all-apps` to install every app published by the merged catalog set

- `--app-ids ID[,ID...]` to install an explicit subset of apps from the merged catalog set

- `--app-source-resolutions APP_UID=CATALOG_ID[,APP_UID=CATALOG_ID...]` to resolve duplicate app sources non-interactively

- `--installed-target-ssh-key-name NAME` to reuse or create a named host-side SSH key and stage its public key for the installed target

- `--mission-only` to stage only the mission directory under `./out/` (or `--output-dir`)

- `--compose-only` to compose installer media to disk under `./out/` (or `--output-dir`) without flashing

- `--output-dir DIR` to keep staged mission or composed media in a specific directory for those explicit non-default modes

- `--flash-device /dev/...` to bypass the interactive USB picker and flash that exact device

- `--help` to print the optional CI/dev flags without changing the normal no-flag operator flow



Cache behavior:



- the tool keeps a host-side cache of pulled artifacts

- when matching cached assets are available, it asks whether to reuse them

- at the end of compose, it offers to clear cached assets to reclaim disk space



Installed-target SSH behavior:



- host-side installed-target SSH staging is optional

- if you skip it, compose still continues and the mission carries no staged

  installed-target SSH key

- named host-side SSH keys are stored in `${XDG_STATE_HOME:-$HOME/.local/state}/ourbox/installed-target-ssh-keys` by default

- the staged mission carries only the selected public key, never the private key

- the installed target can use that staged host key for key-based SSH

- password-based installed-target SSH remains a separate target-side prompt during installation



## Repository contract



- `schemas/mission-manifest.schema.json`

  - JSON Schema for the staged mission-manifest contract

- `tools/cache.sh`

  - host-side OCI cache plumbing

- `tools/vendor-adapter.sh`

  - copies target adapter surfaces into `vendor/`

- `vendor/matchbox/`

  - pinned snapshot of the Matchbox adapter surface used for phase-one execution

- `vendor/woodbox/`

  - pinned snapshot of the Woodbox adapter surface used for phase-one execution



Phase one uses the vendored adapter scripts as the execution surface and points

them at the published installer substrate artifact for the selected target

during target-specific media composition.



Terminology note:



- the transport artifact is named `ourbox-substrate`

- the user-facing concept is now one or more application catalogs plus a

  selected app set from the merged effective catalog