lfg2025/archy
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases 33 Wiki Activity

bug fixing and deploy and build diagnostics

Browse Source
This commit is contained in:
Dorian
2026-03-22 03:30:21 +00:00
parent 01942cea95
commit 13e4a738be
198 changed files with 21703 additions and 19587 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/BETA-RELEASE-CHECKLIST.md
View File

@@ -13,7 +13,7 @@
### Critical Files
- [ ] `core/container/src/podman_client.rs` — sudo podman
- [ ] `core/container/src/podman_client.rs` — rootless Podman REST API socket
- [ ] `core/archipelago/src/container/docker_packages.rs` — app metadata + UI mapping
- [ ] `core/archipelago/src/api/rpc/package.rs` — app configs, capabilities, dependencies
- [ ] `core/archipelago/src/session.rs` — session security hardening
@@ -235,10 +235,10 @@ sudo systemctl reload nginx
```bash
# Check container logs
sudo podman logs <container-name>
podman logs <container-name>
# Remove and recreate
sudo podman rm -f <container-name>
podman rm -f <container-name>
# Reinstall from App Store
```

99
docs/MASTER_PLAN.md
View File

@@ -18,6 +18,8 @@
| **TASK-12** | **Beta telemetry — reporter + toggle + collector POST** | **P1** | IN PROGRESS | - |
| **TASK-39** | **Finish .198 rootless container migration** | **P1** | PLANNED | TASK-11 |
| **TASK-42** | **LUKS2 full-partition encryption for /var/lib/archipelago/** | **P1** | PLANNED | TASK-10 |
| **BUG-44** | **App iframe shows blank/broken when container is starting or crashed** | **P2** | PLANNED | - |
| **TASK-45** | **Deploy script: auto-chown data dirs after rootful→rootless migration** | **P2** | PLANNED | - |
### Phase 2: User Testing (controlled, real hardware)
@@ -41,6 +43,7 @@
| **INQUIRY-5** | **Offline balance check via mesh relay** | **P2** | DEFERRED | - |
| **FEATURE-6** | **Watch-only wallet architecture** | **P1** | DEFERRED | - |
| **TASK-7** | **Mesh Bitcoin security hardening** | **P1** | DEFERRED | FEATURE-6 |
| **FEATURE-43** | **P2P encrypted voice/video calling (WebRTC over federation)** | **P1** | DEFERRED | - |
## Active Work
@@ -142,6 +145,37 @@ Encrypt all Archipelago app data at rest using LUKS2 full-partition encryption.
- `core/archipelago/src/api/rpc/system.rs` — password change handler
- `core/archipelago/src/server.rs` — startup checks
### BUG-44: App iframe shows blank/broken when container is starting or crashed (PLANNED)
**Priority**: P2 — Medium
**Status**: PLANNED (2026-03-21)
When an app container is still starting up or has crashed, the iframe overlay shows a blank/broken page with no feedback. Should show contextual loading states:
- **Starting**: skeleton loader or "App is starting up..." with spinner
- **Crashed**: "App has stopped" with restart button and link to logs
- **Port not ready**: "Waiting for app to become available..." with timeout warning
- **X-Frame-Options blocked**: Detect and open in new tab automatically
**Key files**:
- `neode-ui/src/views/AppSession.vue` — iframe container
- `neode-ui/src/stores/appLauncher.ts` — app launch state
- `neode-ui/src/api/container-client.ts` — container status checks
### TASK-45: Deploy script: auto-chown data dirs after rootful→rootless migration (PLANNED)
**Priority**: P2 — Medium
**Status**: PLANNED (2026-03-21)
When `deploy-tailscale.sh` migrates from rootful to rootless Podman, all files in `/var/lib/archipelago/` created by the old root-running backend are owned by `root:root`. The new backend runs as `archipelago` user and can't read them (node-key.pem, credentials, sessions, identity, etc.). Deploy script must auto-detect and fix ownership after migration.
Also fix:
- `/run/user/1000/crun` ownership (left as root from rootful container creation)
- Container recreation needs `--cap-add NET_BIND_SERVICE` for apps binding port 80 (nextcloud)
- Container recreation needs config volume mounts for apps writing to `/etc/` (searxng)
- Frontend should be copied from .228, not built locally (prevents build mismatches)
**Key files**:
- `scripts/deploy-tailscale.sh` — Step 14 (UID mapping) and Step 22 (container creation)
- `scripts/first-boot-containers.sh` — container creation reference
---
## Post-Beta (FROZEN)
@@ -152,6 +186,71 @@ Encrypt all Archipelago app data at rest using LUKS2 full-partition encryption.
- **FEATURE-6**: Watch-only wallet architecture
- **TASK-7**: Mesh Bitcoin security hardening
- **TASK-2**: Roll incoming-tx into deploy & ISO
- **FEATURE-43**: P2P encrypted voice/video calling (WebRTC over federation)
---
### FEATURE-43: P2P encrypted voice/video calling — WebRTC over federation (DEFERRED)
**Priority**: P1 — High
**Status**: DEFERRED (post-beta)
Self-sovereign encrypted voice and video calling between Archipelago peers. Zero new containers or dependencies — uses browser-native WebRTC with signaling over the existing federation WebSocket. Integrates directly into peer tabs/chat.
**Security & Privacy**:
- All media encrypted via DTLS/SRTP (WebRTC mandatory encryption — no opt-out)
- Signaling (SDP offers, ICE candidates) transmitted over existing federation WebSocket through Tor
- ICE candidate filtering: strip local/public IP candidates in Tor-relay mode
- No central server, no metadata leakage — true P2P between browsers
- Two privacy modes:
- **LAN Direct**: <50ms latency, IPs visible to peer (trusted same-network peers)
- **Tor Relay**: 300-800ms latency, full anonymity via coturn TURN server on .onion
**Architecture**:
- Signaling reuses existing federation WebSocket — new message types: `call-offer`, `call-answer`, `call-ice`, `call-hangup`, `call-reject`, `call-busy`
- Browser `getUserMedia()` + `RTCPeerConnection` — no backend media processing
- Opus codec for voice (~30kbps, handles Tor latency well)
- VP8/VP9 adaptive bitrate for video (720p on LAN, degrades gracefully)
- Optional `coturn` container (~10MB RAM) for Tor-relay media mode only
**UX**:
- Voice and video call buttons in peer chat (federation contacts)
- Incoming call: glass modal slides up with peer name + avatar, accept/decline
- In-call: floating glass PIP overlay — navigate while talking
- One-tap mute, camera toggle, speaker toggle, hangup
- Call quality indicator (green/yellow/red based on RTT)
- Ring timeout (30s) → missed call notification
- Call history in peer chat thread
**Tasks**:
- [ ] `CallService.ts` — WebRTC wrapper (offer/answer, ICE management, stream handling, codec negotiation)
- [ ] Federation signaling protocol — new message types over existing WS (`call-offer`, `call-answer`, `call-ice`, `call-hangup`)
- [ ] Rust backend — relay call signaling messages between federation peers (pass-through, no media processing)
- [ ] ICE candidate filtering — strip public IPs in privacy mode, force relay-only
- [ ] `CallOverlay.vue` — incoming call modal (glass aesthetic, ring animation, accept/decline)
- [ ] `CallPIP.vue` — floating picture-in-picture during active call (draggable, minimize/expand)
- [ ] `CallControls.vue` — mute, camera toggle, speaker, hangup, privacy mode switch
- [ ] Voice-only mode — Opus codec, bandwidth-optimized, Tor-friendly
- [ ] Video mode — VP8/VP9 adaptive bitrate, resolution scaling based on connection quality
- [ ] Optional `coturn` container manifest — TURN relay for Tor-routed media
- [ ] Call quality monitoring — RTT measurement, packet loss detection, quality indicator
- [ ] Call history — persist in peer chat thread, missed call notifications
- [ ] Multi-peer consideration — design for 1:1 first, extensible to group calls later
- [ ] Test: LAN direct call (voice + video)
- [ ] Test: Tor relay call (voice — verify latency is acceptable)
- [ ] Test: call during active chat, call while navigating other views
- [ ] Test: network interruption recovery (ICE restart)
**Key files** (new):
- `neode-ui/src/services/CallService.ts` — WebRTC engine
- `neode-ui/src/components/call/CallOverlay.vue` — incoming call UI
- `neode-ui/src/components/call/CallPIP.vue` — in-call floating overlay
- `neode-ui/src/components/call/CallControls.vue` — call action buttons
- `apps/coturn/manifest.yml` — optional TURN relay container
**Key files** (modified):
- `neode-ui/src/views/Federation.vue` — call buttons in peer chat
- `core/archipelago/src/api/rpc/federation.rs` — call signaling relay
- `neode-ui/src/stores/federation.ts` — call state management
## Completed

795
docs/architecture-review.html
View File

File diff suppressed because it is too large Load Diff

326
docs/architecture.md
View File

@@ -1,186 +1,190 @@
# Archipelago Bitcoin Node OS - Architecture Documentation
# Archipelago — Architecture
## Overview
> **Bitcoin Node OS** — Flash to USB, install on hardware, manage via web UI.
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.
**Stack**: Rust backend + Vue 3 + TypeScript (strict) + Vite 7 + Tailwind CSS + Pinia + rootless Podman
**Target OS**: Debian 12 (Bookworm) — x86_64 and ARM64
**Status**: Beta freeze (Phase 1: Feature Testing)
## System Architecture
For the full interactive architecture review with diagrams and learning guide, see [`architecture-review.html`](architecture-review.html).
---
## System Layers
```
┌─────────────────────────────────────────────────────────┐
│ 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 │
└───────────────────────┘
┌──────────────────────────────────────────────────────┐
│ YOUR BROWSER │
│ Vue 3 SPA (Composition API + Pinia) │
└──────────────────────┬───────────────────────────────┘
│ HTTP / WebSocket
┌──────────────────────┴───────────────────────────────┐
│ NGINX │
│ /rpc/v1 → backend /app/{id}/ → container │
└──────────────────────┬───────────────────────────────┘
│ port 5678
┌──────────────────────┴───────────────────────────────┐
│ RUST BACKEND (core/) │
│ Auth, RPC, containers, federation, mesh, health │
└──────────────────────┬───────────────────────────────┘
│ Podman REST API socket
┌──────────────────────┴───────────────────────────────┐
│ ROOTLESS PODMAN CONTAINERS │
│ 30 apps: Bitcoin, LND, Mempool, BTCPay, etc. │
└──────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────┐
│ DEBIAN 12 (Bookworm) │
│ systemd, UFW, Tor, AppArmor, filesystem │
└──────────────────────────────────────────────────────┘
```
## Key Components
## Codebase Stats
### 1. Debian Linux Base
| Component | Lines | Files |
|-----------|-------|-------|
| Rust backend (`core/`) | ~49,000 | 146 |
| TypeScript/Vue (`neode-ui/src/`) | ~47,000 | 155 |
| Shell scripts | — | 78 |
| Container apps | — | 30 |
- **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
## Backend Crates (`core/`)
### 2. Container Orchestration Layer
| Crate | Purpose |
|-------|---------|
| `archipelago` | Main binary — RPC endpoints, auth, identity, federation, mesh, health |
| `container` | PodmanClient (REST API), manifest parser, dependency resolver |
| `models` | Shared data types across the workspace |
| `helpers` | Common utilities |
| `js-engine` | Embedded JS runtime for extensibility |
| `security` | Secrets encryption, AppArmor profiles, Cosign verification |
| `performance` | CPU/memory/disk monitoring |
| `container-init` | Container initialization and first-run setup |
| `parmanode` | Parmanode compatibility 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
### Key Backend Files
### 3. Backend API Extensions
```
core/archipelago/src/
├── api/handler.rs — HTTP routing (/rpc, /health, /dwn, /ws)
├── api/rpc/mod.rs — RPC dispatcher (100+ endpoints)
├── api/rpc/package.rs — App install/start/stop/configure
├── session.rs — Auth sessions, rate limiting, persistence
├── health_monitor.rs — Container health + auto-restart
├── crash_recovery.rs — Boot-time container recovery
├── federation.rs — Multi-node federation over Tor
├── identity.rs — Ed25519 node identity, did:key
├── identity_manager.rs — Multi-identity (Personal/Business/Anonymous)
├── credentials.rs — W3C Verifiable Credentials
├── nostr_discovery.rs — Nostr presence (kind 30078)
├── nostr_handshake.rs — NIP-44 encrypted peer comms
├── network/dwn_store.rs — DWN message persistence
├── network/dwn_sync.rs — Bidirectional DWN replication over Tor
├── monitoring/ — System metrics
├── update.rs — Update checking + scheduling
└── wallet/ — LND integration, ecash
```
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
## Frontend (`neode-ui/src/`)
### 4. Vue.js UI Integration
```
├── api/ — RPC client, WebSocket, container client
├── views/ — Dashboard, Marketplace, Settings, Web5, Mesh, Login
├── components/ — BootScreen, SplashScreen, SpotlightSearch, etc.
├── stores/ — Pinia: app, container, mesh, appLauncher, etc.
├── composables/ — useToast, useAudioPlayer, etc.
├── types/ — TypeScript type definitions
├── router/ — Vue Router
└── style.css — Global glassmorphism theme
```
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
## Container Apps (30)
### 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
**Bitcoin & Lightning**: Bitcoin Knots, LND, BTCPay Server, ThunderHub, Mempool, ElectrumX, Fedimint
**Nostr**: nostr-rs-relay, Nostrudel
**Self-Hosted**: Nextcloud, Jellyfin, Immich, PhotoPrism, Vaultwarden, Home Assistant, OnlyOffice, Penpot, SearXNG, FileBrowser
**Dev/Ops**: Grafana, Portainer, Ollama, Nginx Proxy Manager
**Networking**: Tailscale
**Custom**: DWN, IndeedHub, Router
**External**: BotFights, NWNN, 484 Kitchen, Call the Operator, Arch Presentation, Syntropy Institute, T-Zero
## 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
- **Container DNS**: `archy-net` for inter-container communication (Bitcoin, LND, ElectrumX, Mempool, BTCPay, Fedimint)
- **Aardvark DNS**: Container hostname resolution within Podman networks
- **Tor**: System Tor daemon, SOCKS5 on port 9050, hidden services per node
- **Federation**: Inter-node communication over Tor with DID-based trust
- **UFW**: `DEFAULT_FORWARD_POLICY="ACCEPT"` required for LAN container access
## Data Persistence
## Security Model
- **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)
| Layer | Measures |
|-------|----------|
| OS | Debian hardening, AppArmor, minimal packages |
| Nginx | CSP headers, rate limiting, auth_request, session validation |
| Backend | Input validation, CSRF, session auth, bind 127.0.0.1 only |
| Containers | Rootless Podman, cap-drop ALL, readonly root, non-root user, no-new-privileges, memory limits |
| Crypto | Ed25519 signatures, ChaCha20-Poly1305 encryption, Argon2 password hashing, constant-time comparisons |
| Network | Tor hidden services, UFW firewall, SSRF prevention |
## Multi-Node Federation
## Data Paths
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
| Data | Path |
|------|------|
| App data | `/var/lib/archipelago/{app-id}/` |
| Identity | `/var/lib/archipelago/identity/` |
| Multi-identity | `/var/lib/archipelago/identities/` |
| Federation | `/var/lib/archipelago/federation/` |
| DWN messages | `/var/lib/archipelago/dwn/messages/` |
| Credentials | `/var/lib/archipelago/credentials/` |
| Backups | `/var/lib/archipelago/backups/` (ChaCha20-Poly1305) |
| Secrets | `/var/lib/archipelago/secrets/{app-id}/` (encrypted) |
| Sessions | `/var/lib/archipelago/sessions.json` |
| Frontend | `/opt/archipelago/web-ui/` |
| Backend binary | `/usr/local/bin/archipelago` |
## Future Enhancements
## Active Nodes (5)
- Time-travel snapshots (ZFS/BTRFS)
- Decentralized app marketplace (IPFS + Nostr)
- Multi-node clustering
- Hardware attestation (TPM 2.0)
- Protocol-agnostic design (multi-chain support)
| Node | Access | Notes |
|------|--------|-------|
| Arch 1 | 192.168.1.228 (LAN) | Primary dev, 16GB RAM, 1.8TB NVMe |
| Arch 2 | 192.168.1.198 (LAN) | Secondary, 8GB RAM |
| Arch 3 | 100.82.97.63 (Tailscale) | Has mesh radio |
| Arch 4 | 100.122.84.60 (Tailscale) | — |
| Arch 5 | 100.124.105.113 (Tailscale) | — |
All nodes federated over Tor with bidirectional DWN sync. Deploy via SSH key from Mac.
## Key Features (Working)
- 30 containerized apps with one-click install/manage
- Multi-node federation with invite-based joining and trust levels
- DWN sync (bidirectional message replication over Tor)
- W3C DID identity (did:key, DID Documents, Verifiable Credentials)
- NIP-07 Nostr signing (iframe apps sign events with consent)
- File sharing with access controls (free/peers-only/paid)
- Encrypted backups (Argon2 + ChaCha20-Poly1305)
- Health monitoring with tiered auto-restart (exponential backoff)
- Tiered container startup (databases → core → applications)
- LoRa mesh networking (Meshcore protocol)
- Three-mode UI (Pro/Easy/Chat)
- Real-time WebSocket updates
- Glassmorphism web UI
- Bootable ISO installer
## Further Documentation
| Doc | Purpose |
|-----|---------|
| [`architecture-review.html`](architecture-review.html) | Full interactive architecture guide with diagrams |
| [`developer-guide.md`](developer-guide.md) | Dev setup, workflow, code conventions |
| [`api-reference.md`](api-reference.md) | Complete RPC endpoint reference |
| [`app-developer-guide.md`](app-developer-guide.md) | Building and publishing apps |
| [`user-walkthrough.md`](user-walkthrough.md) | End-user installation and usage guide |
| [`troubleshooting.md`](troubleshooting.md) | Diagnostic scenarios and solutions |
| [`operations-runbook.md`](operations-runbook.md) | Ops commands and emergency recovery |
| [`multi-node-architecture.md`](multi-node-architecture.md) | Federation protocol design |
| [`marketplace-protocol.md`](marketplace-protocol.md) | Decentralized app discovery via Nostr |
| [`security-code-audit-2026-03.md`](security-code-audit-2026-03.md) | Penetration test findings (33 findings, all remediated) |
| [`MASTER_PLAN.md`](MASTER_PLAN.md) | Phased roadmap and task tracking |
| [`BETA-PROGRESS.md`](BETA-PROGRESS.md) | Current beta stabilization progress |

86
docs/current-state.md
View File

@@ -1,83 +1,5 @@
# Current Development State
# Current State
**Last updated**: 2026-03-14 (v1.2.0)
## Architecture
Archipelago is a pure, standalone Bitcoin Node OS. All StartOS dependencies were removed in v1.0. The stack:
- **OS**: Debian 12 (Bookworm) — x86_64 and ARM64
- **Backend**: Rust binary (`archipelago`) on port 5678
- **Frontend**: Vue 3 + TypeScript + Vite 7 + Tailwind CSS
- **Containers**: Podman (root-level via `sudo podman`)
- **Web Server**: Nginx reverse proxy (port 80/443 → backend 5678)
- **Tor**: System Tor daemon with hidden services
- **Systemd**: `archipelago.service` with watchdog (60s)
## Active Nodes
| Node | IP | Hardware | RAM | Disk | Containers |
|------|-----|----------|-----|------|------------|
| Arch 1 | 192.168.1.228 | Intel i3-8100T | 16GB | 1.8TB NVMe | 32 |
| Arch 2 | 192.168.1.198 | — | 8GB | 457GB | 34 |
Both nodes are federated over Tor with bidirectional DWN sync.
## Backend Modules
```
core/archipelago/src/
├── api/ — HTTP server, RPC handler (100+ endpoints)
│ ├── handler.rs — HTTP routing (/rpc, /health, /dwn, /ws)
│ └── rpc/ — RPC endpoints (auth, identity, federation, etc.)
├── backup/ — Full backup + identity backup (ChaCha20-Poly1305)
├── container/ — Container management (Podman, health checks)
├── identity.rs — Ed25519 node identity, did:key, DID Documents
├── identity_manager.rs — Multi-identity (Personal/Business/Anonymous)
├── credentials.rs — W3C Verifiable Credentials
├── federation.rs — Multi-node federation over Tor
├── network/ — DWN store, DWN sync, DNS, routing
├── nostr_discovery.rs — Nostr presence (kind 30078)
├── nostr_handshake.rs — NIP-44 encrypted peer communication
├── health_monitor.rs — Container health monitoring + auto-restart
├── crash_recovery.rs — Start stopped containers on boot
├── monitoring/ — System metrics collection
├── session.rs — Session management + rate limiting
├── update.rs — Update checking + scheduling
└── wallet/ — LND integration, ecash, profits tracking
```
## Key Features (Working)
- **30+ containerized apps**: Bitcoin Knots, LND, Mempool, BTCPay, Nextcloud, Immich, Jellyfin, Home Assistant, etc.
- **Multi-node federation**: Invite-based joining, trust levels, state sync over Tor
- **DWN sync**: Bidirectional message replication between federated nodes
- **W3C identity**: did:key, DID Documents, Verifiable Credentials
- **NIP-07 signing**: iframe apps can sign Nostr events with consent
- **File sharing**: Content catalog with access controls (free/peers-only/paid)
- **Encrypted backups**: Create, verify, restore with Argon2 + ChaCha20-Poly1305
- **Health monitoring**: Auto-restart crashed containers with exponential backoff
- **Tiered startup**: Databases → Core → Applications ordering on boot
- **Web UI**: Glass morphism design, real-time WebSocket updates
## Planned (Not Yet Implemented)
- **did:dht**: DHT-based discoverable identities (architecture documented)
- **DWN protocol schemas**: 4 Archipelago protocols defined, registration implemented
- **Multi-user support**: Admin/viewer/app-user roles
- **Cluster mode**: Multi-node HA with consensus
- **Mobile companion**: Read-only PWA for remote monitoring
## Test Coverage
Cross-node test suite (`scripts/test-cross-node.sh`) covers:
- US-01: System health (6 checks × 2 nodes)
- US-02: Container lifecycle (3 checks × 2 nodes)
- US-03: Federation join (4 checks × 2 nodes)
- US-04: Federation sync (4 checks × 2 nodes)
- US-05: Tor hidden services (2 checks bidirectional)
- US-07: File sharing (5 checks bidirectional)
- US-08: DWN sync (5 checks × 10 iterations)
- US-09: NIP-07 signing (1 check × 2 nodes)
- US-10: Backup/restore (4 checks × 10 iterations × 2 nodes)
- US-15: Boot recovery (3 checks × 3 reboots per node)
> This document has been consolidated into [`architecture.md`](architecture.md).
>
> See that file for the current system architecture, active nodes, codebase stats, and feature status.

30
docs/operations-runbook.md
View File

@@ -32,32 +32,32 @@ sudo systemctl status tor # Tor hidden services
```bash
# List all containers
sudo podman ps -a
podman ps -a
# Running count
sudo podman ps --format '{{.Names}}' | wc -l
podman ps --format '{{.Names}}' | wc -l
# Find exited/crashed containers
sudo podman ps -a --filter status=exited
podman ps -a --filter status=exited
# Container logs
sudo podman logs {container-name} --tail 50
podman logs {container-name} --tail 50
# Container resource usage
sudo podman stats --no-stream
podman stats --no-stream
```
## 3. Fix Crashed Containers
```bash
# Restart a specific container
sudo podman restart {container-name}
podman restart {container-name}
# If container won't start, check logs first
sudo podman logs {container-name} --tail 100
podman logs {container-name} --tail 100
# Remove and recreate (last resort)
sudo podman rm -f {container-name}
podman rm -f {container-name}
# Then redeploy with: ./scripts/deploy-to-target.sh --live
# The health monitor auto-restarts containers every 60s
@@ -173,11 +173,11 @@ uptime
top -b -n 1 | head -15
# Check container CPU usage
sudo podman stats --no-stream --format '{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}'
podman stats --no-stream --format '{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}'
# Common causes:
# - Bitcoin IBD (initial block download): normal, takes days
# - Container crash loops: check `sudo podman ps -a --filter status=exited`
# - Container crash loops: check `podman ps -a --filter status=exited`
# - mempool-electrs indexing: normal after Bitcoin sync
```
@@ -191,7 +191,7 @@ free -h
swapon --show
# Per-container memory
sudo podman stats --no-stream --format '{{.Name}}\t{{.MemUsage}}\t{{.MemPerc}}'
podman stats --no-stream --format '{{.Name}}\t{{.MemUsage}}\t{{.MemPerc}}'
# Check for OOM kills
dmesg --level=err,crit | grep -i oom
@@ -214,10 +214,10 @@ df -h /
sudo du -h --max-depth=2 /var/lib/archipelago/ | sort -rh | head -20
# Container image sizes
sudo podman images --format '{{.Repository}}:{{.Tag}}\t{{.Size}}'
podman images --format '{{.Repository}}:{{.Tag}}\t{{.Size}}'
# Clean unused images
sudo podman image prune -a
podman image prune -a
# Clean old journal logs
sudo journalctl --vacuum-size=500M
@@ -295,7 +295,7 @@ sudo tail -f /var/log/nginx/access.log
sudo tail -f /var/log/nginx/error.log
# Container logs
sudo podman logs {container-name} --tail 50 -f
podman logs {container-name} --tail 50 -f
```
## 15. Network Diagnostics
@@ -347,7 +347,7 @@ If a node responds to ping but SSH/HTTP are down:
```bash
df -h /
sudo journalctl --vacuum-size=200M
sudo podman image prune -a
podman image prune -a
```
## 17. Run Cross-Node Tests