# ArchyHCL

A community hardware compatibility list for [Archipelago](https://source.archipelago-foundation.org/lfg2025/archy) —
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 →](https://hcl.archipelago-foundation.org)**

## 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](https://toh.openwrt.org/)** — 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](https://wiki.postmarketos.org/wiki/Devices)** —
  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](https://github.com/raspiblitz/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](CONTRIBUTING.md) — either open an issue with the
structured form, or add a YAML file directly and open a PR.

## Building the site locally

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

## Deployment

Live at **https://hcl.archipelago-foundation.org** — a static site (`site/`)
served by nginx, cert via `certbot certonly --webroot` (same pattern as
`regress.atobitcoin.io` and this project's other nginx-fronted sites).

Deployment is fully automatic: `.gitea/workflows/deploy.yml` runs on every
push to `main` on a repo-scoped self-hosted runner (`hcl-local-deploy`,
label `hcl-deploy`) living on the same box that serves the site — it runs
`scripts/build.py` and `rsync`s `site/` straight into the docroot, so
`data.json` can never drift from the source reports. No SSH keys or remote
credentials involved; the runner has local filesystem access since it's on
the same machine. `.gitea/workflows/ci.yml` runs the same build/validate
step on pull requests, on the (separate, shared) `vps2-runner`, so bad data
gets caught before merge rather than at deploy time.

Runner setup, for reference (repo-scoped registration token from
Settings → Actions → Runners → Create new Runner):

```bash
gitea-runner register --no-interactive \
  --instance <gitea-url> --token <token> \
  --name hcl-local-deploy --labels "hcl-deploy:host" \
  --config /etc/gitea-runner-hcl/config.yaml
```

running as a systemd service (`gitea-runner-hcl.service`) under a user that
owns the docroot directly — deliberately not root, and no sudo needed for
the deploy step itself.

## License

MIT — see [LICENSE](LICENSE).