ArchyHCL/README.md

ArchyHCL

A community hardware compatibility list for Archipelago — what physical devices people have actually installed it on, what worked, what didn't, and why. Model, CPU, RAM, storage, and WiFi chip for every report, since WiFi chipsets are consistently the thing most likely to bite someone doing an install on repurposed hardware.

Browse the list → (once deployed — see Deployment below)

Why this exists

Archipelago runs on whatever hardware people have lying around — old laptops, mini PCs, SBCs — and that's a much wider, messier compatibility surface than a project that only targets its own reference hardware. Before building this, I looked at how a few existing communities solve the same problem:

• OpenWrt's Table of Hardware — a searchable table of routers, generated nightly from structured wiki pages into a toh.json file the site reads. Good model for the browsing UX (sortable/filterable table of CPU/RAM/flash/WiFi chip), but the underlying wiki pages are free-text and only loosely structured, which the maintainers themselves have called out as a maintenance problem over the years.
• postmarketOS's device list — tiers devices into main / community / testing support levels, each with a per-device page describing exactly what works and what doesn't. Good model for the status field: a single working/broken flag loses the "boots fine but WiFi is flaky" middle ground that's actually the most common and most useful case to document.
• RaspiBlitz (closest project to Archipelago in spirit — a Bitcoin/Lightning node OS for repurposed hardware) — hardware feedback mostly lives scattered across GitHub issues with no consistent fields, which makes it hard to search or compare reports. Useful as a negative example: this is what we're trying to avoid by using structured data files instead of free-form issue threads.

The model this repo uses: one small YAML file per report (data/reports/*.yml), validated against a JSON Schema, built into a single data.json a plain static site reads — OpenWrt's browsable-table UX, postmarketOS's tiered status field, and RaspiBlitz's actual subject matter (node-OS-on-repurposed-hardware), on top of git-native, PR-reviewable data instead of a wiki or a scattered issue tracker.

Repo layout

data/
  schema.json       — the report schema (source of truth for what fields exist)
  reports/*.yml      — one file per hardware report
scripts/
  build.py           — validates every report and builds site/data.json
site/
  index.html/.css/.js — the static site (no framework, no build step — just fetches data.json)
.gitea/issue_template/hardware-report.yml — structured issue form for reporting without git

Contributing a report

See CONTRIBUTING.md — either open an issue with the structured form, or add a YAML file directly and open a PR.

Building the site locally

pip install pyyaml jsonschema
python3 scripts/build.py     # writes site/data.json
python3 -m http.server 8000 --directory site

Deployment

Not yet deployed. This is a static site (site/) with no backend — any static host works (the same nginx-in-front-of-a-container pattern archy's other apps already use, GitHub/Gitea Pages, or a plain S3-style bucket). scripts/build.py should run in CI on every push to main so data.json never drifts from the source reports; wiring that up is the next step.

License

MIT — see LICENSE.