ucoin

The uCore installer — a TUI (built with the Charm stack) that handles Ignition files for you and builds a bootable ISO.

Build an installer ISO

build-iso produces a bootable ISO that has ucoin (this installer) embedded in it and is pre-configured to install a container image you provide (e.g. a ghcr.io/<namespace>/<repository>:stable or :testing image). It is fully non-interactive: it compiles the ucoin binary, bakes a default config that pre-selects your image, writes a builder Ignition config that installs the binary plus an autostart service to launch ucoin on boot, and runs coreos-installer iso customize to emit the resulting ISO.

A base CoreOS/uCore live ISO is required to customise — supply it via UCOIN_BASE_ISO, the BASE_ISO argument, or --base-iso. The output path defaults to ucoin-builder.iso (--builder-output) and the coreos-installer invocation can be overridden with UCOIN_BUILDER_CMD.

# UCOIN_BASE_ISO must point at a CoreOS/uCore live ISO
UCOIN_BASE_ISO=/path/to/ucore-live.iso \
  just build-iso ghcr.io/<namespace>/<repository>:testing
# …or pass the base ISO explicitly:
just build-iso ghcr.io/<namespace>/<repository>:testing /path/to/ucore-live.iso

Booting the resulting ISO launches ucoin (autostart) with your image already selected as the FROM, after which you configure Ignition and install to disk.

Build the ucoin binary

build just compiles the ucoin binary (stripped, with -ldflags=-s -w), defaulting to ./ucoin (override with just build <output>):

just build

Run interactively

just run

The flow is a step-by-step wizard: enter the FROM image → choose/configure Ignition (one screen per concern, with a progress bar) → build.

What the Ignition covers

The Generate wizard builds an Ignition v3.4.0 config covering:

• Users — name, a bcrypt-hashed account password (plaintext never stored), and SSH access. For SSH you can either paste existing public keys or let the installer generate an ed25519 keypair from a passphrase you enter: the public key is embedded in authorized_keys and the encrypted private key (ucoin-<user>-id_ed25519, chmod 600) is written to the working directory for you to keep.
• Groups (recommended) — sudo adds the user to wheel (passwordless sudo on uCore/FCOS); the form prefills adm,systemd-journal. Append arbitrary groups too (e.g. docker).
• Hostname — written to /etc/hostname.
• System — timezone via an /etc/localtime symlink (default Etc/UTC, fuzzy-searchable), plus a toggle to apply recommended systemd units (sshd, systemd-timesyncd, fstrim.timer).
• Storage — a fuzzy-searchable drive selector lists the detected disks (lsblk, falling back to /sys/block) so you pick the target instead of typing a path. Then optional wipe, a root partition, an optional dedicated /var (recommended for container/image storage), and optional LUKS encryption of root, with xfs (FCOS default) or ext4. LUKS supports three modes: a passphrase (embedded, least secure), TPM2 (clevis-bound, no secret stored), or Tang (clevis-bound to a Tang server). Prefer TPM2/Tang.
• Network — optional WiFi. Pick "Skip (I have Ethernet)" or "Configure WiFi"; if configured, a NetworkManager connection keyfile is written so the installed system associates on first boot.

Recommendations baked in: prefer SSH keys over passwords, keep /var separate, and put admin users in wheel.

How the build works

After the wizard, you choose what to do:

• Build ISO — internal/build writes the two Ignition configs (live + dest) and runs coreos-installer iso customize:
  • live (--live-ignition) — applied when booting the live ISO, so the installer environment is reachable (SSH) and online (WiFi) before you install. It deliberately omits partitioning/LUKS.
  • dest (--dest-ignition) — the full config (users, groups, partitioning, WiFi) applied to the installed system on first boot.
  • Provide a base ISO via --base-iso / UCOIN_BASE_ISO, or override the command with UCOIN_BUILD_CMD.
• Install to disk — runs coreos-installer install <disk> --live-ignition … --dest-ignition … --image-url <FROM> against the disk you picked in the Storage step. Override with UCOIN_INSTALL_CMD (the exact coreos-installer install flags depend on how your uCore image is published).

Persistence

Finishing the wizard writes, alongside the SSH key:

• ucoin-<host>.ign — the dest Ignition,
• ucoin-<host>-live.ign — the live Ignition,
• ucoin-<host>.config.json — the wizard answers (non-secret fields only).

Reload it later from the main menu ("Load saved config") or ucoin --config ucoin-<host>.config.json to re-run without redoing the whole wizard. Secrets (passwords, key passphrases, LUKS passphrase, Tang thumbprint) are intentionally not persisted, so you re-enter those.

The live WiFi relies on the base image shipping NetworkManager + wifi support (uCore/Fedora CoreOS live images do); the connection keyfile is what makes it associate on boot.

Build a builder ISO

A builder ISO is a bootable image that has ucoin pre-installed. Boot it on a machine, run ucoin interactively, and from there you can build ISOs from custom images or install them to disk — all without ucoin or Go being installed on the host beforehand.

Quick start

just builder /path/to/ucore-live.iso

This compiles ucoin (stripped, with -ldflags=-s -w), embeds the binary into a builder Ignition config, and runs coreos-installer iso customize to produce ucoin-builder.iso.

You need go and coreos-installer on the host that builds the ISO (not on the target machine). The base ISO should be a uCore or Fedora CoreOS live ISO.

Options

Flag	Description
--base-iso	Base ISO to customise (or set UCOIN_BASE_ISO).
--builder-binary	Use a pre-built ucoin binary instead of go build.
--builder-output	Output ISO path (default: ucoin-builder.iso).
--autostart	Install a systemd service that launches ucoin on boot.
--ssh-key	SSH public keys (comma separated) for the core user.
--hostname	Hostname for the builder environment.
--tags	Go build tags (comma separated) for binary compilation.
UCOIN_BUILDER_CMD	Override the coreos-installer command entirely.

Example: custom builder with autostart and SSH

go run . --builder \
  --base-iso /path/to/uCore-Live-Iso.iso \
  --autostart \
  --ssh-key "$(cat ~/.ssh/id_ed25519.pub)" \
  --hostname build01

Example: use a pre-built binary

go build -ldflags="-s -w" -o ucoin .
go run . --builder \
  --base-iso uCore-Live-Iso.iso \
  --builder-binary ./ucoin

What goes into the builder ISO

The builder Ignition is a live Ignition (applied at ISO boot, not at install time). It installs:

• /usr/local/bin/ucoin — the compiled binary, mode 0755.
• /etc/hostname — if --hostname is given.
• SSH authorized_keys for the core user — if --ssh-key is given.
• ucoin-installer.service — a systemd unit that auto-starts ucoin on tty1 on first boot (only with --autostart).

The resulting ISO is self-contained: you can boot it on any machine and ucoin will be available immediately.