archy/README.md

# 🏝️ 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.

[![macOS](https://img.shields.io/badge/macOS-10.15%2B-blue)](https://www.apple.com/macos/)
[![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/)

## ✨ 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

### 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)

### 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)

```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
```

### Production Builds for Hardware

Archipelago supports building bootable Debian-based OS images:

```bash
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](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
```

## 🐳 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](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>