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 <noreply@anthropic.com>
This commit is contained in:
Dorian
parent
ef9834fa47
commit
89b7d239f9
346
README.md
346
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.
|
||||
|
||||
[](https://www.apple.com/macos/)
|
||||
[](https://www.debian.org/)
|
||||
[](LICENSE)
|
||||
[](https://www.docker.com/)
|
||||
[](https://www.rust-lang.org/)
|
||||
[](https://vuejs.org/)
|
||||
[](https://vuejs.org/)
|
||||
[]()
|
||||
|
||||
## ✨ 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://<device-ip>`
|
||||
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@<server>
|
||||
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)
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
**Built with ❤️ by the Archipelago team**
|
||||
|
||||
[Website](https://archipelago.os) • [Documentation](./docs) • [Twitter](https://twitter.com/archipelago_os)
|
||||
|
||||
</div>
|
||||
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/)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user