reframe as composefs-os; fix all pre-open-source issues

Project identity:
- README rewritten: composefs-os publishes bootable OCI images; cbootc is
  the embedded management tool, not the release artifact
- DESIGN.md: update status ("working implementation"), fix section 8 to
  describe the actual cbootc install to-disk command, fix file layout
  paths (/sysroot/composefs, /var/lib/cbootc), fix rollback description
  to match grub2-editenv implementation
- Cargo.toml: add description, license, repository fields

Must-fix bugs:
- container.yml: fix Containerfile.base path (was examples/fedora/…,
  now at repo root); rename image to composefs-os-fedora:43; drop CI
  push of the example derived image (it had a weak root password)
- units/cbootc-update.service: fix ConditionPathExists from
  /etc/cbootc/config.toml to /var/lib/cbootc/config.toml — the auto-
  update timer was silently doing nothing on every system since the
  config was moved to /var in an earlier commit

Cleanup:
- examples/fedora/Containerfile: remove weak root password, serial
  autologin, and leftover upgrade-test debug block; rewrite as a clean
  template pointing at the published base image

Author: henrywang

.github/workflows/container.yml

@@ -27,35 +27,12 @@ jobs:
 
       # Build the base image and push it.  The build is slow (dnf + dracut)
       # so GHA layer cache is critical for subsequent runs.
-      - name: Build and push fedora-cfs-base:43
+      - name: Build and push composefs-os-fedora:43
         uses: docker/build-push-action@v6
         with:
           context: .
-          file: examples/fedora/Containerfile.base
+          file: Containerfile.base
           push: true
-          tags: ghcr.io/${{ github.repository_owner }}/fedora-cfs-base:43
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
-
-      # Compute tags for the derived image: always "latest", plus semver on tags
-      - name: Docker metadata (derived image)
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ghcr.io/${{ github.repository_owner }}/fedora-cfs
-          tags: |
-            type=raw,value=latest
-            type=semver,pattern=v{{version}}
-
-      # Build the derived image, pointing BASE_IMAGE at the image we just pushed
-      - name: Build and push fedora-cfs
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          file: examples/fedora/Containerfile
-          push: true
-          tags: ${{ steps.meta.outputs.tags }}
-          build-args: |
-            BASE_IMAGE=ghcr.io/${{ github.repository_owner }}/fedora-cfs-base:43
+          tags: ghcr.io/${{ github.repository_owner }}/composefs-os-fedora:43
           cache-from: type=gha
           cache-to: type=gha,mode=max

Cargo.toml

@@ -2,6 +2,9 @@
 name = "cbootc"
 version = "0.1.0"
 edition = "2024"
+description = "Upgrade/rollback tool embedded in composefs-os images"
+license = "MIT"
+repository = "https://github.com/OWNER/composefs-os"
 
 [dependencies]
 anyhow = "1.0"

DESIGN.md

@@ -1,12 +1,13 @@
-# cbootc Design Notes
+# composefs-os / cbootc Design Notes
 
-A minimal bootc-like operational tool built directly on composefs-rs, with no
-ostree dependency. Intended as a personal-scale tool, not a bootc replacement.
+composefs-os ships bootable Linux OCI images backed by composefs-rs.
+cbootc is the embedded upgrade/rollback tool inside those images — a minimal
+bootc-like operational layer with no ostree dependency.
 
 ## Status
 
-Greenfield. No code yet. This document captures the design decisions made
-during initial scoping so we can pick up implementation cleanly.
+Working implementation. All core commands (install, upgrade, switch, rollback,
+status, verify) are functional on x86-64 EFI systems.
 
 ## Goals
 
@@ -104,21 +105,21 @@ Signature verification before deploy, using `sigstore-rs` or by shelling out
 to `cosign verify`. Enforced when a public key is configured; warning-only
 when none is. Configuration via `/etc/cbootc/config.toml`.
 
