fa7372dd7a
- DOC-02: architecture.md — remove StartOS refs, add identity/federation section, update networking (archy-net, UFW, Tor), data persistence paths - DOC-03: current-state.md — full rewrite reflecting pure Archipelago stack, 2-node federation, 30+ apps, test coverage matrix Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
187 lines
7.5 KiB
Markdown
187 lines
7.5 KiB
Markdown
# Archipelago Bitcoin Node OS - Architecture Documentation
|
|
|
|
## Overview
|
|
|
|
Archipelago is a self-sovereign Bitcoin Node OS built on Debian Linux with Podman containerization. Flash to USB, install on hardware, manage via web UI. It runs 30+ containerized apps (Bitcoin, Lightning, BTCPay, Mempool, DWN, and more) with multi-node federation over Tor, W3C DID identity, and encrypted backups.
|
|
|
|
## System Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ Debian Linux Base (Bookworm) │
|
|
│ - Stable, well-supported kernel │
|
|
│ - Systemd service management │
|
|
│ - Extensive hardware support │
|
|
└─────────────────────────────────────────────────────────┘
|
|
│
|
|
┌───────────────┼───────────────┐
|
|
│ │ │
|
|
┌───────▼──────┐ ┌──────▼──────┐ ┌─────▼──────┐
|
|
│ Podman │ │ Rust Backend│ │ Vue.js UI │
|
|
│ (rootless) │ │ (core/) │ │ (neode-ui/) │
|
|
└───────┬──────┘ └──────┬──────┘ └─────────────┘
|
|
│ │
|
|
└───────┬───────┘
|
|
│
|
|
┌───────────▼───────────┐
|
|
│ Container Orchestration│
|
|
│ Layer │
|
|
│ - Manifest parser │
|
|
│ - Podman client │
|
|
│ - Dependency resolver │
|
|
│ - Health monitor │
|
|
└───────────┬───────────┘
|
|
│
|
|
┌───────────▼───────────┐
|
|
│ Containerized Apps │
|
|
│ - Bitcoin Core │
|
|
│ - LND / CLN │
|
|
│ - BTCPay Server │
|
|
│ - Nostr Relays │
|
|
│ - Meshtastic │
|
|
│ - Web5 DWN │
|
|
└───────────────────────┘
|
|
```
|
|
|
|
## Key Components
|
|
|
|
### 1. Debian Linux Base
|
|
|
|
- **Distribution**: Debian 12 (Bookworm) - stable, LTS support
|
|
- **Init System**: Systemd for service management
|
|
- **Security**: AppArmor, standard Debian hardening
|
|
- **Multi-arch**: ARM64 (Raspberry Pi) and x86_64 support
|
|
|
|
### 2. Container Orchestration Layer
|
|
|
|
Located in `core/container/`:
|
|
- **manifest.rs**: Parses YAML app manifests
|
|
- **podman_client.rs**: Wraps Podman API for container management
|
|
- **dependency_resolver.rs**: Resolves app dependencies and conflicts
|
|
- **health_monitor.rs**: Monitors container health and auto-restarts
|
|
|
|
### 3. Backend API Extensions
|
|
|
|
New RPC endpoints in `core/archipelago/src/container/`:
|
|
- `container-install`: Install app from manifest
|
|
- `container-start/stop/remove`: Container lifecycle
|
|
- `container-status/logs`: Status and debugging
|
|
- `container-list`: List all containers
|
|
- `container-health`: Health status aggregation
|
|
|
|
### 4. Vue.js UI Integration
|
|
|
|
New components in `neode-ui/`:
|
|
- **ContainerApps.vue**: List of containerized apps
|
|
- **ContainerAppDetails.vue**: Detailed app view with logs
|
|
- **ContainerStatus.vue**: Status indicator component
|
|
- **container-client.ts**: API client for container operations
|
|
- **container.ts**: Pinia store for container state
|
|
|
|
### 5. App Manifest System
|
|
|
|
Standardized YAML format in `apps/`:
|
|
- Defines container image, resources, dependencies
|
|
- Security policies and health checks
|
|
- Bitcoin/Lightning/Web5 integration metadata
|
|
|
|
### 6. Identity & Federation
|
|
|
|
Located in `core/archipelago/src/`:
|
|
- **identity.rs**: Ed25519 node identity, did:key generation, DID Documents
|
|
- **identity_manager.rs**: Multi-identity manager (Personal/Business/Anonymous)
|
|
- **credentials.rs**: W3C Verifiable Credentials (issue, verify, present, revoke)
|
|
- **federation.rs**: Multi-node federation with invite codes, trust levels, Tor sync
|
|
- **network/dwn_store.rs**: DWN message persistence (JSON files on disk)
|
|
- **network/dwn_sync.rs**: Bidirectional DWN replication over Tor
|
|
- **nostr_discovery.rs**: Nostr presence publishing (kind 30078, no onion addresses)
|
|
- **nostr_handshake.rs**: NIP-44 encrypted peer communication
|
|
|
|
### 7. Security Modules
|
|
|
|
Located in `core/security/`:
|
|
- **container_policies.rs**: Generates AppArmor profiles
|
|
- **secrets_manager.rs**: Encrypted secrets storage
|
|
- **image_verifier.rs**: Cosign signature verification
|
|
|
|
### 8. Performance Optimization
|
|
|
|
Located in `core/performance/`:
|
|
- **resource_manager.rs**: CPU/memory/disk allocation
|
|
- **optimize-debian.sh**: OS-level optimizations
|
|
|
|
## App Categories
|
|
|
|
### Bitcoin & Lightning
|
|
- Bitcoin Core (full node)
|
|
- LND (Lightning Network Daemon)
|
|
- Core Lightning (CLN)
|
|
- BTCPay Server
|
|
- Mempool (blockchain explorer)
|
|
|
|
### Web5 & Decentralized Protocols
|
|
- Nostr relays (nostr-rs-relay, strfry)
|
|
- Web5 DWN (Decentralized Web Node)
|
|
- DID Wallet
|
|
- Bitcoin Domain Names
|
|
|
|
### Mesh Networking & Routing
|
|
- Meshtastic (LoRa mesh networking)
|
|
- Router (mesh routing, device discovery)
|
|
- Local network management
|
|
|
|
### Self-Hosted Services
|
|
- Home Assistant
|
|
- Grafana
|
|
- SearXNG
|
|
- OnlyOffice
|
|
- Ollama (local AI)
|
|
- Penpot
|
|
|
|
## Security Model
|
|
|
|
1. **OS Level**: Debian hardening, AppArmor, minimal installed packages
|
|
2. **Container Level**: Rootless Podman, capability dropping, network isolation
|
|
3. **Secrets**: Encrypted storage, runtime injection only
|
|
4. **Supply Chain**: Signed images (Cosign), SBOM generation
|
|
5. **Network**: Firewall (nftables/iptables), rate limiting, Tor integration
|
|
6. **Audit**: Journald logging, configuration tracking
|
|
|
|
## Networking
|
|
|
|
- **Container Networks**: `archy-net` (main), `immich-net`, `penpot-net` via Podman
|
|
- **Aardvark DNS**: Container hostname resolution within networks
|
|
- **UFW Firewall**: Podman subnets (10.88.0.0/16, 10.89.0.0/16) allowed for DNS
|
|
- **Tor Integration**: System Tor daemon, SOCKS5 proxy on port 9050
|
|
- **Federation**: Inter-node communication over Tor hidden services
|
|
- **Nginx**: Reverse proxy on port 80/443, proxies to backend on 5678
|
|
|
|
## Data Persistence
|
|
|
|
- **App Data**: `/var/lib/archipelago/{app-id}/`
|
|
- **Identity**: `/var/lib/archipelago/identity/` (Ed25519 node key)
|
|
- **Multi-Identity**: `/var/lib/archipelago/identities/` (per-identity JSON)
|
|
- **DWN Messages**: `/var/lib/archipelago/dwn/messages/` (JSON files)
|
|
- **Credentials**: `/var/lib/archipelago/credentials/`
|
|
- **Federation**: `/var/lib/archipelago/federation/`
|
|
- **Content Catalog**: `/var/lib/archipelago/content/`
|
|
- **Backups**: `/var/lib/archipelago/backups/` (ChaCha20-Poly1305 encrypted)
|
|
- **Secrets**: `/var/lib/archipelago/secrets/{app-id}/` (encrypted)
|
|
|
|
## Multi-Node Federation
|
|
|
|
Nodes form a federated network over Tor:
|
|
- **Invite-based joining**: Generate invite code, peer joins via Tor
|
|
- **Trust levels**: Trusted, Verified, Untrusted
|
|
- **State sync**: Federation state, DWN messages, file catalogs sync bidirectionally
|
|
- **DWN protocols**: 4 interoperable schemas (node-identity, file-catalog, federation, app-deploy)
|
|
- **Verifiable Credentials**: W3C VCs for inter-node trust attestation
|
|
|
|
## Future Enhancements
|
|
|
|
- Time-travel snapshots (ZFS/BTRFS)
|
|
- Decentralized app marketplace (IPFS + Nostr)
|
|
- Multi-node clustering
|
|
- Hardware attestation (TPM 2.0)
|
|
- Protocol-agnostic design (multi-chain support)
|