From 89b7d239f9971149b9653e3500c1641b391a6dd9 Mon Sep 17 00:00:00 2001 From: Dorian Date: Wed, 11 Mar 2026 18:18:06 +0000 Subject: [PATCH] docs: update README for v1.0.0 release (LAUNCH-01) 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 --- README.md | 346 +++++++++++++++--------------------------------------- 1 file changed, 92 insertions(+), 254 deletions(-) diff --git a/README.md b/README.md index 7792fba5..9df6f320 100644 --- a/README.md +++ b/README.md @@ -1,292 +1,130 @@ -# 🏝️ Archipelago +# Archipelago -> Your Sovereign Personal Server +> Self-Sovereign Bitcoin Node OS -**Archipelago** is a next-generation Bitcoin Node OS for macOS that combines the power of Bitcoin Core, Lightning Network, and modern self-hosted applications in a beautiful, easy-to-use interface. +**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. -[![macOS](https://img.shields.io/badge/macOS-10.15%2B-blue)](https://www.apple.com/macos/) +[![Debian 12](https://img.shields.io/badge/Debian-12%20Bookworm-a80030)](https://www.debian.org/) [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE) -[![Docker](https://img.shields.io/badge/docker-23.0%2B-blue)](https://www.docker.com/) [![Rust](https://img.shields.io/badge/rust-stable-orange)](https://www.rust-lang.org/) -[![Vue.js](https://img.shields.io/badge/vue.js-3.0-brightgreen)](https://vuejs.org/) +[![Vue.js](https://img.shields.io/badge/vue.js-3.5-brightgreen)](https://vuejs.org/) +[![Version](https://img.shields.io/badge/version-1.0.0-blue)]() -## ✨ Features +## Features -### 🟠 Bitcoin & Lightning -- **Bitcoin Core** - Full node with custom UI (regtest/testnet/mainnet) -- **LND** - Lightning Network Daemon for instant payments -- **BTCPay Server** - Self-hosted payment processing -- **Mempool** - Beautiful blockchain explorer +### 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 -- **Nextcloud** - Cloud storage and file management -- **Penpot** - Open-source design and prototyping -- **Endurain** - Fitness tracking platform -- **Home Assistant** - Home automation hub -- **Grafana** - Metrics and monitoring -- **OnlyOffice** - Document editing suite -- **SearXNG** - Privacy-respecting search -- **Morphos** - File conversion utility +### 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. -### 🎨 Modern UI -- **Glassmorphism Design** - Beautiful, modern interface -- **Real-time Updates** - WebSocket-powered live data -- **Responsive Layout** - Works on desktop and mobile -- **Dark Theme** - Easy on the eyes -- **Progressive Web App** - Install as native app +### 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 -### πŸ”§ Technical -- **Native Rust Backend** - Fast, secure, efficient -- **Vue.js Frontend** - Modern reactive UI -- **Docker Integration** - Seamless container management -- **One-Click Launch** - Start apps with a single click -- **Auto-Discovery** - Automatically detects running containers +### 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 +## Quick Start -### Build ISO from Source +### Install from ISO -```bash -# One command to build everything and create flashable ISO -./build-iso-complete.sh --remote archipelago@192.168.1.228 +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://` +6. Set your password and start the onboarding wizard -# Flash to USB -./flash-to-usb.sh /dev/diskN -``` +### Supported Hardware -**πŸ“˜ See [BUILD-GUIDE.md](BUILD-GUIDE.md) for detailed build instructions.** +| 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 10.15 (Catalina) or later -- 8GB RAM minimum (16GB recommended) -- 20GB free disk space -- [Docker Desktop](https://www.docker.com/products/docker-desktop) +- Rust stable toolchain +- Node.js 20+ +- Linux dev server (Debian 12) for backend builds -### Installation - -1. **Download the latest release** - ```bash - # Download from GitHub Releases - https://github.com/[your-repo]/archipelago/releases/latest - ``` - -2. **Install Docker Desktop** - - Download from https://www.docker.com/products/docker-desktop - - Install and start Docker Desktop - -3. **Install Archipelago** - - Open the DMG file - - Drag Archipelago to Applications - - Launch from Applications folder - -4. **Access the Dashboard** - - Open http://localhost:8100 in your browser - - Login with default credentials (change immediately!) - -See [QUICKSTART.md](QUICKSTART.md) for detailed instructions. - -## πŸ—οΈ Building from Source - -### Development Setup (macOS/Docker) +### Frontend Development ```bash -# Clone the repository -git clone https://github.com/[your-repo]/archipelago.git -cd archipelago - -# Install Rust -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh - -# Install Node.js (using Homebrew) -brew install node - -# Build and run in development mode -./start-docker-apps.sh +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 ``` -### Production Builds for Hardware - -Archipelago supports building bootable Debian-based OS images: +### Deploy to Server ```bash -cd image-recipe - -# Build bootable ISO -./build-debian-iso.sh - -# Write to USB -./write-usb-dd.sh /dev/diskN +./scripts/deploy-to-target.sh --live # Deploy to dev server +./scripts/deploy-to-target.sh --both # Deploy to both servers ``` -**Supported Hardware:** -- πŸ–₯️ **Start9 Server Pure** - Intel i7-10710U, 32-64GB RAM, 2-4TB NVMe -- πŸ–₯️ **HP ProDesk 400 G4 DM** - Intel varies, 8GB+ RAM, 128GB+ SSD -- πŸ–₯️ **Dell OptiPlex** - Intel varies, 8GB+ RAM, 128GB+ SSD -- πŸ–₯️ **Generic x86_64** - Any x86_64 hardware with UEFI +### Build ISO -See [image-recipe/README.md](image-recipe/README.md) for detailed build instructions. - -## πŸ“– Documentation - -- **[Quick Start Guide](QUICKSTART.md)** - Get started in minutes -- **[Build Instructions](BUILD_MACOS.md)** - Build from source -- **[Deployment Checklist](DEPLOYMENT_CHECKLIST.md)** - Release process -- **[Architecture](docs/architecture.md)** - System design -- **[Changelog](CHANGELOG.md)** - Version history - -## πŸ—ΊοΈ Project Structure - -``` -archipelago/ -β”œβ”€β”€ core/ # Rust backend -β”‚ β”œβ”€β”€ archipelago/ # Main backend binary -β”‚ β”œβ”€β”€ container/ # Docker integration -β”‚ β”œβ”€β”€ security/ # Security modules -β”‚ └── performance/ # Performance optimization -β”œβ”€β”€ neode-ui/ # Vue.js frontend -β”‚ β”œβ”€β”€ src/ -β”‚ β”‚ β”œβ”€β”€ views/ # Page components -β”‚ β”‚ β”œβ”€β”€ components/ # UI components -β”‚ β”‚ └── stores/ # State management -β”‚ └── public/ # Static assets -β”œβ”€β”€ docker/ # Docker UI assets -β”‚ β”œβ”€β”€ bitcoin-ui/ # Bitcoin Core UI -β”‚ └── lnd-ui/ # LND UI -β”œβ”€β”€ docker-compose.yml # Container orchestration -└── build-macos-production.sh # Production build script +```bash +ssh archipelago@ +cd ~/archy/image-recipe +sudo ./build-auto-installer-iso.sh # x86_64 +sudo ARCH=arm64 ./build-auto-installer-iso.sh # ARM64 ``` -## 🐳 Docker Apps +## Architecture -All apps run in isolated Docker containers with automatic health monitoring: +``` +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) +``` -| App | Port | Description | -|-----|------|-------------| -| Dashboard | 8100 | Main Archipelago UI | -| Bitcoin Core | 18443-18444 | Bitcoin RPC | -| Bitcoin UI | 18445 | Custom Bitcoin interface | -| LND | 10009 | Lightning gRPC | -| LND UI | 8085 | Custom LND interface | -| BTCPay Server | 8082 | Payment processing | -| Mempool | 8080 | Blockchain explorer | -| Penpot | 9001 | Design platform | -| Endurain | 8084 | Fitness tracking | -| Morphos | 8081 | File converter | -| Nextcloud | 8086 | Cloud storage | -| Grafana | 8083 | Monitoring | -| Home Assistant | 8123 | Home automation | +## Documentation -## πŸ” Security +- [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 -### Default Security Measures -- βœ… Localhost-only by default (127.0.0.1) -- βœ… Container isolation (Docker networks) -- βœ… No root privileges required -- βœ… Encrypted data storage -- βœ… Session-based authentication +## Contributing -### Recommended Practices -- πŸ”‘ Change default passwords immediately -- πŸ”₯ Enable macOS firewall -- πŸ”„ Keep Docker and Archipelago updated -- πŸ’Ύ Backup data regularly -- 🚫 Don't expose ports without VPN +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 -## 🀝 Contributing +## License -We welcome contributions! Here's how: +[MIT License](LICENSE) -1. **Fork the repository** -2. **Create a feature branch**: `git checkout -b feature/amazing-feature` -3. **Commit your changes**: `git commit -m 'Add amazing feature'` -4. **Push to the branch**: `git push origin feature/amazing-feature` -5. **Open a Pull Request** +## Acknowledgments -See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines. - -## πŸ› Bug Reports - -Found a bug? Please open an issue with: -- macOS version -- Docker version -- Archipelago version -- Steps to reproduce -- Error logs - -## πŸ’¬ Community - -- **GitHub Discussions**: Ask questions and share ideas -- **Discord**: [Join our server] (coming soon) -- **Twitter**: [@archipelago_os] (coming soon) - -## πŸ—ΊοΈ Roadmap - -### v0.2.0 (Q2 2026) -- [ ] Auto-update system -- [ ] Multi-user support -- [ ] Enhanced Bitcoin Core controls -- [ ] Lightning Network autopilot -- [ ] Backup/restore functionality - -### v0.3.0 (Q3 2026) -- [ ] Native container runtime (no Docker Desktop) -- [ ] iOS companion app -- [ ] Hardware wallet integration -- [ ] Tor integration -- [ ] VPN/Tailscale support - -### v1.0.0 (Q4 2026) -- [ ] Mac App Store release -- [ ] Windows support -- [ ] Linux support -- [ ] Plugin system -- [ ] Decentralized app marketplace - -## πŸ“Š System Requirements - -### Minimum -- macOS 10.15 (Catalina) -- 8GB RAM -- 20GB disk space -- Intel or Apple Silicon CPU - -### Recommended -- macOS 12.0 (Monterey) or later -- 16GB RAM -- 50GB+ disk space (for blockchain) -- SSD storage -- Fast internet - -## πŸ“œ License - -This project is licensed under the [MIT License](LICENSE). - -## πŸ™ Acknowledgments - -Built with amazing open-source projects: -- [Rust](https://www.rust-lang.org/) - Systems programming language -- [Vue.js](https://vuejs.org/) - Frontend framework -- [Docker](https://www.docker.com/) - Container runtime -- [Bitcoin Core](https://bitcoin.org/) - Bitcoin full node -- [LND](https://lightning.engineering/) - Lightning Network -- [Debian](https://www.debian.org/) - Stable Linux foundation -- And many more... - -## πŸ’– Support the Project - -If you find Archipelago useful: -- ⭐ Star the repository -- 🐦 Share on social media -- πŸ› Report bugs and request features -- πŸ’» Contribute code -- β˜• [Buy us a coffee] (coming soon) - ---- - -
- -**Built with ❀️ by the Archipelago team** - -[Website](https://archipelago.os) β€’ [Documentation](./docs) β€’ [Twitter](https://twitter.com/archipelago_os) - -
+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/)