89b7d239f9
Replace outdated macOS/Docker Desktop references with current Debian 12 target platform, Podman containers, and accurate feature list. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
131 lines
4.4 KiB
Markdown
131 lines
4.4 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 Web5 identity through a modern web interface.
|
|
|
|
[](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
|
|
- **Electrs** 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 (20+)
|
|
Storage (File Browser, Immich, Nextcloud), Productivity (Penpot, OnlyOffice, Vaultwarden), Media (Jellyfin), Search (SearXNG), AI (Ollama), Network (Tailscale, Nginx Proxy Manager), Home (Home Assistant), and more.
|
|
|
|
### Web5 Identity
|
|
- DID-based digital identity (Ed25519 + secp256k1)
|
|
- Verifiable Credentials issuance and verification
|
|
- Decentralized Web Node (DWN) for data sync
|
|
- Nostr relay integration for node discovery
|
|
|
|
### Security
|
|
- AES-256-GCM encrypted secrets at rest
|
|
- Container isolation: read-only root, capability dropping, non-root user
|
|
- TOTP two-factor authentication
|
|
- Per-endpoint rate limiting and input validation
|
|
- AppArmor profiles for container confinement
|
|
|
|
## 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
|
|
- Rust stable toolchain
|
|
- Node.js 20+
|
|
- Linux dev server (Debian 12) for backend builds
|
|
|
|
### Frontend Development
|
|
|
|
```bash
|
|
cd neode-ui
|
|
npm install
|
|
npm start # Dev server on http://localhost:8100
|
|
npm run type-check # TypeScript validation
|
|
npm test # Run 515+ tests
|
|
npm run build # Production build
|
|
```
|
|
|
|
### Deploy to Server
|
|
|
|
```bash
|
|
./scripts/deploy-to-target.sh --live # Deploy to dev server
|
|
./scripts/deploy-to-target.sh --both # Deploy to both servers
|
|
```
|
|
|
|
### Build ISO
|
|
|
|
```bash
|
|
ssh archipelago@<server>
|
|
cd ~/archy/image-recipe
|
|
sudo ./build-auto-installer-iso.sh # x86_64
|
|
sudo ARCH=arm64 ./build-auto-installer-iso.sh # ARM64
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Debian 12 (Bookworm)
|
|
├── Podman (rootless containers)
|
|
├── Nginx (reverse proxy + security headers)
|
|
├── Rust Backend (JSON-RPC API on port 5678)
|
|
│ ├── core/archipelago/ — RPC endpoints, state, identity
|
|
│ ├── core/container/ — Podman client, manifests, health
|
|
│ └── core/security/ — AppArmor, secrets, image verification
|
|
└── Vue 3 Frontend (Composition API + TypeScript + Pinia)
|
|
```
|
|
|
|
## Documentation
|
|
|
|
- [Architecture](docs/architecture.md) — System design
|
|
- [Developer Guide](docs/developer-guide.md) — Contributing guide
|
|
- [App Developer Guide](docs/app-developer-guide.md) — Writing app manifests
|
|
- [App Manifest Spec](docs/app-manifest-spec.md) — YAML manifest format
|
|
- [User Guide](docs/user-guide.md) — End-user documentation
|
|
- [Release Notes](RELEASE-NOTES-v1.0.0.md) — v1.0.0 release notes
|
|
- [v1.1 Roadmap](docs/roadmap-v1.1.md) — Upcoming features
|
|
- [v2.0 Roadmap](docs/roadmap-v2.0.md) — Long-term vision
|
|
|
|
## 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 with tests
|
|
|
|
## 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/)
|