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:

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

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.

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

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.):

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.