README.md
# Quarry
Quarry is a **cut** of [Bazzite](https://bazzite.gg/): a Universal Blue
bootc image defined from a Containerfile. Bazzite is a mineral; Quarry is
a cut of it. We keep the gaming stack and reverse a handful of ublue
desktop decisions.
This repository is **skeleton + policy** plus a live overlay. It does
**not** yet produce a signed, rebase-ready image: the Gitea registry
has no `:stable` tag until CI pushes one. Do not `bootc switch` to it.
## What it is
- An OCI image `FROM ghcr.io/ublue-os/bazzite:stable` (KDE / Kinoite
desktop, Steam and the rest of the Bazzite gaming stack intact).
- A written desktop policy an agent can extend when the next KDE app is
replaced.
- Gitea Actions that build and push to the Gitea container registry on
label `desktop-quarry` (`quarry-builder-01`). Validate is green;
a registry `:stable` push is still missing.
## What it is not
- A git fork of `ublue-os/bazzite`. Do not clone that repo to work here.
- A rebase of any running machine.
- Aurora, Kalpa, Bluefin, or a GNOME variant.
- Homebrew. CLI tools use Mise.
- Docker Engine on the base image. Podman is native.
- A mascot project.
## Required desktop reversals
| ublue/Bazzite default | Quarry |
| --- | --- |
| Bazaar | **Gone.** Plasma Discover restored; custom Flatpak remotes visible |
| Ptyxis (or other non-Konsole default) | **Konsole** default; **Ghostty** secondary |
| Homebrew for CLI | **Mise** |
| Docker as a first-class engine | **Podman** only; Docker CLI is opt-in |
| Fonts | **Adwaita Sans** UI/document; **Adwaita Mono** monospace |
Full policy: [`docs/desktop-policy.md`](docs/desktop-policy.md).
## Docs
- [`docs/design.md`](docs/design.md) — goals, non-goals, base image, build/publish, installer spike
- [`docs/ci-runners.md`](docs/ci-runners.md) — LAN host runner (`quarry-builder-01`, unit `act-runner-desktop-quarry.service`)
- [`docs/consume.md`](docs/consume.md) — pull from public OCI; `bootc switch` only on a throwaway VM
- [`docs/consume-gate.md`](docs/consume-gate.md) — throwaway VM 141 PASS record + KVM notes
- [`docs/iso-strategy.md`](docs/iso-strategy.md) — Option B minimal installer default; mirror; variants; optional cloud-init
- [`docs/iso-spike.md`](docs/iso-spike.md) — concrete installer spike plan + scripts
- [`docs/flavors.md`](docs/flavors.md) — server/desktop × base matrix
- [`docs/desktop-environment-variants.md`](docs/desktop-environment-variants.md) — server/desktop × Fedora/Debian matrix
- [`docs/desktop-policy.md`](docs/desktop-policy.md) — Bazaar/Discover/Konsole/Ghostty and the KDE-app replacement pattern
- [`docs/tooling.md`](docs/tooling.md) — Mise vs brew, Flatpak/AppImage/Distrobox, Podman vs Docker, ujust for Tailscale/Sunshine
- [`docs/brand.md`](docs/brand.md) — name, artwork direction, no mascot
- [`AGENTS.md`](AGENTS.md) — short rules for future agents
## Build (when the image actually builds)
Local, on a machine with Podman (not by rebasing the builder):
```bash
just build
# or
podman build -t git.thepeoples.dev/desktop/quarry:stable .
```
CI: [`.gitea/workflows/image-build.yml`](.gitea/workflows/image-build.yml)
builds with buildah/podman and pushes to
`git.thepeoples.dev/desktop/quarry` on label `desktop-quarry`. That
workflow is real Gitea Actions, not a GitHub-only pipeline. The LAN
host runner **is online** (`act-runner-desktop-quarry.service` on
`quarry-builder-01`). The last image-build (run 18, `e714b07`) failed
in `actions/checkout@v4` (`node` missing from PATH at the time).
Validate later succeeded. There is **no** Gitea container package
`:stable` yet. Signing is **not** configured. See
[`docs/ci-runners.md`](docs/ci-runners.md) and
[`docs/consume.md`](docs/consume.md).
Minimal-installer spike (Option B): [`docs/iso-spike.md`](docs/iso-spike.md) (strategy: [`docs/iso-strategy.md`](docs/iso-strategy.md)). `just iso-validate`.
## Layout
```
Containerfile # image-template-style entrypoint (source of truth)
build_files/ # scripts the Containerfile runs
artwork/ # brand source (icon, wallpaper, plymouth)
system_files/ # files copied to / (assets not applied as defaults)
recipes/recipe.yml # BlueBuild map of the same decisions; not CI
.gitea/workflows/ # Gitea Actions
docs/ # policy first
```