Initial commit

2026-01-24 22:01:51 +00:00
commit 64cc3bc7fb
56 changed files with 4584 additions and 0 deletions
@@ -0,0 +1,165 @@
+# Archipelago Bitcoin Node OS - Architecture Documentation
+
+## Overview
+
+Archipelago is a next-generation Bitcoin Node OS built on Alpine Linux with Podman containerization, combining the modularity of Parmanode with the security and efficiency of a minimal server OS.
+
+## System Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│              Alpine Linux Base (130MB)                   │
+│  - Minimal kernel                                        │
+│  - Hardened security                                     │
+│  - Read-only root filesystem                             │
+└─────────────────────────────────────────────────────────┘
+                        │
+        ┌───────────────┼───────────────┐
+        │               │               │
+┌───────▼──────┐ ┌──────▼──────┐ ┌─────▼──────┐
+│   Podman     │ │ Rust Backend│ │ Vue.js UI   │
+│ (rootless)   │ │  (core/)    │ │ (neode-ui/) │
+└───────┬──────┘ └──────┬──────┘ └─────────────┘
+        │               │
+        └───────┬───────┘
+                │
+    ┌───────────▼───────────┐
+    │ Container Orchestration│
+    │   Layer (new)          │
+    │  - Manifest parser     │
+    │  - Podman client       │
+    │  - Dependency resolver  │
+    │  - Health monitor      │
+    └───────────┬───────────┘
+                │
+    ┌───────────▼───────────┐
+    │  Containerized Apps   │
+    │  - Bitcoin Core       │
+    │  - LND / CLN          │
+    │  - BTCPay Server      │
+    │  - Nostr Relays       │
+    │  - Meshtastic         │
+    │  - Web5 DWN           │
+    └───────────────────────┘
+```
+
+## Key Components
+
+### 1. Alpine Linux Base
+
+- **Size**: ~130MB (vs 1.5GB+ for Umbrel/StartOS)
+- **Security**: Hardened kernel, minimal attack surface
+- **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/startos/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. Parmanode Compatibility
+
+Located in `core/parmanode/`:
+- **script_runner.rs**: Executes Parmanode scripts in containers
+- **converter.rs**: Converts Parmanode modules to app manifests
+- **parmanode-wrapper.sh**: Shell wrapper for direct script execution
+
+### 7. Security Modules
+
+Located in `core/security/`:
+- **container_policies.rs**: Generates AppArmor/SELinux 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-alpine.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**: Hardened Alpine, read-only root, minimal kernel
+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, rate limiting, Tor integration
+6. **Audit**: Immutable logs, configuration tracking
+
+## Networking
+
+- **Isolated Networks**: Each app on separate bridge network by default
+- **Bitcoin Core**: Isolated network, explicit RPC access
+- **Lightning Nodes**: Separate network, gRPC/REST exposed
+- **Tor Integration**: Optional, default for privacy-sensitive apps
+- **Mesh Networking**: Meshtastic and router support for decentralized communication
+
+## Data Persistence
+
+- **App Data**: `/var/lib/archipelago/{app-id}/`
+- **Secrets**: `/var/lib/archipelago/secrets/{app-id}/` (encrypted)
+- **Logs**: `/var/lib/archipelago/logs/{app-id}/`
+- **Backups**: `/var/lib/archipelago/backups/`
+
+## 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)