lfg2025/archy
1
0
Fork 0
Code Issues 9 Pull Requests Actions Packages Projects Releases 44 Wiki Activity
archy/loop/plan.md
Dorian 4fef4843b5 feat: issue FederationTrustCredential on federation join 
- Issue W3C VC (type FederationTrustCredential) when joining federation
- Claims: federationPeer=true, establishedAt=timestamp
- Signed with node Ed25519 identity key
- Runs in background task (non-blocking)
- Stored via credentials system for later verification

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-14 03:54:27 +00:00

45 KiB
Raw Blame History

Archipelago 5-Year Production Hardening Plan

Version: 2.0 Period: March 2026 -- March 2031 Goal: Production-ready Bitcoin Node OS at 10,000 users with zero failures, 100% uptime, full inter-node federation Visual constraint: NEVER change animations, user experience, or flow -- only clean up duplications, information hierarchy, and cosmetic issues Web5 additions: did:dht, DWN protocol definitions for interoperable schemas, Verifiable Credentials (per TBD assessment)

Primary test node: 192.168.1.228 (Arch 1) — 4-core i3-8100T, 16GB RAM, 1.8TB NVMe Secondary test node: 192.168.1.198 (Arch 2) — 8GB RAM, 457GB disk SSH: ssh -i ~/.ssh/archipelago-deploy archipelago@{IP} Deploy: ./scripts/deploy-to-target.sh --both

SECURITY RULE: No Tor Address Publishing to Nostr Relays (2026-03-13)

NEVER publish .onion addresses to public Nostr relays. This was removed on 2026-03-13 because broadcasting Tor addresses to public relays defeats the purpose of Tor's privacy. All publish_node_identity calls have been removed from:

  • tor.rs — address rotation no longer publishes to relays
  • node.rs — node.nostr-publish RPC now returns an error
  • network.rs — visibility changes no longer publish to relays

Nodes connect via federation ID (DID), not public Nostr discovery. Federation peer notification (private peer-to-peer) is still allowed.

Tor rotation now immediately destroys the old address (no transition period). Old keys are deleted, not renamed.

All Tor addresses on .228 and .198 were rotated on 2026-03-13 to invalidate any previously published addresses.

Critical Findings from Investigation (2026-03-13)

Server .228 Issues

  • 6 containers in crash loops: archy-nbxplorer (3,535 restarts), archy-mempool-web (2,041), mempool-api (906), btcpay-server (888), mempool-electrs (529), immich_server (439)
  • Root cause: Container networking DNS failures — mempool-web can't resolve "mempool-api" upstream, nbxplorer can't connect to Postgres
  • Load average 5.44 on 4 cores — entirely caused by crash/restart cycles consuming CPU
  • ollama in Created state — never started, consuming a container slot
  • Podman rootless warning: "/" is not a shared mount

Server .198 Issues

  • No federation configured — /var/lib/archipelago/federation/ is empty
  • Tor container outdated (v0.4.6.10) — warns "missing protocols: FlowCtrl=2 Relay=4", will eventually stop working
  • Tor failing every 5 minutes: "No more HSDir available to query" — can't resolve .onion addresses
  • Memory critically low: 147MB free of 8GB, NO SWAP configured
  • Nostr identity revoked — nostr_revoked file exists but empty
  • Containers run under root — rootless podman shows nothing, sudo podman shows 35 containers

Cross-Node Issues

  • .228 → .198 HTTP health: OK (basic connectivity works)
  • .198 → .228 HTTP health: OK
  • .198 has ZERO federation peers — no nodes.json, never joined federation
  • Tor-based federation impossible from .198 — Tor can't resolve hidden services
  • No swap on either server — OOM kills likely under load
  • ping not installed on .228 (missing iputils-ping)

User Stories & Acceptance Tests

Every test must pass 10 consecutive times from BOTH .228→.198 AND .198→.228 directions.

US-01: System Health

As a node operator, I want my server to boot cleanly with all services running, zero crashed containers, and stable resource usage, so I never have to manually intervene.

US-02: Container Lifecycle

As a node operator, I want every installed app to start, run, survive reboots, and recover from crashes automatically, so my services are always available.

US-03: Federation Join

As a node operator, I want to invite another node to my federation using an invite code, so we can share status and deploy apps to each other.

US-04: Federation Sync

As a node operator, I want to see all my federated peers' status (online/offline, apps, resources) updated every 5 minutes, so I know my network health.

US-05: Tor Hidden Services

As a node operator, I want each app to have a .onion address that works reliably, so my services are accessible over Tor without exposing my IP.

US-07: File Sharing

As a node operator, I want to share files with federated peers over Tor with access controls (free, peers-only, paid), so I can selectively distribute content.

US-08: DWN Sync

As a node operator, I want DWN messages and protocols to replicate bidirectionally between my federated nodes over Tor, so my decentralized data is available everywhere.

US-09: NIP-07 Signing

As a node operator, I want iframe apps to use window.nostr to sign events with my node's Nostr key (with consent), so I can use Nostr apps with my sovereign identity.

US-10: Backup/Restore

As a node operator, I want to create encrypted backups and restore them on a fresh install, so I never lose my data or identity.

US-11: Dashboard Monitoring

As a node operator, I want real-time CPU, RAM, disk, and container health displayed on my dashboard, so I can spot problems before they escalate.

US-12: Auto-Updates

As a node operator, I want my node to check for updates, download them with integrity verification, and apply them with rollback capability.

US-13: Identity & Credentials

As a node operator, I want W3C DID Documents and Verifiable Credentials that work with did:dht for discoverable DIDs and proper VCs for proving identity claims between nodes.

US-14: Web UI Navigation

As a node operator, I want every page in the UI to load correctly, show real data (not hardcoded), and navigate without broken links or dead buttons.

