🏝️ Archipelago

Your Sovereign Personal Server

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.

✨ 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

🚀 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

🎨 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

🔧 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

🚀 Quick Start

Build ISO from Source

# One command to build everything and create flashable ISO
./build-iso-complete.sh --remote archipelago@192.168.1.228

# Flash to USB
./flash-to-usb.sh /dev/diskN

📘 See BUILD-GUIDE.md for detailed build instructions.

Prerequisites

• macOS 10.15 (Catalina) or later
• 8GB RAM minimum (16GB recommended)
• 20GB free disk space
• Docker Desktop

Installation

1. Download the latest release

   # 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 for detailed instructions.

🏗️ Building from Source

Development Setup (macOS/Docker)

# 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

Production Builds for Hardware

Archipelago supports building bootable Debian-based OS images:

cd image-recipe

# Build bootable ISO
./build-debian-iso.sh

# Write to USB
./write-usb-dd.sh /dev/diskN

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

See image-recipe/README.md for detailed build instructions.

📖 Documentation

• Quick Start Guide - Get started in minutes
• Build Instructions - Build from source
• Deployment Checklist - Release process
• Architecture - System design
• Changelog - 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

🐳 Docker Apps

All apps run in isolated Docker containers with automatic health monitoring:

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

🔐 Security

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

Recommended Practices

• 🔑 Change default passwords immediately
• 🔥 Enable macOS firewall
• 🔄 Keep Docker and Archipelago updated
• 💾 Backup data regularly
• 🚫 Don't expose ports without VPN

🤝 Contributing

We welcome contributions! Here's how:

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

See 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.

🙏 Acknowledgments

Built with amazing open-source projects:

• Rust - Systems programming language
• Vue.js - Frontend framework
• Docker - Container runtime
• Bitcoin Core - Bitcoin full node
• LND - Lightning Network
• Debian - 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 • Documentation • Twitter