-### 7. Rollback via grub-reboot, not state machines
+### 7. Rollback via grubenv next_entry, not state machines
 
 Rather than tracking deployment generations in custom state, lean on the BLS
-entries cfsctl writes. Rollback = "boot the previous BLS entry once" via
-`grub2-reboot` or equivalent. Simple, debuggable, no custom state to corrupt.
+entries cfsctl writes. Rollback = write `next_entry=<digest>` to
+`/boot/grub2/grubenv` via `grub2-editenv`, then reboot. GRUB reads the env,
+boots that entry once, and clears it. Simple, debuggable, no custom state to
+corrupt.
 
-### 8. No installer in the binary
+### 8. Installer in the binary
 
-`cbootc install` is out of scope for the binary itself. Installation is done
-by the disk-builder script (see `tools/build-disk.sh`) which produces a
-qcow2/raw image. For bare-metal install, boot a live environment and run that
-script against `/dev/sdX` instead of a disk image file.
-
-This is the single biggest scope cut vs. bootc and is what makes cbootc
-buildable in weeks rather than months.
+`cbootc install to-disk <DEVICE>` runs inside the container image and writes a
+bootable system to a block device or raw file. It handles partitioning (GPT,
+via sfdisk), formatting, composefs repo initialisation, GRUB installation, and
+shared-var wiring. Running inside the container means the source image is always
+the container itself — no separate image reference needed at install time.
 
 ## Command Surface
 
@@ -135,10 +136,11 @@ That's it. Five commands. Compare to bootc's ~15.
 ## File Layout on Target System
 
 ```
-/composefs/                          cfsctl repo (objects, images, streams)
+/sysroot/composefs/                  cfsctl repo (objects, images, streams)
 /boot/                               kernel + initramfs + BLS entries
-/boot/loader/entries/*.conf          BLS snippets with composefs=<digest>
-/etc/cbootc/config.toml              tracked image, signing key, update policy
+/boot/loader/entries/<digest>.conf   BLS snippet with composefs=<digest>
+/boot/grub2/grubenv                  GRUB env block (next_entry for rollback)
+/var/lib/cbootc/config.toml          tracked image reference
 /var/lib/cbootc/state.json           last-upgrade time, last-known-good digest
 /usr/lib/systemd/system/cbootc-*     timer + service for auto-updates (optional)
 ```

README.md

@@ -1,39 +1,41 @@
-# cbootc
+# composefs-os
 