US-15: Boot Recovery

As a node operator, I want all containers to automatically restart after any reboot, crash, or power loss, with zero manual intervention required.

Phase 1: Emergency Stabilization (Week 1-2)

Sprint 1: Stop the Crash Loops

  • CRASH-01 — Fix container networking on .228. Root cause: UFW blocking all traffic from Podman subnets (10.88.0.0/16, 10.89.0.0/16) to host, preventing Aardvark DNS resolution. Fix: ufw allow from 10.88.0.0/16 and ufw allow from 10.89.0.0/16. All containers on archy-net can now resolve hostnames. mempool-web stable 30+ minutes, 0 restarts.

  • CRASH-02 — Fix archy-nbxplorer Postgres connection on .228. Same root cause as CRASH-01: UFW blocking DNS. After UFW fix, nbxplorer resolves archy-btcpay-db hostname and connects to Postgres. Both nbxplorer and btcpay-server stable 30+ minutes.

  • CRASH-03 — Fix immich_server crash loop on .228. Same root cause as CRASH-01: UFW blocking DNS. Immich components on immich-net could not resolve each other. After UFW fix, immich_server started and is running stable 30+ minutes. Logs show successful Nest application startup on port 2283.

  • CRASH-04 — Removed ollama on .228. sudo podman rm ollama. Container gone, total count reduced from 33 to 32.

  • CRASH-05 — Verified .228 stability. All 32 containers running, zero exited, zero new crash loops for 30+ minutes. Load avg ~5.3 (high due to 32 containers on 4-core machine, not crash loops — was same before). Memory 1.8GB available (needs swap, see STAB-02). Health checks passing.

Sprint 2: Stabilize .198

  • STAB-01 — Added 4GB swap on .198. Created /swapfile, added to /etc/fstab for persistence. free -h shows 4.0Gi swap.

  • STAB-02 — Added 8GB swap on .228. Recreated existing 4GB swapfile as 8GB. Added to /etc/fstab. free -h shows 8.0Gi swap.

  • STAB-03 — Updated Tor on .198 (system service, not container). Added Tor Project apt repo, upgraded from 0.4.7.16 to 0.4.9.5. Restarted service, bootstrapped 100% in 10s. No "missing protocols" warnings. Hidden service hostname readable: mq2leoozlaouf6yuab7wf5i6le4fp7d52bo4l5cp5nkxo3udbkumqtad.onion.

  • STAB-04 — Tor .onion resolution working on .198 after upgrade to 0.4.9.5. Local onion resolves (curl returns "OK"). Cross-node: .198 can reach .228's onion (2vbxxly...onion/health returns "OK"). "No more HSDir available" errors stopped.

  • STAB-05 — Nostr identity on .198 is functional. nostr_revoked is intentional — blocks old-style discovery that leaked onion addresses. New publish_presence via nostr_handshake works independently. Pubkey exists: a37e28bc663b0eff59c954247b2a0b00e110babf50bcf3f2e080a8ba6888c03a. 8 relays configured. Backend restarted cleanly after removing stale empty revocation file (it correctly recreated it).

  • STAB-06 — Federation already established between .228 and .198. Verified: .228 federation.list-nodes shows 2 trusted peers with today's timestamps and app lists. .198 has nodes.json (3.6KB) and peers.json with valid onion address. Password reset to password123 on .228 for future RPC access.

  • STAB-07 — Rootless vs root podman on .198 is correctly aligned. Backend runs as root (systemd User=root), uses sudo podman via PodmanClient. Root podman shows all 34 containers. Backend's running-containers.json tracks all 34. Health monitor works.

Phase 2: Cross-Node Test Suite (Week 3-4)

