Adding an image to Kiln
On this page
Kiln installs Glassworks on a frame by default. It can also install a community image: another project's software for the same device, as that project publishes it. On the lululemon Mirror that's Glass Panes. We'd like more of them: if your project makes an image for a frame Kiln supports, this page says how to add it.
Kiln downloads the image itself, checks every file against the SHA-256 you publish, and writes it with the same safety steps as Glassworks. The person doesn't download or select anything. Your image gets a card on the frame's page, a line that says you make it and that questions go to your project, and a link of its own that opens straight into its install.
Status: the first version supports the Mirror (lululemon-mirror), whose page is in beta, open to everyone.
The design is in docs/design/kiln/community-images.md.
What an image is: a recipe
An image is data, never code. It's an ImageRecipe
(kiln/packages/kiln-core/src/images.ts) in the frame's
installer, in the frame's list of images. The Mirror's list is MIRROR_IMAGES in
frames/lululemon-mirror/installer/src/choices.ts.
Glassworks is always first.
export const GLASS_PANES_IMAGE: ImageRecipe = {
id: 'glass-panes', // the ?image= id: lower case, digits, dashes
name: 'Glass Panes',
community: true,
by: { name: 'git-nimrod', href: 'https://github.com/git-nimrod' },
project: { name: 'git-nimrod/glass-panes', href: 'https://github.com/git-nimrod/glass-panes' },
licence: 'MIT; the image’s parts keep their own',
summary: 'Android 6.0.1 for the Mirror as its release has it, with its own Mirror Kiosk app.',
support: { name: 'Glass Panes on GitHub', href: 'https://github.com/git-nimrod/glass-panes/issues' },
release: { name: 'mirror-android-2', href: 'https://github.com/git-nimrod/glass-panes/releases/tag/mirror-android-2' },
next: { name: 'its README', href: 'https://github.com/git-nimrod/glass-panes#readme' },
files: [
{ name: 'system.img', url: 'https://github.com/…/system.img', refract: 'glass-panes/mirror-android-2/system.img',
size: 850905808, sha256: 'bdb6b844…e35c1' },
{ name: 'userdata.sparse', url: 'https://github.com/…/userdata.sparse', refract: 'glass-panes/mirror-android-2/userdata.sparse',
size: 154944572, sha256: '74b1f57a…cf908' },
],
steps: [
{ do: 'download', file: 'system.img' },
{ do: 'download', file: 'userdata.sparse' },
{ do: 'fastboot' },
{ do: 'flash', partition: 'system', file: 'system.img' },
{ do: 'flash', partition: 'userdata', file: 'userdata.sparse' },
{ do: 'restart' },
],
};
| Field | What it is |
|---|---|
id |
The image's id in Kiln's link. glassworks is taken |
name, by, project |
Shown on the card, and on every screen of the install: "Glass Panes is made by git-nimrod. Questions about it go to its project." They must match the frame's credits entry for the image (frames/<id>/design/frame.json) |
licence, summary |
The card's licence row and its one line |
support |
Where questions go. The card says "Its project, on GitHub" |
release |
The release the files come from, named on the download screen |
next |
Where the person carries on after Done, e.g. your install guide |
files |
Every file Kiln downloads: the release URL, its id on Refract, its exact size in bytes, and its SHA-256 in lower-case hex |
steps |
What Kiln does, in order, from the step library below |
The step library
Recipes can only use these steps. Each is reviewed code in Kiln; the frame says which ones it can
run and which partitions a recipe may write (MIRROR_ACCESS: system and userdata, never the
bootloader, boot or the modem).
| Step | Fields | What Kiln does |
|---|---|---|
download |
file |
Downloads the file through Refract and checks its size and SHA-256 as it arrives. A file that doesn't match is emptied, and the screen shows it as Kiln's bug, with Try again and Report this |
fastboot |
Shows the frame's own steps to put the device in fastboot, then connects. Read-only | |
flash |
partition, file |
Checks the stored file's size and SHA-256 again, as the very copy it sends, then writes it to the partition |
restart |
Restarts the device into what was written | |
patch |
file, makes |
Kiln's own change to a downloaded image. Glassworks only |
first-start |
Kiln's first start over adb with the browser's key. Glassworks only | |
wifi |
file, template, makes |
Optional: when the person gives a network, saves it in a copy of a checked userdata image (file), named makes. It writes one file, /misc/wifi/wpa_supplicant.conf: the template from the checked system image (template's /etc/wifi/wpa_supplicant.conf, read where it lies), then the network with its PSK, never the password. It re-hashes the userdata as it reads it. Without a network, makes is the userdata as published |
wifi-on |
key |
After the restart, when a network was saved: connects over adb with the image's own published adb key (key, a checked download, held in memory for that one connection) and runs svc wifi enable, nothing else, then waits for dumpsys wifi to say "Wi-Fi is enabled" (the driver up, not only the switch asked for). For an image that ships with Wi-Fi off, so the saved network joins without anyone opening its Settings |
A new kind of step is a change to Kiln's code, with its own review and tests, not part of adding an image.
Kiln's safety steps
Kiln puts its own steps around every recipe. A recipe can't list, skip or move them:
- Checks, right after the device connects: read-only, and a failed check stops the install before anything is written.
- Backup: what the device has, or, where it can't be read back (the Mirror), the SHA-256 of each file about to be written, in the log.
- The warning: what will be replaced and what can't come back. The person must tick it.
- The way back, on Done: how to put the other image back.
Every file is downloaded and checked before Kiln connects to the device, so a failed download never leaves a half-written device.
The rules a recipe must pass
validateImage() checks every recipe in the frame's tests, so a pull request that breaks one fails
CI:
- Only steps from the library, only steps the frame can run, and no extra fields on a step.
- Every file has an https URL, a Refract id, a size and a SHA-256, and is downloaded exactly once.
- Every
downloadcomes before the device is connected. flashwrites a checked file, afterfastboot, to a partition the frame allows.- The recipe writes something and ends with
restart. - A community image has no
patchand nofirst-start: it goes on as its project publishes it. wifitakes only checked downloads and names one new file; it's listed once.wifi-oncomes afterrestartand awifistep, once, with a key that is a checked download. It takes no command: what it runs is Kiln's code.- The frame's own test checks each file against Refract's allowlist: the same source (a release file, or a repository file at a pinned commit), size and SHA-256.
Adding your image, step by step
- Publish a release with your files and their SHA-256 (a
SHA256SUMSfile, or GitHub's own digests). Kiln pins one release; a new release is a new pull request. - Add the files to Refract's allowlist,
kiln/workers/refract/allowlist.json, as its README says. Read the size and hash from GitHub:gh api repos/<owner>/<repo>/releases/tags/<tag> --jq '.assets[] | "\(.name) \(.size) \(.digest)"' - Credit your project in the frame's
frame.jsoncredits, with your name, your project and the licence. - Add your recipe to the frame's list of images, after Glassworks, and run the frame's tests:
npm test -w @glassworks/<frame>-installer. - Open a pull request with the release you pin, the terms that let Refract pass your files on, and what you tested.
Only URLs and hashes go in the repo, never an image's bytes.
What review a community image needs
The maintainer reviews every community image before Kiln offers it. The pull request needs:
- The terms. Whether Refract may pass the files on, written down next to the frame's research, as
frames/lululemon-mirror/research/community-image-terms.mddoes for the Mirror. - The release. A tagged release, its files and their SHA-256s. Kiln never follows "latest".
- The partitions. Only those the frame allows. A recipe that needs another partition, or a new step, needs a change to Kiln first.
- A run on a real device: install the image through Kiln (the frame's page with
?image=<id>), then install Glassworks back from its Done, and say what you saw. - The Refract deploy. The root thread deploys Refract once the allowlist change is merged; until then the download fails, as Kiln's bug to report.
The link to your image
Each image has a link that opens the frame's page straight into its install, with no choice first:
https://kiln.glassworks.dev/<frame>?image=<id>
https://kiln.glassworks.dev/lululemon-mirror?image=glass-panes
Put it in your README. Every safety step stays: nothing downloads before the person clicks, and
"Install Glassworks instead" is in the foot. An unknown id, or glassworks, opens the normal page.
On a frame whose page isn't open yet (not alpha or later), add apk=release (or apk=local):
https://kiln.glassworks.dev/<frame>?apk=release&image=<id>.