archipelagoandClaude Opus 5
cbfda30579
Demo images / Build & push demo images (push) Failing after 2m22s
The app store offered "update to 2.3.9" on a node already running 2.4.2 — the release that fixes an actively exploited 2FA bypass. Taking it would have rolled the node back onto the vulnerable version. Root cause: available_update_for_images compared tags for inequality only. Same repo + different tag meant "update available", with no ordering. Every version claim upstream of it can go stale — the signed catalog, a legacy catalog entry, the image-versions.sh baseline pin — and any one of them lagging turned into a backwards Update button. Guard added: when both tags parse as dotted-numeric versions, a lower pinned version is never offered. Tags that cannot be ordered (RELEASE.2024-11-07…, 14-vectorchord0.4.3) keep the previous behaviour rather than silently losing updates. This makes stale data fail safe, which matters more than any single pin being correct. Four sources still named 2.3.9, three of them able to act on it: - releases/app-catalog.json — a LEGACY `btcpay` entry, distinct from `btcpay-server`, carrying a concrete 2.3.9 image. catalog_primary_image treats that as authoritative, so this is what drove the button. Fixed, but held back from this commit: it needs re-signing. - scripts/image-versions.sh — the baseline pin used when the catalog does not cover an app. - stacks.rs — the legacy BTCPay installer, twice. The fallback install path would have deployed 2.3.9 outright. - neode-ui curatedApps/marketplaceData and public/catalog.json — the store's displayed version, hardcoded rather than read from the catalog, which is why it still showed 2.3.9 after the update landed. Audited every other installer for the same shape. The remaining literals are the immich stack, which currently agrees with its manifests; hits in set_config.rs and app_catalog.rs are test fixtures. To keep it that way, scripts/check-installer-image-pins.py asserts that any installer literal naming the same repository as an app manifest carries the same tag, and runs blocking in CI. Verified it catches a simulated revert to 2.3.9. Tests: 13/13 in image_versions including the exact BTCPay case, a genuine upgrade still offered, equal versions silent, prerelease suffixes ordered on their numbers, and opaque tags unchanged. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Archipelago
Self-sovereign Bitcoin node OS and manifest-driven app platform.
Archipelago is a bootable personal server OS for Bitcoin infrastructure,
self-hosted apps, mesh communication, decentralized identity, and federation.
Apps are packaged as declarative manifest.yml files and run as rootless
Podman containers managed by the Rust backend.
What is here
core/- Rust workspace: backend API, container runtime, security, OpenWrt helpers, and performance/resource management.neode-ui/- Vue 3 + TypeScript frontend.apps/- app manifests and custom app container sources.docker/- supporting container build contexts for UI companion surfaces.image-recipe/- bootable image/ISO build inputs.Android/- Android companion app.scripts/- development, release, deployment, and validation tooling.docs/- architecture, app packaging, operations, API, and roadmap docs.
Platform model
Archipelago is built as a developer-ready app platform, not a fixed appliance:
- Apps are declared in
apps/<app-id>/manifest.yml. - The Rust parser in
core/container/src/manifest.rsis the canonical schema. - The orchestrator compiles manifests to rootless Podman/Quadlet runtime state.
- App data lives under
/var/lib/archipelago/<app-id>/. - Secrets are generated or read from
/var/lib/archipelago/secrets/and injected through Podman secrets rather than static environment values. - Release and app catalogs are signed and verified against a pinned trust anchor.
Start with:
- Architecture
- Developer Guide
- App Developer Guide
- App Manifest Spec
- Nostr Git Source Hosting Plan
- Troubleshooting
Quick start
Frontend
cd neode-ui
npm install
npm start
The dev UI runs at http://localhost:8100 with a mock backend on :5959.
Backend
cd core
cargo build
cargo test --all-features
Linux is the supported backend runtime and release-build target. macOS is fine for frontend work and many Rust compile/test loops, but host integration tests that touch Podman, systemd, networking, or image build paths require Linux.
App manifests
./scripts/validate-app-manifest.sh apps/filebrowser/manifest.yml
python3 scripts/generate-app-catalog.py
python3 scripts/check-app-catalog-drift.py --release --strict
scripts/generate-app-catalog.py requires Python with PyYAML installed.
Documentation map
| Doc | Purpose |
|---|---|
| Architecture | System layers, crates, data paths, security model |
| Developer Guide | Local setup, code workflow, testing |
| API Reference | JSON-RPC API overview |
| App Developer Guide | How to package and test apps |
| App Manifest Spec | Manifest schema and validation rules |
| Nostr Git Source Hosting Plan | ngit/NIP-34 contribution workflow and maintainer model |
| Apps README | Packaged app catalog overview |
| Image Recipe | Bootable image build flow |
| Roadmap | Shipped, in-progress, and planned work |
| Archive | Historical plans, audits, and handoffs |
Contributing
Read CONTRIBUTING.md before opening a pull request. For security issues, follow SECURITY.md and do not open a public issue.
License
Archipelago is licensed under the MIT License. Third-party notices are listed in NOTICE and generated license inventories in component release artifacts.