archy/README.md

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

[![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)
[![Rust](https://img.shields.io/badge/rust-stable-orange)](https://www.rust-lang.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

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