135 lines
5.9 KiB
Markdown
135 lines
5.9 KiB
Markdown
# 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 packages baked into the OS:** edit `build_files/build.sh`
|
||
(`dnf5 -y install <package>`), push — CI rebuilds the image.
|
||
- **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)
|
||
```
|