kamos/README.md

# KAMOS — Gaming Linux OS

KAMOS is a custom Linux gaming operating system for PCs and laptops, built on top of
[Bazzite](https://bazzite.gg)'s **stable** channel (Fedora Atomic). It is an
*image-based* OS: the whole system ships as one tested image, updates are atomic,
and you can roll back from the boot menu if an update ever misbehaves.

Everything Bazzite ships is included out of the box: Steam with Proton, Gamescope,
MangoHud, GameMode, HDR/VRR support, the fsync gaming kernel, KDE Plasma, Distrobox,
and Waydroid.

KAMOS is built and hosted entirely on **your own Forgejo instance** — Forgejo
Actions builds the images, and Forgejo's container/package registry serves them.
The build runner is deployed as a **Coolify service** (your existing Forgejo is
not modified in any way).

## Variants

| Image | For |
|---|---|
| `kamos` | AMD and Intel graphics (uses built-in Mesa drivers) |
| `kamos-nvidia` | NVIDIA graphics (proprietary driver pre-installed) |

Both work on desktops and laptops. For laptops with hybrid AMD+NVIDIA or
Intel+NVIDIA graphics, use `kamos-nvidia`.

## One-time setup

Server needs **~40 GB free disk** and 4+ GB RAM. Coolify's job here is only to
run the build runner container — the runner connects to Forgejo with a token;
your existing Forgejo service is untouched.

### 1. Get a runner registration token from Forgejo

Forgejo → **Site administration → Actions → Runners → Create new runner** →
copy the registration token. (This only *creates a token*; it changes nothing.)

### 2. Deploy the runner in Coolify

Coolify → your project → **New Resource** → search `git` → select **Gitea Runner**
(Forgejo's Actions runner is compatible with Gitea's — there is no separate
Forgejo Runner template). Before deploying, set the environment variables:

| Variable | Value |
|---|---|
| `GITEA_INSTANCE_URL` | `https://YOUR-FORGEJO-DOMAIN` |
| `GITEA_RUNNER_REGISTRATION_TOKEN` | the token from step 1 |
| `GITEA_RUNNER_NAME` | `kamos-builder` |
| `GITEA_RUNNER_LABELS` | `ubuntu-latest:docker://ghcr.io/catthehacker/ubuntu:act-22.04` |

(`GITEA_TOKEN` can stay empty — it's an alternative to the registration token.)

Then, still in the service before/after first deploy:

1. **Storages → Add File Mount**: destination `/config.yaml`, content = the file
   [`coolify/runner-config.yaml`](coolify/runner-config.yaml) from this repo.
   This lets build jobs use the host Docker daemon (required).
2. Add env var `CONFIG_FILE=/config.yaml`.
3. Deploy. In Forgejo → Site administration → Runners, `kamos-builder` should
   appear as **online** with the `ubuntu-latest` label.

### 3. Configure the repo

1. Create a repository named `kamos` on your Forgejo and push this folder to it
   (make sure Repository → Settings → **Actions** is enabled).
2. In both workflow files under `.forgejo/workflows/`, change
   `REGISTRY_HOST: git.example.com` to your Forgejo domain.
3. In Forgejo: your avatar → **Settings → Applications → Generate new token**
   with `package` read/write scope. Then in the repo:
   **Settings → Actions → Secrets**, add:
   - `REGISTRY_USER` — your Forgejo username
   - `REGISTRY_TOKEN` — the token you just generated
4. Push to `main` — the **Build KAMOS images** workflow builds both variants
   (30–60 min first run; the ~8 GB Bazzite base download is cached after that).
5. After the first build: profile → **Packages** → `kamos` and `kamos-nvidia` →
   package settings → visibility **Public** (so installed machines and the ISO
   builder can pull without credentials).

### 4. Build an installer ISO

Repo → **Actions → Build KAMOS installer ISO → Run workflow** → pick `kamos` or
`kamos-nvidia`. The finished ISO is uploaded to your Forgejo **package registry**
under `kamos-iso` — download it from your profile's Packages page.

The weekly scheduled rebuild keeps KAMOS current with upstream Bazzite stable and
Fedora security updates; installed machines pick these up automatically.

## Installing

**Fresh install:** write the ISO to a 16 GB+ USB stick with
[Fedora Media Writer](https://fedoraproject.org/workstation/download) or
[Rufus](https://rufus.ie) (DD mode), boot from it, and follow the installer.

**Already running Bazzite / Fedora Atomic?** Rebase without reinstalling:

```bash
rpm-ostree rebase ostree-unverified-registry:YOUR-FORGEJO-DOMAIN/YOUR-USERNAME/kamos:stable
```

(use `kamos-nvidia:stable` for NVIDIA), then reboot.

> **Secure Boot:** Bazzite's kernel is signed with Universal Blue's key. Either
> disable Secure Boot in the BIOS, or enroll the key as described in the
> [Bazzite docs](https://docs.bazzite.gg/General/Installation_Guide/secure_boot/).

## Customizing KAMOS

- **Add/remove system packages:** edit [`build_files/packages.list`](build_files/packages.list)
  — one package name per line, `#` for comments. Push, CI rebuilds.
- **Add/remove default apps (Flatpaks):** edit
  [`system_files/usr/share/kamos/flatpaks.list`](system_files/usr/share/kamos/flatpaks.list)
  with Flathub app IDs — installed automatically on each machine's first boot.
- **Wallpaper/logo:** replace
  `system_files/usr/share/backgrounds/kamos/kamos-default.png` and
  `system_files/usr/share/pixmaps/kamos-logo.png`. The build stamps the
  wallpaper over all stock desktop wallpapers.
- **Add config files:** drop them under `system_files/` mirroring the target
  path (e.g. `system_files/etc/foo.conf` → `/etc/foo.conf`).
- **Apps like Heroic, Lutris, Discord, OBS:** install as Flatpaks after boot
  (Discover app store) — that's the intended pattern on image-based systems.
- **Download page:** if you want a public KAMOS website with download links,
  deploy a small static site with Coolify pointing at the ISO URLs in your
  Forgejo package registry.

## Building locally (optional)

Requires Linux or WSL2 with `podman` or `docker`:

```bash
docker build --build-arg BASE_IMAGE=ghcr.io/ublue-os/bazzite --build-arg BASE_TAG=stable -t kamos:stable .
```

## Layout

```
Containerfile              OS image recipe (FROM bazzite:stable)
build_files/build.sh       packages + branding applied at build time
system_files/              files overlaid onto the OS (/etc, /usr, ...)
disk_config/iso.toml       installer ISO configuration (optional kickstart)
coolify/runner-config.yaml runner config for the Coolify Gitea Runner service
.forgejo/workflows/        CI: image build + ISO build (Forgejo Actions)
```