Skip to content

Document laptop quickstart path for Bluefin contributors #20

Description

@castrojo

[WHAT] Step-by-step docs and Justfile recipes for running the Bluespeed stack on a contributor's own Linux machine — not just the ghost homelab server.

[WHY] The README promises "YOU DON'T NEED A HOMELAB, you can run this on your laptop" but no laptop path exists. The primary contributor audience is Bluefin users (Fedora/ostree immutable OS), which has specific k3s install constraints.

[FIX]

  • Document k3s single-node install for standard mutable Linux
  • Document k3s install for immutable/ostree systems (Bluefin) — the k3s install script writes to /usr/local/bin which does not persist across ostree transactions; document the correct approach (rpm-ostree layer, toolbox, or alternative path)
  • Minimum hardware spec: RAM floor, CPU, disk requirements for running k3s + OTel + Loki + Prometheus + Perses
  • Add just setup-local recipe for localhost deployment (no SSH hop needed)
  • Same Justfile recipes must work identically on laptop as on ghost

[NEXT] Do NOT assume contributors are on Debian/Ubuntu — the primary audience is Bluefin (Fedora/ostree). Do NOT document a laptop path until the ghost path is confirmed working in issues #17 and #18.

Acceptance criteria:

  • A Bluefin contributor can follow the docs and get a working single-node cluster on their laptop
  • just setup-local works without SSH
  • Minimum hardware requirements documented
  • Immutable OS install path explicitly documented

Metadata

Metadata

Assignees

No one assigned

    Labels

    1-triageNew work awaiting human triage.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions