kamos/README.md

# KAMOS - Gaming OS

> Play. Perform. Dominate.

KAMOS is a personal Bazzite-based bootc image with custom logo, wallpaper, boot splash, and OS branding. Built on top of `ghcr.io/ublue-os/bazzite-nvidia:stable` so the proprietary NVIDIA driver and Bazzite's gaming/desktop tuning come for free.

## Architecture note (important if you're on a Mac)

KAMOS is `linux/amd64` only. Bazzite NVIDIA has no ARM64 build and NVIDIA's proprietary driver doesn't run on Apple Silicon anyway. The MacBook M2 is fine as a *build host* (CI does the heavy lifting) and as a *test host* via VMware Fusion's x86_64 emulation, but KAMOS is meant to run on a real NVIDIA PC.

## Layout

```
kamos/
├── Containerfile                                 # FROM bazzite-nvidia:stable + COPY + RUN build.sh
├── Justfile                                      # build / build-iso / build-qcow2 / lint
├── build_files/
│   └── build.sh                                  # all KAMOS customisation lives here
├── disk_config/
│   └── iso.toml                                  # bootc-image-builder ISO config
├── system_files/                                 # COPY'd into / inside the image
│   └── usr/share/
│       ├── backgrounds/kamos/                    # drop kamos-wallpaper.jpg here
│       ├── plymouth/themes/kamos/                # boot splash (kamos.plymouth + kamos.script + logo)
│       └── pixmaps/                              # drop kamos-logo.png here (GRUB logo)
├── .forgejo/workflows/build.yml                  # primary CI - builds & pushes to Forgejo
└── .github/workflows/build.yml                   # disabled GitHub equivalent (mirror if needed)
```

## Step 1 — Drop in your KAMOS branding assets

The repo has placeholder `DROP_*_HERE.txt` files in the right folders. Replace them with:

| Path                                                                  | What goes here                              | Recommended size      |
| --------------------------------------------------------------------- | ------------------------------------------- | --------------------- |
| `system_files/usr/share/backgrounds/kamos/kamos-wallpaper.jpg`        | Your "Play. Perform. Dominate." wallpaper   | 3840x2160 or 1920x1080 |
| `system_files/usr/share/plymouth/themes/kamos/kamos-logo.png`         | KAMOS logo (raven crest) for boot splash    | 256x256 or 512x512, transparent PNG |
| `system_files/usr/share/pixmaps/kamos-logo.png`                       | Same logo, used by GRUB boot menu           | 256x256 or 512x512, transparent PNG |

You can drop additional files anywhere under `system_files/`; they'll all be COPY'd into `/`. Delete the `DROP_*_HERE.txt` files once you've added the real assets.

## Step 2 — Configure your Forgejo registry

The repo is already wired for `cgi.medsys.cloud/mkm1971/kamos` and the runner label `ubuntu-latest`. You only need to add three secrets so CI can push and sign images.

Go to **https://cgi.medsys.cloud/mkm1971/kamos/settings/actions/secrets** and add:

| Secret name      | Value                                                          |
| ---------------- | -------------------------------------------------------------- |
| `SIGNING_SECRET` | The full contents of `cosign.key` (created in Step 3 below)    |
| `REGISTRY_USER`  | `mkm1971`                                                      |
| `REGISTRY_TOKEN` | A Forgejo access token with `package` write scope              |

To create `REGISTRY_TOKEN`: in Forgejo, click your avatar (top-right) → **Settings → Applications → Generate New Token**. Name it `kamos-ci`, tick the **package: write** scope, click Generate, and copy the token immediately (it's shown only once).

## Step 3 — Generate a cosign signing key

On your M2:

```bash
brew install cosign
cd /path/to/kamos
COSIGN_PASSWORD="" cosign generate-key-pair
```

Creates `cosign.key` (private — **never commit**) and `cosign.pub` (commit this). Paste the contents of `cosign.key` into the `SIGNING_SECRET` repository secret.

## Step 4 — Push to Forgejo and let CI build

```bash
git init
git add .
git commit -m "KAMOS initial scaffold"
git remote add origin https://cgi.medsys.cloud/mkm1971/kamos.git
git push -u origin main
```

Forgejo Actions needs an `linux-amd64` runner. Register one on any x86_64 Linux machine (the NVIDIA PC works perfectly).

## Step 5 — (Optional) Iterate locally on the M2

The base image is x86_64, so Podman has to emulate. Slow but works for quick checks.

```bash
brew install podman just
podman machine init --cpus 6 --memory 8192 --disk-size 60
podman machine start
just build
```

## Step 6 — Generate a bootable ISO for VMware Fusion

```bash
just build           # builds the OCI image
just build-iso       # wraps it with bootc-image-builder into output/bootiso/install.iso
```

VMware Fusion 13+ on Apple Silicon supports x86_64 emulation. New VM → install from ISO → choose `output/bootiso/install.iso` → guest type "Other Linux 5.x kernel 64-bit". Expect single-digit FPS in the GUI, but the boot splash and branding will render fine. This is the path you mentioned for your VMware testing setup.

## Step 7 — Install on the real NVIDIA PC

If the PC is already on a bootc image (Bazzite, Bluefin, Aurora, etc.):

```bash
sudo bootc switch cgi.medsys.cloud/mkm1971/kamos:stable
sudo systemctl reboot
```

If it's running something else, install Bazzite from its normal ISO first, then `bootc switch` to KAMOS. Or burn the ISO from step 6 to a USB stick and install fresh.

## Updating

CI rebuilds weekly so you pick up upstream Bazzite security fixes. Push any commit to `main` or run the workflow manually to bump immediately.

## What gets branded

`build.sh` applies KAMOS branding in seven places:

1. `/etc/os-release` → `NAME`, `PRETTY_NAME`, `VARIANT`, `HOME_URL` (so `neofetch`/`fastfetch` show "KAMOS Gaming OS - Play. Perform. Dominate.")
2. GNOME default wallpaper (system-wide via dconf override, applies to all new users)
3. GNOME lock-screen / screensaver background (same wallpaper)
4. Plymouth boot splash (custom `kamos` theme with pulsing logo on black)
5. Initramfs is regenerated with `dracut --force --regenerate-all` so the splash shows on first boot
6. GRUB boot-menu logo (logo PNG dropped into Bazzite's GRUB theme)
7. Container image labels (visible in registries / artifacthub)

## Troubleshooting

**`podman build` fails with "exec format error"**: forgot `--platform=linux/amd64` on Apple Silicon, or QEMU user-static isn't enabled in your Podman machine.

**Boot splash doesn't show**: confirm the kernel cmdline has `rhgb quiet splash` (it does, via iso.toml). On a `bootc switch` upgrade you may need to re-run `dracut --force --regenerate-all` and reboot once.

**Wallpaper doesn't apply for existing user**: the dconf override is `system-db:local`, which only affects new users. Existing accounts have their own user dconf — set it manually once with `gsettings set org.gnome.desktop.background picture-uri 'file:///usr/share/backgrounds/kamos/kamos-wallpaper.jpg'`.

**Image builds but boot loops on real hardware**: usually SecureBoot rejecting unsigned NVIDIA modules. Disable SecureBoot in BIOS or enroll Bazzite's MOK key (Bazzite docs cover this).

**Cosign signing step fails**: `SIGNING_SECRET` must be the *contents* of `cosign.key`, not a path. The key must be generated with an empty password.

## License

Apache-2.0 — same as the upstream `ublue-os/image-template`.