-A minimal bootc-like tool for systems running on composefs-rs. Personal-scale,
-distro-neutral, deliberately small.
+Bootable Linux system images built on [composefs-rs](https://github.com/containers/composefs-rs).
+Image-based OS management for personal and small-scale systems — no ostree, no fleet tooling.
 
 ## What This Is
 
-cbootc deploys and updates Linux systems built as OCI container images, using
-[composefs-rs](https://github.com/containers/composefs-rs) (via `cfsctl`) as
-the storage backend. It is a thin operational layer above cfsctl: install,
-status, upgrade, switch, rollback, signature verification, and a systemd timer
-for automatic updates.
+composefs-os publishes OCI container images that boot directly via a composefs
+overlay filesystem. Each image ships `cbootc`, a small embedded tool that
+handles upgrades, rollbacks, and image switching from within the running system.
 
 It is **not**:
 
-- A general-purpose bootc replacement (use [bootc](https://github.com/bootc-dev/bootc))
-- An ostree-compatible tool (no ostree code)
+- A general-purpose [bootc](https://github.com/bootc-dev/bootc) replacement
+- An ostree-compatible tool
 - A fleet management system
 
-See [DESIGN.md](DESIGN.md) for full design rationale.
+See [DESIGN.md](DESIGN.md) for rationale and architecture.
 
-## Quick Start
+## Available Images
 
-```sh
-# Build the base image (slow — dnf + dracut inside the container)
-podman build -t fedora-cfs-base:43 -f Containerfile.base .
+| Image | Status |
+|-------|--------|
+| `ghcr.io/OWNER/composefs-os-fedora:43` | Working |
+| Ubuntu | Planned |
+| Arch Linux | Planned |
 
-# Build a derived image (fast)
-podman build -t my-fedora-cfs:latest -f examples/fedora/Containerfile .
+Replace `OWNER` with the GitHub organisation or username hosting the packages.
+
+## Quick Start
 
+```sh
 # Install to a raw disk image (run from inside the container, needs --privileged)
 sudo podman run --rm --privileged \
     -v $(pwd):/output \
     -v /var/lib/containers:/var/lib/containers \
     -v /var/tmp:/var/tmp \
-    my-fedora-cfs:latest \
+    ghcr.io/OWNER/composefs-os-fedora:43 \
     cbootc install to-disk /output/disk.raw --size 10G
 
 # Boot it
@@ -43,35 +45,70 @@ qemu-system-x86_64 -enable-kvm -m 4096 \
     -nographic
 ```
 
-## Upgrading a Running System
+## Building a Custom Image
+
+The published base images are a starting point. Add your own packages and
+configuration in a derived `Containerfile`:
+
+```dockerfile
+FROM ghcr.io/OWNER/composefs-os-fedora:43
+
+# Add packages
+RUN dnf install -y vim htop && dnf clean all
+
+# Bake in configuration that must survive upgrades
+RUN echo 'myhost' > /etc/hostname
+```
+
+Use `examples/fedora/Containerfile` as a full template.
+
+## In-System Management
+
+Once booted, `cbootc` manages the system:
 
 ```sh
-# Point the system at a registry image
-cbootc switch docker://ghcr.io/you/my-fedora-cfs:latest
+# Show current deployment status
+cbootc status
 
-# Pull latest and stage new boot entry
+# Pull the latest image and stage a new boot entry
 cbootc upgrade
 
 # Reboot to apply
 systemctl reboot
+
+# Roll back to the previous deployment
+cbootc rollback
+systemctl reboot
+
+# Switch to a different image
+cbootc switch docker://ghcr.io/OWNER/composefs-os-fedora:43
 ```
 
-The image reference is persisted in `/var/lib/cbootc/config.toml` and survives
-upgrades. The `cbootc-update.timer` (enabled in the base image) runs
+The tracked image reference is stored in `/var/lib/cbootc/config.toml` and
+survives upgrades. `cbootc-update.timer` (enabled in the base image) runs
 `cbootc upgrade` daily with a randomised delay.
 
 ## Repository Layout
 
 ```
-cbootc/
+composefs-os/
   Containerfile.base         Builds the bootable Fedora 43 base image
-  src/                       Rust source
+  src/                       cbootc source (Rust)
   units/
     cbootc-update.service    Systemd service for automatic upgrades
     cbootc-update.timer      Systemd timer (daily, randomised delay)
   examples/
     fedora/
-      Containerfile          Example derived image (your customisations go here)
+      Containerfile          Template for derived Fedora images
+    arch/
+      Containerfile          Arch Linux (stub — not yet functional)
+    ubuntu/
+      Containerfile          Ubuntu (stub — not yet functional)
+  tests/
+    INTEGRATION.md           Manual integration test checklist
+  .github/workflows/
+    ci.yml                   Rust build, test, lint
+    container.yml            Build and push base image to ghcr.io
 ```
 
 ## Known Limitations
@@ -107,9 +144,9 @@ are not pruned automatically. Remove them manually when disk space is a concern.
 
 ### x86-64 only
 
-The GRUB install step (`grub2-install --target=x86_64-efi`) is hard-coded to
-x86-64 EFI. aarch64 and other architectures are not supported.
+The GRUB install step is hard-coded to `--target=x86_64-efi`.
+aarch64 and other architectures are not supported.
 
 ## License
 
-MIT — see [LICENSE](LICENSE) (if present) or SPDX identifier in source files.
+MIT — see [LICENSE](LICENSE).

examples/fedora/Containerfile

@@ -1,52 +1,37 @@
-# Example derived image built on fedora-cfs-base:43.
+# Template for a custom Fedora composefs-os image.
 #
 # Pattern:
-#   1. FROM fedora-cfs-base:43
+#   1. FROM ghcr.io/OWNER/composefs-os-fedora:43
 #   2. Install packages, write config — /etc and /var are normal here
-#   3. Add LABEL containers.bootc=1
+#   3. Keep the LABEL block at the bottom
 #
-# No cfs-layout-apply or FROM scratch step needed. cbootc install to-disk
-# handles the composefs layout transformation at install time.
+# Build locally:
+#   podman build -t my-fedora-cfs:latest \
+#       --build-arg BASE_IMAGE=ghcr.io/OWNER/composefs-os-fedora:43 \
+#       -f examples/fedora/Containerfile .
 #
-# Build:
-#   podman build -t fedora-cfs-base:43 -f examples/fedora/Containerfile.base .
-#   podman build -t my-fedora-cfs:latest -f examples/fedora/Containerfile .
-# Deploy (physical disk):
-#   sudo podman run --rm --privileged \
-#       -v /dev:/dev -v /var/lib/containers:/var/lib/containers \
-#       -v /var/tmp:/var/tmp \
-#       my-fedora-cfs:latest cbootc install to-disk /dev/vda --wipe
-# Deploy (disk image file):
+# Deploy to a disk image file:
 #   sudo podman run --rm --privileged \
 #       -v $(pwd):/output -v /var/lib/containers:/var/lib/containers \
 #       -v /var/tmp:/var/tmp \
 #       my-fedora-cfs:latest cbootc install to-disk /output/disk.raw --size 10G
 
-# BASE_IMAGE can be overridden in CI to reference ghcr.io/…/fedora-cfs-base:43
-ARG BASE_IMAGE=fedora-cfs-base:43
+ARG BASE_IMAGE=ghcr.io/OWNER/composefs-os-fedora:43
 FROM ${BASE_IMAGE}
 
 # --- Customise below this line -------------------------------------------
 
-# Root password — REMOVE FOR PRODUCTION, use SSH keys instead
-RUN echo 'root:fedora' | chpasswd
-
-# Serial console autologin — REMOVE FOR PRODUCTION
-RUN mkdir -p /usr/lib/systemd/system/serial-getty@ttyS0.service.d && \
-    printf '[Service]\nExecStart=\nExecStart=-/sbin/agetty --autologin root --noclear %%I 115200,38400,9600 vt220\n' \
-        > /usr/lib/systemd/system/serial-getty@ttyS0.service.d/autologin.conf
-
-RUN echo 'fedora-cfs' > /etc/hostname
+# Set hostname
+RUN echo 'myhost' > /etc/hostname
 
-# Add your own packages here:
-# RUN dnf install -y --setopt=install_weak_deps=False myapp && dnf clean all
+# Add your packages here, e.g.:
+# RUN dnf install -y --setopt=install_weak_deps=False vim htop && dnf clean all
 
 # --- Do not edit below this line ------------------------------------------
 
 LABEL containers.bootc=1
 LABEL composefs.backend=cfs-rs
-LABEL org.opencontainers.image.title="Fedora CFS (example)"
-LABEL org.opencontainers.image.description="Example composefs-rs bootable Fedora 43 image"
+LABEL org.opencontainers.image.title="My Fedora composefs-os image"
 LABEL org.opencontainers.image.version="43"
 
 CMD ["/sbin/init"]

units/cbootc-update.service

@@ -2,7 +2,7 @@
 Description=cbootc automatic image upgrade
 After=network-online.target
 Wants=network-online.target
-ConditionPathExists=/etc/cbootc/config.toml
+ConditionPathExists=/var/lib/cbootc/config.toml
 
 [Service]
 Type=oneshot