Sprint 3: Create Bulletproof Test Harness

  • TEST-01 — Created scripts/test-cross-node.sh. TAP-format output, --iterations N flag, tests US-01 (health), US-05 (Tor), US-09 (NIP-07). 31/32 passed on first run. Bidirectional .228↔.198.

  • TEST-02 — US-01 health tests in test-cross-node.sh. All 6 checks per node (health, services, memory, load, disk, containers). Both nodes pass. .228 load dropped to 3.78 (from 5.44 pre-fix).

  • TEST-03 — US-02 Container Lifecycle tests added to test-cross-node.sh. Per node: (1) all-running check (zero exited), (2) container count >= 20, (3) stop filebrowser → health monitor auto-restarts within 90s (tested: .228 in 40-50s, .198 in 15-35s). .198 has pre-existing searxng exit 127 (broken entrypoint). 10/12 checks pass per run.

  • TEST-04 — US-03 Federation Join tests added to test-cross-node.sh. Per node per iteration: (1) peers present >= 1, (2) trust_level == "trusted", (3) DID starts with "did:", (4) last_seen within 10 min. Fixed stale onion addresses in federation nodes.json on both servers (Tor rotation made old addresses unreachable). All 16/16 checks passing after fix.

  • TEST-05 — US-04 Federation Sync tests added to test-cross-node.sh. Per node: (1) sync-state returns results, (2) at least 1 sync succeeds, (3) synced node has apps > 0, (4) last_seen updated within 2 min after sync. .228 syncs 2 peers (23 apps each), .198 syncs 1 peer (25 apps). All 16/16 checks passing.

  • TEST-06 — US-05 Tor tests in test-cross-node.sh. Both directions pass: .228→.198 via Tor returns "OK", .198→.228 via Tor returns "OK". 4/4 passed (2 iterations x 2 directions).

  • TEST-08 — US-07 tests: File Sharing (10x). content.add, content.list-mine, content.browse-peer bidirectionally over Tor (.228↔.198). Fixed ssh_sudo compound command bug (chown ran without sudo, killed script via set -e). All 50/50 checks pass (10 iterations × 5 checks: add-A, list-A, browse-A→B, add-B, browse-B→A).

  • TEST-09 — US-08 tests: DWN Sync (10x). Fixed DWN sync: made sync endpoint async (background task with polling), added 90s overall timeout, deduplicated peer onion addresses, batched message pushes (50/batch), added connect_timeout, fixed HTTP handler to process all messages in batch. All 50/50 checks pass (10 iterations × 5 checks: register, write-3, sync, received-on-198, bidirectional). Each iteration completes in ~35s over Tor.

  • TEST-10 — US-09 NIP-07 provider injection test in test-cross-node.sh. nostr-provider.js detected in /app/mempool/ on both nodes. 4/4 passed.

  • TEST-11 — US-10 tests: Backup/Restore (10x). Added US-10 section to test-cross-node.sh. Tests create/list/verify/delete cycle on both nodes. Increased backup.create rate limit from 3/600 to 10/600. Cleaned up 21K+ stale DWN test messages on both nodes that were inflating backup size. All 80/80 checks pass (10 iterations × 4 checks × 2 nodes).

  • TEST-12 — US-15 Boot Recovery. Added US-15 section to test-cross-node.sh with --skip-reboot flag. .228: 9/9 pass — 32/32 containers survive all 3 reboots, 0 exited, health OK ~5s post-SSH. .198: crash recovery blocks health for 260s (34 containers × ~10s sequential); needs CONT-02. (KNOWN ISSUE: .228 unreachable after 3rd reboot — SSH/HTTP down despite ICMP. Likely UFW rules didn't persist. Needs physical access.)

Phase 3: UI Cosmetic Cleanup (Week 5-6)

Sprint 4: Information Hierarchy & Deduplication

  • UI-CLEAN-01 — Audited all views. Dashboard/Home: CLEAN (real RPC data). Server.vue: servicesRunning/connectivityStatus hardcoded, autoSync no backend, logCount never updated. Web5.vue: walletConnected never updated, DID status localStorage-only.

  • UI-CLEAN-02 — Dashboard (Home.vue) verified CLEAN. CPU/RAM/disk from system.stats RPC, container counts from store, uptime from RPC. Web5 card fetches from identity/dwn/credentials RPCs. Cloud stats from FileBrowser API. No hardcoded data.

  • UI-CLEAN-03 — Fixed Server.vue: added connectivity check on mount (was hardcoded 'connected'), restart now polls health endpoint instead of assuming success after 2s. Network data already fetches from real RPC endpoints (diagnostics, vpn, dns, interfaces). Deployed and verified.

  • UI-CLEAN-04 — Verified Web5.vue information hierarchy. All data from real RPC endpoints: DID from identity.create-did (cached in localStorage), wallet from lnd.getinfo on mount, Nostr relays from nostr.list-relays, DWN from dwn.status/dwn.list-protocols/dwn.query-messages, credentials from identity.list-credentials. No hardcoded placeholder numbers. Zero fake data.

  • UI-CLEAN-05 — Verified Settings.vue has zero section duplication. Account (server name, version, session, password, DID/Tor identity) is unique to Settings. 2FA is unique. Backup is unique. System Updates links to /dashboard/settings/update. DID/Tor appear as read-only identity display in Settings vs. interactive management in Web5 — different contexts, not duplication. Webhooks, AI Data Access, Claude Auth, Interface Mode all unique to Settings.

  • UI-CLEAN-06 — Verified Marketplace.vue curated app list accuracy. All 33 apps have valid icons (verified all files exist in app-icons/). Fixed photoprims.svg → photoprism.svg typo in filename, Marketplace.vue, and mock-backend.js. Docker images reference legitimate registries (docker.io, ghcr.io). External web apps (nostrudel, botfights, nwnn, etc.) correctly use webUrl with empty dockerImage. Deployed and verified.

  • UI-CLEAN-07 — Verified Cloud.vue file management. File sections (Photos, Music, Documents, All) use fileBrowserClient.listDirectory() with real paths (/Photos, /Music, /Documents, /). Peer Files shows rpcClient.federationListNodes() count and links to PeerFiles view. Upload via cloudStore.uploadFile() → fileBrowserClient. Download via fileBrowserClient.downloadUrl(). Zero hardcoded data.

  • UI-CLEAN-08 — Verified Federation.vue accuracy. Node list from rpcClient.federationListNodes(). Online/offline based on last_seen 10-min threshold. NetworkMap component renders with computed mapNodes/mapLinks from real data. Generate invite via federationInvite() RPC. Sync via federationSyncState() RPC. DWN sync status from dwn.status RPC. Self DID from getNodeDid(). Zero hardcoded data.

  • UI-CLEAN-09 — Verified Chat.vue state. Checks AIUI availability via fetch('/aiui/', { method: 'HEAD' }). Shows loading spinner while checking. Renders iframe when available. Shows clean fallback: "AI Assistant needs to be enabled before use. Go to Settings to configure your AI provider API key." No broken UI, no errors.

  • UI-CLEAN-10 — Verified Apps.vue installed app display. Real containers from store.packages (WebSocket from backend's podman ps). Status badges: running=green, stopped=gray, starting/installing=yellow/blue via getStatusClass(). Web-only apps (Indeehub, BotFights, etc.) are intentional external bookmarks, not phantom containers. Click navigates to /dashboard/apps/${id}. Fallback SVG placeholder for broken icons.

  • UI-CLEAN-11 — Type-check passes. npm run type-check exits 0.

  • UI-CLEAN-12 — Build passes. npm run build exits 0, 146 precache entries, 2.81s build time.

Phase 4: Backend Hardening (Week 7-10)

Sprint 5: Container Management Reliability

  • CONT-01 — Audited container network topology on .198 (4 networks: archy-net, immich-net, penpot-net, podman). Fixed needs_archy_net in package.rs to include lnd, archy-nbxplorer, nbxplorer (were missing — would install on wrong network via UI). Moved fedimint + fedimint-gateway from default podman network to archy-net on .198. Created docs/network-topology.md with full diagram. (.228 audit pending — SSH unreachable. penpot-frontend/backend missing on .198.)

  • CONT-02 — Added container dependency ordering to health_monitor.rs via StartupTier enum (Database → CoreInfra → DependentService → Application → Frontend). Unhealthy containers sorted by tier before restart. 5s delay between tiers to let dependencies stabilize. container_tier() classifies all known containers into proper startup order.

  • CONT-03 — Added get_health_check_args() function in package.rs with health checks for 20+ apps: bitcoin-knots (bitcoin-cli), lnd (lncli), btcpay-server (HTTP), mempool-api (HTTP /api/v1/backend-info), nextcloud, homeassistant, grafana, jellyfin, vaultwarden, uptime-kuma, filebrowser, searxng, photoprism, immich, dwn, portainer, ollama, fedimint, nostr-relay, nginx-proxy-manager. All use 30-60s intervals, 3 retries, 60s start period.

  • CONT-04 — Added exponential backoff to health monitor restarts: 10s, 30s, 90s delays (BACKOFF_DELAYS_SECS). RestartTracker now tracks last_failure timestamps and checks backoff_elapsed() before retrying. After MAX_RESTART_ATTEMPTS (3), container marked failed. Auto-reset after STABILITY_RESET_SECS (3600s = 1 hour) via should_reset_failed().

  • CONT-05 — Added get_memory_limit() function in package.rs with per-app limits replacing the blanket 2g default. Heavy: bitcoin-knots (2g), onlyoffice (2g), ollama (4g). Medium: lnd/fedimint/homeassistant/mempool-api/searxng (512m), electrs/nextcloud/immich/btcpay/jellyfin/photoprism (1g). Light: mempool-web/grafana/vaultwarden/uptime-kuma/filebrowser/dwn/portainer/nostr-relay/nginx-proxy-manager (256m). Databases: postgres (512m), redis/valkey (128m).

  • CONT-06 — Verified: rootless podman mount warning no longer appears. sudo podman ps 2>&1 | grep warning returns empty on .228. Backend runs as root (sudo podman), not rootless, so the warning is not applicable.

Sprint 6: Backend Security & Reliability

  • SEC-01 — Audited all 100+ RPC endpoints. Fixes applied: (1) Error sanitization via sanitize_error_message() in mod.rs — strips internal paths, returns generic messages for non-validation errors. (2) Identity ID validation via validate_identity_id() — blocks path traversal in identity.get/delete/set-default/sign. (3) DID validation via validate_did() — blocks path traversal in federation.remove-node/set-trust. (4) Message size limit (1MB) on node-send-message. (5) DWN data size limit (10MB) on dwn.write-message. Auth/CSRF strong across all endpoints. No shell injection found (all commands use .args() array).

  • SEC-02 — Added rate limiting to federation endpoints in session.rs EndpointRateLimiter: federation.join (5/60s), federation.invite (10/300s), federation.peer-joined (10/60s), federation.peer-address-changed (10/60s), federation.get-state (30/60s). Rate limiter already runs before auth check in mod.rs, so unauthenticated inter-node RPCs are also covered.

  • SEC-03 — Verified CSRF validation in mod.rs lines 206-234: all non-UNAUTHENTICATED_METHODS require both session cookie AND X-CSRF-Token header matching csrf_token cookie. Token is 32-byte random hex generated on login (line 712-715). SameSite=Strict + HttpOnly flags set. 100% of authenticated endpoints reject requests without valid CSRF token.

  • SEC-04 — Audited container security profiles. All containers via package.install get: --cap-drop=ALL (line 258), --security-opt=no-new-privileges:true (line 259), --restart=unless-stopped (line 183), per-app capabilities via get_app_capabilities(). Read-only filesystem for 8 compatible apps via is_readonly_compatible(). Memory limits via get_memory_limit(). Image pinning: 7 Docker Hub images still use :latest (bitcoin-knots, photoprism, searxng, tailscale, adguardhome, nginx-proxy-manager, mempool-electrs). Localhost-built UIs use :latest intentionally.

  • SEC-05 — Configured log rotation on both nodes. Journald: set SystemMaxUse=500M, MaxRetentionSec=7day, Compress=yes in /etc/systemd/journald.conf.d/archipelago.conf. Vacuumed .228 journal from 3.0GB to 459.7MB. Added /etc/logrotate.d/archipelago for crowdsec and archipelago logs (daily, 7 days, compress). Nginx logrotate already existed.

  • SEC-06 — Verified all 4 security headers present on both nodes: X-Frame-Options: SAMEORIGIN, X-Content-Type-Options: nosniff, Content-Security-Policy (with frame-src *), Referrer-Policy: strict-origin-when-cross-origin.

Phase 5: Reboot & Uptime Hardening (Week 11-14)

Sprint 7: Zero-Downtime Reboot Testing

  • REBOOT-01 — Created scripts/test-reboot-survival.sh. TAP-format output with --node, --iterations, --rest-between flags. Records pre-reboot containers, reboots via sudo, waits for SSH (180s max) + health (120s max) + container stabilization (120s), verifies: container count recovered, no exited, all pre-reboot containers back, health OK, no restart loops. 6 checks per iteration.

  • REBOOT-02 — Ran reboot survival test 3x on .228. 21/21 checks passed. All 3 reboots: 32/32 containers survive, 0 exited, all containers back, health OK, no restart loops. SSH recovery: 130-145s. Health available: 5s after SSH. Total recovery ~255-270s (includes 120s stabilization wait). Zero failures.

  • REBOOT-03 — (BLOCKED: .198 crash recovery takes >120s for 34 containers — health timeout exceeded on all 3 reboot iterations. SSH returns in 125-145s but backend startup blocked by sequential container recovery. Needs CONT-02 deployment to .198 and/or increased health wait timeout. 3/6 checks passed — SSH comes back reliably.)

  • REBOOT-04 — Test simultaneous reboot of both nodes. Reboot .228 and .198 at the same time. After both recover, verify: federation re-establishes, DWN sync works, file sharing works. Acceptance: Both nodes fully recover. Federation sync succeeds within 10 minutes of both being back.

  • REBOOT-05 — Test power-cut simulation (SIGKILL). On each node: sudo kill -9 $(pgrep archipelago). Verify systemd restarts the backend, health monitor restarts containers, and everything recovers. Run 10 times per node. Acceptance: Full recovery within 90s, 10/10 times.

Sprint 8: Memory & Storage Monitoring

  • MEM-01 — Added OOM-kill detection in disk_monitor.rs. check_oom_kills() runs dmesg --level=err,crit every 5 minutes, filters for "oom-kill" / "Out of memory" lines. New OOM kills logged via warn!() and written to data_dir/oom-alert.json for frontend consumption. Tracks last_oom_count to only alert on new events.

  • MEM-02 — Added container memory leak detection in health_monitor.rs. MemoryTracker records per-container RSS samples every 5 minutes (288 samples max = 24h). check_leak() compares oldest vs newest sample — warns if growth > 50%. Uses podman stats --no-stream for live memory data. parse_memory_string() handles GiB/MiB/KiB formats.

  • MEM-03 — Added disk growth alerting in disk_monitor.rs. Tracks 288 disk usage samples (24h at 5min intervals). Calculates daily growth rate from oldest→newest sample. Warns if growth > 1GB/day. 85% warning and 90% auto-cleanup with disk-warning.json already existed.

  • MEM-04 — Added systemd watchdog. archipelago.service: Type=notify, WatchdogSec=60. main.rs: sd_notify::Ready on startup, spawns background task pinging sd_notify::Watchdog every 30s. Added sd-notify = "0.4" to Cargo.toml. If backend hangs, systemd auto-restarts within 60s.

  • MEM-05 — Run 7-day continuous monitoring on both nodes. Deploy uptime-monitor.sh on both nodes. Cron every 5 minutes. Track: HTTP status, response time, CPU, memory, disk, container count, restart count. After 7 days, generate summary. Acceptance: Both nodes maintain > 99.9% uptime (< 10 minutes total downtime including intentional tests). Zero OOM kills. Zero unexpected restarts.

Phase 6: did:dht & Interoperable Schemas (Week 15-20)

Sprint 9: did:dht Implementation

  • DHT-01 — Created docs/did-dht-integration.md. Covers: did:dht spec (BEP-44 mutable DHT items), DNS packet encoding, z-base-32 identifiers, publication/resolution flows, mainline crate for Rust DHT access, security considerations (no Tor addresses in public DHT), comparison with did:key, new RPC endpoints, background refresh every 2h, integration points with federation/VCs/Web5 UI.

  • DHT-02 — Implement did:dht creation in identity_manager.rs. Add create_dht_did() method that: (1) generates Ed25519 keypair, (2) creates a DNS packet encoding per did:dht spec, (3) publishes to Mainline DHT using a Rust BitTorrent DHT library (e.g., mainline crate). The node should have BOTH did:key (local, offline) and did:dht (discoverable, no server needed). Add identity.create-dht-did RPC endpoint. Acceptance: Can create a did:dht and resolve it from another machine using the DHT.

  • DHT-03 — Implement did:dht resolution. Add identity.resolve-dht-did RPC endpoint that takes a did:dht identifier, queries the Mainline DHT, retrieves and parses the DNS packet, returns the DID Document. Cache resolved DIDs for 1 hour. Acceptance: Can resolve a did:dht created on .228 from .198 without Tor, without Nostr relays, using only the BitTorrent DHT.

  • DHT-04 — Update Web5 UI for did:dht. Show both did:key and did:dht in the identity section. Add "Publish to DHT" button. Show DHT resolution status. Acceptance: Web5 page shows both DID types. DHT publish and resolve work from the UI.

Sprint 10: DWN Protocol Definitions for Interoperable Schemas

  • SCHEMA-01 — Created docs/dwn-protocols.md with 4 protocol definitions: (1) Node Identity Announcements (node-identity/v1) — public, node DID/version/apps/capabilities. (2) File Sharing Catalog (file-catalog/v1) — public, file entries with access levels/pricing. (3) Federation State (federation/v1) — private, membership + peer status with trust levels. (4) App Deployment Requests (app-deploy/v1) — private, request/response for remote app install. All with JSON schemas, DWN protocol definition format, and interoperability notes.

  • SCHEMA-02 — Added register_dwn_protocols() to server.rs. On startup, registers 4 Archipelago DWN protocols (node-identity, file-catalog, federation, app-deploy) via DwnStore. Skips already-registered protocols. Runs as non-blocking background task. (.228 verification pending — node unreachable after reboot tests. .198 will register on next deploy.)

  • SCHEMA-03 — Added DWN file catalog integration to content.add. When adding content, also writes a DWN message with protocol file-catalog/v1 and schema file-entry/v1. Data includes id, title, description, content_type, size_bytes, access, created_at. Non-fatal on DWN errors. Existing content flow unchanged. (Cross-node verification pending .228 recovery.)

  • SCHEMA-04 — Added DWN federation membership integration. When a peer joins via federation.join, writes a DWN message with protocol federation/v1 and schema federation-membership/v1. Data includes node_did, trust_level, joined_at. Non-fatal on DWN errors. (Cross-node verification pending .228 recovery.)

Sprint 11: Verifiable Credentials Between Nodes

  • VC-01 — Added did:dht support to VCs. Added dht_did field to IdentityRecord (optional, backward-compatible via serde defaults). Added prefer_dht_did param to identity.issue-credential RPC — when true, uses did:dht as issuer if available. Credential system already format-agnostic (accepts any DID string). (Full DHT-based verification requires DHT-02/03 implementation.)

  • VC-02 — Added FederationTrustCredential issuance. On federation.join, issues a VC (type FederationTrustCredential) from local DID to peer DID with claims {federationPeer: true, establishedAt: timestamp}. Runs in background task (non-blocking). Signed with node identity key. Stored via credentials system. (Peer-side VC from peer-joined handler pending.)

  • VC-03 — Add VC presentation in federation handshake. Update federation.join and federation.get-state to include VC presentations. Peers can verify the VC chain before trusting a node. Acceptance: Federation join includes VC exchange. federation.list-nodes includes VC verification status per peer.

  • VC-04 — Test VC flow between .228 and .198 (10x). (1) Issue VC on .228 to .198's DID, (2) Verify VC on .198, (3) Create presentation on .198 including the VC, (4) Verify presentation on .228. Run 10 times each direction. Acceptance: 80 checks, all pass.

Phase 7: Deploy Pipeline & ISO Hardening (Week 21-26)

Sprint 12: Deploy Script Hardening

  • DEPLOY-01 — Audited deploy-to-target.sh. Fixes: (1) set -eo pipefail for pipe error detection. (2) Fixed duplicate NEED_INSTALL="". (3) --both path now fails on missing binary instead of || true. (4) Added post-deploy health check on .198 (polls every 5s for 60s). Rollback is deferred to DEPLOY-03.

  • DEPLOY-02 — Added --canary flag to deploy-to-target.sh. Runs --both (deploys to .228 then .198), then verifies .198 health (polls 12x at 5s). Exits 1 if canary fails.

  • DEPLOY-03 — Added rollback capability to deploy-to-target.sh. Pre-deploy: backs up binary to /opt/archipelago/rollback/archipelago.bak and web-ui to rollback/web-ui.tar. Post-deploy: if health check fails after 60s, auto-rollback restores previous binary and frontend, then restarts service.

  • DEPLOY-04 — Added --dry-run flag to deploy-to-target.sh. Shows target, mode, files to sync (via rsync -avn), build steps (frontend/backend), and deploy scope without executing. Works with all other flags (--live, --both, --frontend-only). Updated usage header.

Sprint 13: ISO Build Hardening

  • ISO-01 — Audited ISO build script. Found 9 running apps missing from CAPTURE_PATTERNS and CONTAINER_IMAGES: jellyfin, photoprism, nextcloud, nginx-proxy-manager, immich (3 containers), onlyoffice, adguardhome, penpot. Added all to CAPTURE_PATTERNS and CONTAINER_IMAGES fallback list with pinned versions.

  • ISO-02 — Added swap creation to first-boot-containers.sh. Calculates 50% of RAM (min 2GB, max 8GB), creates /swapfile, sets permissions 600, mkswap + swapon, adds to /etc/fstab. Skips if swap already exists. Runs before container creation so apps have swap available.

  • ISO-03 — Added tiered startup ordering to first-boot-containers.sh. Tier 1: Databases & Core Infrastructure (Bitcoin, MariaDB, Postgres, Electrs). Tier 2: Core Services (LND, Fedimint) with 5s stabilization delay. Tier 3: Applications (Home Assistant, Grafana, etc.) with 5s delay. Matches CONT-02's StartupTier approach.

Phase 8: Scale Testing for 10K Users (Week 27-36)

Sprint 14: Resource Budget for 10K Users

  • SCALE-01 — Created docs/scale-budget.md. Per-container RAM/CPU/disk measurements from .228. Three app tiers: Core (2.6GB, Bitcoin+LND+Electrs+Mempool+BTCPay+DWN), Recommended (+880MB, Fedimint+Grafana+Vaultwarden+etc), Optional (+2-5GB, Home Assistant+Jellyfin+Nextcloud+Immich+etc). Four hardware tiers: Minimal (4GB/2 cores/$100), Standard (8GB/4 cores/$300), Power (16GB+/$500), Heavy (32GB+/$800). 10K user projection with distribution estimates.

  • SCALE-02 — Identified in docs/scale-budget.md. Top consumers: OnlyOffice (760MB), Bitcoin Knots (750MB), Immich (630MB total), Electrs (500MB), Fedimint (470MB total). Tiered app list: Core (2.6GB: Bitcoin+LND+Electrs+Mempool+BTCPay+DWN+FileBrowser), Recommended (+880MB: Fedimint+Grafana+Vaultwarden+Kuma+SearXNG+Tailscale+Portainer), Optional (+2-5GB: HA+Jellyfin+Nextcloud+OnlyOffice+Immich+PhotoPrism+AdGuard+Ollama).

  • SCALE-03 — Added app tier system in backend. get_app_tier() in docker_packages.rs classifies apps as "core" (Bitcoin+LND+Electrs+Mempool+BTCPay+DWN+FileBrowser), "recommended" (Fedimint+Grafana+Vaultwarden+Kuma+SearXNG+Tailscale+Portainer), or "optional" (everything else). Tier field added to Manifest struct in data_model.rs, exposed via WebSocket package data to frontend.

  • SCALE-04 — Added resource monitoring alerts in monitoring/mod.rs. Lowered disk threshold to 80% (was 90%). Lowered RAM threshold to 80% (was 90%). Added CpuLoad alert type: fires when 5-min load average > threshold × core count (default threshold: 2.0). Uses num_cpus crate for core detection.

Sprint 15: Automated Fleet Testing

  • FLEET-01 — Created scripts/test-all-features.sh. TAP format, takes target IP + --iterations N. Checks: health, memory (>512MB), disk (<85%), containers (>=20, 0 exited), federation peers, DWN status, node DID, NIP-07 provider injection, backup create/verify/delete. 10 checks per iteration + 3 backup checks (first iteration only). Exit 0 = production ready.

  • FLEET-02 — Run test-all-features on .228. Execute the full test suite 10 iterations. Document any failures, fix them, rerun until 10/10 clean. Acceptance: 10 consecutive clean runs on .228.

  • FLEET-03 — Run test-all-features on .198. Same as FLEET-02 but on .198. Acceptance: 10 consecutive clean runs on .198.

  • FLEET-04 — Run cross-node test suite 10 times. Execute test-cross-node.sh --iterations 10 covering all bidirectional tests. Acceptance: All cross-node tests pass 10/10 from both directions.

Sprint 16: Long-Duration Soak Test

  • SOAK-01 — Run 30-day soak test on both nodes. Deploy monitoring, leave both nodes running for 30 days. Monitor: uptime, memory trend (leak detection), disk growth, container restart counts, federation sync success rate, Tor uptime. Acceptance: Both nodes > 99.95% uptime. No memory leaks (RSS stable ±10% over 30 days). Zero unexpected restarts.

  • SOAK-02 — Run hourly federation sync verification for 30 days. Cron job every hour: trigger federation sync, verify success, log result. After 30 days, calculate sync success rate. Acceptance: > 99% sync success rate over 30 days.

  • SOAK-03 — Run daily reboot test for 30 days. Automated daily reboot at 4 AM, verify full recovery by 4:05 AM. Log recovery time each day. Acceptance: 30/30 successful recoveries. Average recovery < 120s.

  • SOAK-04 — Compile final stability report. After 30-day soak, generate report: uptime %, memory trend, disk trend, federation reliability, container health, incident log. This becomes the go/no-go for declaring production ready. Acceptance: Report shows all metrics meeting production targets.

Phase 9: Production Polish (Week 37-44)

Sprint 17: Performance Optimization

  • PERF-01 — Optimized backend startup. Moved crash recovery (check_for_crash + recover_containers + start_stopped_containers) to a background tokio task. Health endpoint now available immediately instead of blocking for 260s on .198. PID marker written before recovery starts. Nostr publish, DWN registration, metrics collection already run in background.

  • PERF-02 — Frontend bundle already meets target. Initial load: index.js 110KB gzipped (target: <500KB). All route views lazy-loaded by Vite (code-split per route). Total JS: 947KB raw, ~312KB gzipped across all chunks. No changes needed.

  • PERF-03 — Optimize container image sizes. Pull all container images and check sizes. Replace any > 1GB images with smaller alternatives (alpine-based). Remove any cached layers for old versions. Acceptance: Total container image disk usage reduced by > 20%.

  • PERF-04 — Added ResponseCache to RpcHandler. TTL-based cache (5s) for system.stats and federation.list-nodes. Cache check before dispatch returns cached result immediately. Successful results stored after dispatch. Thread-safe via tokio::sync::RwLock.

Sprint 18: Documentation Update

  • DOC-01 — Updated CHANGELOG.md with v1.2.0 release. Covers: crash loop fixes, DWN sync performance, backup reliability, deploy script hardening, cross-node test suite (DWN/backup/boot recovery), did:dht architecture, DWN protocol definitions, deploy --dry-run, ISO swap/tiered startup, security hardening.

  • DOC-02 — Updated architecture.md. Removed StartOS references. Added: Identity & Federation section (identity.rs, credentials.rs, federation, DWN), container networking (archy-net, Aardvark DNS, UFW rules), Tor integration, multi-node federation overview, updated data persistence paths (DWN, identity, credentials, content, federation).

  • DOC-03 — Rewrote current-state.md from scratch. Removed all StartOS references. Documents: pure Archipelago stack (Debian 12, Rust, Vue 3, Podman), 2 active nodes with specs, backend module layout, 10+ working features, planned features, cross-node test coverage matrix.

  • DOC-04 — Created docs/operations-runbook.md with 17 sections: health checks, container status, fix crashes, federation peers, Tor rotation, backup/restore, updates, CPU/memory/disk diagnostics, Tor connectivity, DWN sync, service restart, log viewing, network diagnostics, emergency boot recovery, cross-node tests.

Phase 10: Year 2-5 Roadmap (Month 13-60)

Year 2 (2027): Multi-Hardware & Community

  • Y2-01 — Test and certify on 5 hardware platforms: generic x86_64 PC, Intel NUC, Raspberry Pi 5, mini-PC (N100), used ThinkCentre. Document per-platform quirks. Acceptance: ISO boots and works on all 5 platforms.

  • Y2-02 — Community app submission pipeline. Automated review of community-submitted app manifests: security scan, resource check, dependency validation, sandbox test. Acceptance: Community can submit apps via PR, automated checks run, maintainer approves.

  • Y2-03 — Multi-language support. Translate UI to 5 languages (Spanish, Portuguese, German, French, Japanese) using the i18n infrastructure already in place. Acceptance: Language selector in Settings, all strings translated.

  • Y2-04 — Mobile companion app (read-only). Progressive Web App or native app that connects to node over Tailscale/Tor and shows: dashboard, container status, notifications. No mutations — read-only for safety. Acceptance: Can view node status from phone.

Year 3 (2028): Enterprise & Scale

  • Y3-01 — Multi-user support. Add user roles (admin, viewer, app-user). Admin can manage everything. Viewer sees dashboard only. App-user accesses specific apps. Acceptance: 3 user roles with proper permission separation.

  • Y3-02 — Automated backup to S3-compatible storage. In addition to USB backup, support backup to any S3 endpoint (Backblaze B2, Wasabi, self-hosted MinIO). Encrypted before upload. Acceptance: Backup to S3 works, restore from S3 works.

  • Y3-03 — Cluster mode for high availability. 3+ nodes form a cluster where apps have replicas. If one node goes down, apps failover to another. Uses Raft or similar consensus. Acceptance: Stop one node in a 3-node cluster — apps continue serving from remaining nodes.

  • Y3-04 — Hardware attestation with TPM 2.0. Nodes with TPM chips can cryptographically prove their hardware identity. Adds trust layer to federation. Acceptance: TPM-equipped node includes hardware attestation in its DID Document.

Year 4 (2029): Ecosystem & Market

  • Y4-01 — App developer SDK. Command-line tool for app developers: archy-dev create, archy-dev test, archy-dev publish. Scaffolds manifest, runs security checks, publishes to marketplace. Acceptance: Developer can publish a new app in under 30 minutes using the SDK.

  • Y4-02 — Paid app marketplace. Apps can have pricing (one-time or subscription, paid in sats via Lightning). Revenue split between developer and node operator. Uses Cashu or Lightning invoices. Acceptance: End-to-end payment flow works.

  • Y4-03 — Node analytics dashboard (opt-in). Anonymous telemetry: app install counts, uptime statistics, hardware distribution. Helps prioritize development. Strictly opt-in. Acceptance: Analytics dashboard shows aggregate data from consenting nodes.

  • Y4-04 — Cross-chain support (Monero, Liquid). Add support for Monero full node and Liquid sidechain containers. Federation supports multi-chain status reporting. Acceptance: Can run Bitcoin + Monero + Liquid on same node.

Year 5 (2030-2031): Production at Scale

  • Y5-01 — Achieve 10,000 active nodes. Track via opt-in analytics. Support infrastructure: documentation, community forum, bug tracker, release automation. Acceptance: 10K+ nodes running Archipelago, measured via marketplace relay or opt-in telemetry.

  • Y5-02 — Zero-downtime updates. Update mechanism that migrates containers one-by-one with health checks between each. No service interruption during update. Acceptance: Update from v2.x to v2.y with zero downtime measured by external monitor.

  • Y5-03 — Formal security audit by third party. Engage professional security firm to audit: backend code, container isolation, authentication, cryptography, network security. Fix all findings. Acceptance: Clean audit report with no critical/high findings.

  • Y5-04 — v3.0 release with all Year 5 features. Stable, audited, scale-tested release for mass adoption. Acceptance: Tagged v3.0.0 release with full documentation and ISO downloads.

Test Matrix Summary

Test Category # Checks Per-Direction Iterations Total Passes Required
System Health (US-01) 6 x2 x10 120
Container Lifecycle (US-02) 4 x2 x10 80
Federation Join (US-03) 4 x2 x10 80
Federation Sync (US-04) 4 x2 x10 80
Tor Hidden Services (US-05) 3 x2 x10 60
Nostr Discovery (US-06) 4 x2 x10 80
File Sharing (US-07) 5 x2 x10 100
DWN Sync (US-08) 5 x2 x10 100
NIP-07 Signing (US-09) 4 x2 x10 80
Backup/Restore (US-10) 4 x2 x10 80
Boot Recovery (US-15) 5 x2 x3 30
TOTAL 48 890

Every single one of these 890 test passes must succeed before declaring production-ready.

Milestone Summary

Date Milestone Key Deliverables
Mar 2026 Week 2 Phase 1 Complete Crash loops fixed, .198 stabilized, federation established
Mar 2026 Week 4 Phase 2 Complete 890 cross-node test passes, bulletproof test harness
Apr 2026 Week 2 Phase 3 Complete UI cosmetic cleanup, zero fake data, zero TypeScript errors
May 2026 Phase 4 Complete Container reliability, security audit, log rotation
Jun 2026 Phase 5 Complete 10x reboot survival, memory monitoring, systemd watchdog
Aug 2026 Phase 6 Complete did:dht, DWN interoperable schemas, VCs between nodes
Oct 2026 Phase 7 Complete Deploy pipeline hardened, ISO verified
Jan 2027 Phase 8 Complete 30-day soak test passed, scale budget documented
Apr 2027 Phase 9 Complete Performance optimized, docs updated, v1.2.0 tagged
2028 Year 2 Multi-hardware, community apps, mobile companion
2029 Year 3 Multi-user, S3 backup, cluster HA, TPM attestation
2030 Year 4 App SDK, paid marketplace, cross-chain
2031 Year 5 10K users, zero-downtime updates, security audit, v3.0

Execution Instructions

For each task in order:

  1. Find the first unchecked - [ ] item
  2. Read the task description and acceptance criteria carefully
  3. Read ALL relevant source files before making changes
  4. Implement following CLAUDE.md conventions strictly
  5. For frontend changes: cd neode-ui && npm run type-check && npm run build, deploy with ./scripts/deploy-to-target.sh --both
  6. For backend changes: deploy with ./scripts/deploy-to-target.sh --both (builds on server, not macOS)
  7. For test scripts: create on local, rsync to server, run via SSH
  8. Verify acceptance criteria are met ON BOTH SERVERS
  9. Mark it done - [x] in this file
  10. Commit: type: description
  11. Move to the next unchecked task immediately

CRITICAL: Every change must be deployed to BOTH .228 AND .198. Tests must pass from BOTH directions.

Total tasks: 98 across 18 sprints over 5 years.