83aacdf209
Releases no longer ship as bootable ISOs. Archipelago updates are distributed as the backend binary plus a frontend tarball referenced by releases/manifest.json. Nodes OTA-update via scripts/self-update.sh. Filebrowser and AIUI remain bundled inside the frontend tarball and deployed atomically, verified present in v1.7.43-alpha release artifact (189 AIUI files, filebrowser-client bundle). Archived under image-recipe/_archived/ (resurrectable if ISO distribution is reintroduced): - build-auto-installer-iso.sh - build-unbundled-iso.sh - test-iso-qemu.sh - scripts/convert-iso-to-disk.sh - BUILD-ISO-STATUS.md, ISO-BUILD-CHECKLIST.md - branding/isohdpfx.bin - .gitea/workflows/build-iso-dev.yml Updated release process docs to drop ISO references: - scripts/create-release.sh (next-steps text) - docs/BETA-RELEASE-CHECKLIST.md - docs/hotfix-process.md - README.md
164 lines
6.5 KiB
Markdown
164 lines
6.5 KiB
Markdown
# Archipelago
|
|
|
|
> Self-Sovereign Bitcoin Node OS
|
|
|
|
**Archipelago** is a bootable personal server OS. Flash it to a USB drive, install on any x86_64 or ARM64 machine, and manage Bitcoin infrastructure, self-hosted apps, and decentralized identity through a glassmorphism web UI.
|
|
|
|
[](https://www.debian.org/)
|
|
[](LICENSE)
|
|
[](https://www.rust-lang.org/)
|
|
[](https://vuejs.org/)
|
|
[]()
|
|
|
|
## Features
|
|
|
|
### Bitcoin Infrastructure
|
|
- **Bitcoin Knots** full node with pruning support
|
|
- **LND** Lightning Network daemon with channel management
|
|
- **ElectrumX** Electrum server for wallet connectivity
|
|
- **BTCPay Server** for accepting Bitcoin payments
|
|
- **Mempool** block explorer and fee estimator
|
|
- **Fedimint** federation guardian and gateway
|
|
|
|
### Self-Hosted Apps (30)
|
|
Bitcoin (ThunderHub), Storage (FileBrowser, Immich, Nextcloud), Productivity (Penpot, OnlyOffice, Vaultwarden), Media (Jellyfin, PhotoPrism), Search (SearXNG), AI (Ollama), Network (Tailscale, Nginx Proxy Manager), Home (Home Assistant), Nostr (nostr-rs-relay, Nostrudel), Dev (Grafana, Portainer), and more.
|
|
|
|
### Decentralized Identity
|
|
- Ed25519 node identity with DID Documents (did:key)
|
|
- Multi-identity management (Personal/Business/Anonymous)
|
|
- W3C Verifiable Credentials issuance and verification
|
|
- Decentralized Web Node (DWN) with bidirectional sync over Tor
|
|
- Nostr relay integration and NIP-07 signing for iframe apps
|
|
|
|
### Multi-Node Federation
|
|
- Invite-based node joining over Tor hidden services
|
|
- Trust levels (Trusted/Verified/Untrusted) with DID-based auth
|
|
- Bidirectional DWN state sync between federated nodes
|
|
- File sharing with access controls (free/peers-only/paid)
|
|
|
|
### Mesh Networking
|
|
- LoRa radio communication via Meshcore protocol
|
|
- Device discovery and mesh routing
|
|
- Off-grid Bitcoin balance checks (planned)
|
|
|
|
### System Updates
|
|
- OTA updates from self-hosted Gitea (git.tx1138.com) with SHA256 verification
|
|
- Three update modes: Manual, Daily Check, Auto Apply (3 AM window)
|
|
- Rollback support with automatic backup before applying
|
|
- Full UI for update management in Settings
|
|
|
|
### Security
|
|
- ChaCha20-Poly1305 encrypted secrets at rest, Argon2id password hashing
|
|
- Rootless Podman: read-only root, cap-drop ALL, non-root user, no-new-privileges
|
|
- TOTP two-factor authentication
|
|
- Per-endpoint rate limiting, CSRF protection, input validation
|
|
- AppArmor profiles for container confinement
|
|
- Tor hidden services for all inter-node communication
|
|
- All crypto and container dependencies pinned to exact versions
|
|
- Full penetration test completed (33 findings, all remediated)
|
|
|
|
## Quick Start
|
|
|
|
### Install from ISO
|
|
|
|
1. Download the ISO for your architecture (x86_64 or ARM64)
|
|
2. Flash to USB drive with Balena Etcher or `dd`
|
|
3. Boot from USB on target hardware
|
|
4. Follow the automated installer
|
|
5. Access the web UI at `http://<device-ip>`
|
|
6. Set your password and start the onboarding wizard
|
|
|
|
### Supported Hardware
|
|
|
|
| Platform | Examples | Minimum |
|
|
|----------|----------|---------|
|
|
| **x86_64** | Intel NUC, mini PCs, any 64-bit PC | 4GB RAM, 32GB storage |
|
|
| **ARM64** | Raspberry Pi 5, ARM64 SBCs | 4GB RAM, 32GB storage |
|
|
|
|
**Recommended**: 8GB+ RAM, 1TB+ NVMe SSD (for full Bitcoin node)
|
|
|
|
## Development
|
|
|
|
### Prerequisites
|
|
- macOS or Linux for frontend development
|
|
- Linux dev server (Debian 13) for backend builds — **never build Rust on macOS for Linux**
|
|
- Node.js 20+, Rust stable toolchain
|
|
|
|
### Frontend Development
|
|
|
|
```bash
|
|
cd neode-ui
|
|
npm install
|
|
npm start # Dev server on http://localhost:8100 (mock backend on :5959)
|
|
npm run type-check # TypeScript validation
|
|
npm run build # Production build → web/dist/neode-ui/
|
|
```
|
|
|
|
### Deploy to Server
|
|
|
|
```bash
|
|
./scripts/deploy-to-target.sh --live # Deploy to primary dev server
|
|
./scripts/deploy-to-target.sh --both # Deploy to both LAN servers
|
|
```
|
|
|
|
### Release (tarball-only)
|
|
|
|
Releases ship as a backend binary and a frontend tarball referenced by
|
|
`releases/manifest.json`. Nodes OTA-update via `scripts/self-update.sh`.
|
|
|
|
```bash
|
|
./scripts/create-release.sh 1.2.3
|
|
git push gitea-local main --tags
|
|
git push gitea-vps2 main --tags
|
|
```
|
|
|
|
ISO builds are archived under `image-recipe/_archived/` and not part of the
|
|
release deliverable.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Debian 13 (Trixie)
|
|
├── Rootless Podman (30 containers, archy-net DNS)
|
|
├── Nginx (reverse proxy, security headers, rate limiting)
|
|
├── Rust Backend (JSON-RPC API on 127.0.0.1:5678)
|
|
│ ├── core/archipelago/ — RPC endpoints, auth, identity, federation, mesh
|
|
│ ├── core/container/ — PodmanClient (REST API socket), manifests, health
|
|
│ ├── core/security/ — AppArmor, secrets, Cosign image verification
|
|
│ └── 6 more crates — models, helpers, js-engine, performance, etc.
|
|
├── Vue 3 Frontend (Composition API + TypeScript strict + Pinia + Tailwind)
|
|
└── System Tor (hidden services, SOCKS5 proxy)
|
|
```
|
|
|
|
~49,000 lines of Rust | ~47,000 lines of TypeScript/Vue | 78 shell scripts | 30 container apps
|
|
|
|
## Documentation
|
|
|
|
| Doc | Purpose |
|
|
|-----|---------|
|
|
| [Architecture](docs/architecture.md) | System design, codebase stats, data paths |
|
|
| [Architecture Review (HTML)](docs/architecture-review.html) | Interactive guide with diagrams and learning path |
|
|
| [Developer Guide](docs/developer-guide.md) | Dev setup, workflow, code conventions |
|
|
| [API Reference](docs/api-reference.md) | Complete RPC endpoint reference |
|
|
| [App Developer Guide](docs/app-developer-guide.md) | Building and publishing apps |
|
|
| [User Walkthrough](docs/user-walkthrough.md) | End-user installation and usage guide |
|
|
| [Troubleshooting](docs/troubleshooting.md) | Diagnostic scenarios and solutions |
|
|
| [Operations Runbook](docs/operations-runbook.md) | Ops commands and emergency recovery |
|
|
| [Security Audit](docs/security-code-audit-2026-03.md) | Penetration test findings |
|
|
| [Master Plan](docs/MASTER_PLAN.md) | Phased roadmap and task tracking |
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch (`feature/description`)
|
|
3. Follow the coding standards in [CLAUDE.md](CLAUDE.md)
|
|
4. Submit a pull request
|
|
|
|
## License
|
|
|
|
[MIT License](LICENSE)
|
|
|
|
## Acknowledgments
|
|
|
|
Built with: [Rust](https://www.rust-lang.org/), [Vue.js](https://vuejs.org/), [Podman](https://podman.io/), [Bitcoin Core](https://bitcoin.org/), [LND](https://lightning.engineering/), [Debian](https://www.debian.org/)
|