Archipelago — open-source initial import

2026-08-12 10:55:49 +00:00
commit e502804df8
1634 changed files with 350014 additions and 0 deletions
@@ -0,0 +1,402 @@
+# Archipelago User Walkthrough
+
+A complete guide to setting up and using Archipelago, from hardware to daily use. Each section describes what the user sees and does, serving as the basis for video tutorials.
+
+---
+
+## Part 1: Hardware & Preparation
+
+### What You Need
+
+- **Hardware**: Any x86_64 PC (Intel NUC, mini PC, old desktop) or Raspberry Pi 5
+  - Minimum: 4GB RAM, 32GB SSD
+  - Recommended: 8GB+ RAM, 1TB+ NVMe SSD (for Bitcoin full node)
+- **USB drive**: 8GB+ for the installer
+- **Network**: Ethernet cable (recommended) or WiFi
+- **Monitor + keyboard**: For initial setup (optional if using headless mode)
+- **Another computer**: To flash the USB and access the web UI
+
+### Step 1: Download the ISO
+
+> **Screenshot**: Browser showing the Archipelago releases page with download buttons for x86_64 and ARM64 ISOs.
+
+1. Go to the Archipelago releases page
+2. Download the latest `archipelago-auto-installer-*.iso` for your architecture
+3. Verify the checksum matches the published hash
+
+### Step 2: Flash the USB Drive
+
+> **Screenshot**: Balena Etcher with the ISO selected and a USB drive ready to flash.
+
+1. Download [Balena Etcher](https://etcher.io) (free, cross-platform)
+2. Insert your USB drive
+3. Open Etcher, select the downloaded ISO
+4. Select your USB drive
+5. Click "Flash!" — wait for completion (2-5 minutes)
+
+### Step 3: Boot from USB
+
+> **Screenshot**: BIOS boot menu showing USB drive as an option.
+
+1. Insert the flashed USB into your target hardware
+2. Power on and enter BIOS/boot menu (usually F2, F12, or Del during boot)
+3. Select the USB drive as the boot device
+4. The installer will start automatically
+
+---
+
+## Part 2: Installation
+
+### Step 4: Auto-Installer Runs
+
+> **Screenshot**: Terminal showing the auto-installer progress — partitioning, copying files, setting up the system.
+
+The auto-installer handles everything:
+- Partitions the target disk (erases existing data)
+- Copies the Archipelago system
+- Installs the bootloader
+- Pre-loads container images for offline app installation
+
+**Duration**: 5-15 minutes depending on hardware speed.
+
+### Step 5: First Boot
+
+> **Screenshot**: Console showing systemd services starting — archipelago.service, nginx, podman.
+
+1. Remove the USB drive when prompted
+2. The system reboots into Archipelago
+3. Services start automatically (takes 30-60 seconds)
+4. If a monitor is connected, the kiosk mode launches showing the web UI
+
+---
+
+## Part 3: First-Time Setup (Onboarding)
+
+### Step 6: Connect to the Web UI
+
+> **Screenshot**: Browser address bar showing `http://192.168.1.x` with the Archipelago splash screen loading.
+
+1. Find your server's IP address:
+   - Check your router's DHCP client list
+   - Or connect a monitor — the IP is shown on the kiosk display
+2. Open a browser on any device on the same network
+3. Navigate to `http://<server-ip>`
+4. The splash screen plays the Archipelago intro animation
+
+### Step 7: Tap to Start
+
+> **Screenshot**: The splash screen with "Tap anywhere to begin" text and cosmic background animation.
+
+1. The intro screen shows the Archipelago logo with atmospheric music
+2. Tap or click anywhere to proceed
+3. A typing animation welcomes you: "Welcome, Noderunner"
+
+### Step 8: Login Screen
+
+> **Screenshot**: The login screen with a password field and glass-morphism design.
+
+1. Enter the default password: `password123`
+2. Click "Login"
+3. You'll be prompted to change this password immediately
+
+### Step 9: Choose Your Path (Onboarding)
+
+> **Screenshot**: The onboarding path selection screen showing three options: Bitcoin Node, Home Server, Full Sovereignty.
+
+The onboarding wizard guides you through setup:
+
+1. **Choose your path**:
+   - **Bitcoin Node**: Bitcoin Knots + LND + Mempool (focused)
+   - **Home Server**: Bitcoin + Home Assistant + File Manager (balanced)
+   - **Full Sovereignty**: Everything — Bitcoin, Lightning, Nostr, VPN, Cloud (maximum)
+
+2. **Create your identity**:
+   > **Screenshot**: DID creation screen showing the generated decentralized identifier.
+
+   - A DID (Decentralized Identifier) is generated for your node
+   - This is your sovereign digital identity — no third party needed
+
+3. **Backup your seed**:
+   > **Screenshot**: Seed phrase display with 12 words and a "I've saved this" checkbox.
+
+   - Write down or save your backup passphrase
+   - This is the only way to recover your node if hardware fails
+   - Store it securely offline
+
+4. **Verify your backup**:
+   > **Screenshot**: Verification screen asking to confirm specific words from the backup.
+
+   - Confirm you've saved your backup by entering requested words
+
+5. **Setup complete**:
+   > **Screenshot**: Completion screen with confetti animation and "Enter your node" button.
+
+   - Click to enter the dashboard
+
+---
+
+## Part 4: The Dashboard (Daily Use)
+
+### Step 10: Home Screen
+
+> **Screenshot**: The Archipelago dashboard with glass-card layout — system status, Bitcoin sync progress, quick actions.
+
+The home screen shows:
+- **System status**: CPU, RAM, disk usage, uptime
+- **Bitcoin sync progress**: Block height, peer count, sync percentage
+- **Quick actions**: Start/stop apps, check notifications
+- **Node identity**: Your DID and Nostr public key
+
+### Step 11: My Apps
+
+> **Screenshot**: The Apps page showing installed containers as glass cards — Bitcoin Knots (running), LND (running), Mempool (stopped).
+
+- View all installed applications
+- **Green dot**: Running
+- **Red dot**: Stopped
+- Click an app to see details, logs, and actions
+- Start/stop apps with one click
+
+### Step 12: App Details
+
+> **Screenshot**: Bitcoin Knots detail page showing sync status, peer count, block height, and action buttons.
+
+Each app detail page shows:
+- Container status and health
+- Live logs (scrollable)
+- Start / Stop / Restart buttons
+- Launch button (opens the app's own UI in a new tab)
+- Resource usage
+
+### Step 13: Marketplace
+
+> **Screenshot**: The Marketplace page with curated app cards — each showing name, description, and install button.
+
+- Browse available applications
+- Install with one click
+- Apps are verified containers with security hardening
+- Categories: Bitcoin, Lightning, Home, Nostr, Other
+
+### Step 14: Cloud (File Manager)
+
+> **Screenshot**: The Cloud page showing folders (Documents, Photos, Music) with breadcrumb navigation.
+
+- Browse files stored on your node
+- Upload and download files
+- Organized with breadcrumb navigation
+- Files are stored locally — not in the cloud
+
+### Step 15: Server Status
+
+> **Screenshot**: The Server page showing CPU/RAM/Disk gauges, Tor status, and network information.
+
+- Real-time system metrics
+- Tor connectivity status and .onion address
+- DNS configuration
+- VPN status
+- Federation peers (if configured)
+
+### Step 16: Web5 Identity
+
+> **Screenshot**: The Web5 page showing DID document, Nostr public key, and credential management.
+
+- View your decentralized identity (DID)
+- Manage verifiable credentials
+- Publish your identity to Nostr relays
+- Create and verify presentations
+
+### Step 17: Settings
+
+> **Screenshot**: The Settings page with sections for password, appearance, system update, and shutdown.
+
+- Change password
+- Configure TOTP two-factor authentication
+- Check for system updates
+- Restart or shutdown the server
+- Reset onboarding (for testing)
+
+---
+
+## Part 5: Advanced Operations
+
+### Accessing via Tor
+
+> **Screenshot**: Browser showing the .onion address in the Tor Browser URL bar.
+
+1. Install [Tor Browser](https://torproject.org)
+2. Find your .onion address in Settings > Server
+3. Access your node from anywhere in the world via Tor
+
+### Federation (Multi-Node)
+
+> **Screenshot**: Federation page showing connected peer nodes with status indicators.
+
+1. Generate an invite code from Server > Federation
+2. Share the code with a trusted peer
+3. They join using the code on their node
+4. Monitor peer status and deploy apps remotely
+
+### Hardware Wallet Integration
+
+> **Screenshot**: PSBT signing flow — creating a transaction, scanning QR with hardware wallet.
+
+1. Create a PSBT (Partially Signed Bitcoin Transaction) from Web5
+2. Transfer to your hardware wallet (QR code or file)
+3. Sign on the hardware wallet
+4. Import the signed PSBT back to finalize and broadcast
+
+### Controller / Gamepad Navigation
+
+Archipelago supports Xbox-style controller navigation throughout the UI.
+
+#### Global Controls
+
+| Button | Action |
+|--------|--------|
+| D-pad Up/Down | Navigate between elements |
+| D-pad Left/Right | Move between zones (sidebar ↔ content) |
+| A / Enter | Select / activate / enter container |
+| B / Escape | Go back / exit container / return to sidebar |
+
+#### Navigation Zones
+
+**Sidebar** (left column — always visible on desktop):
+- Up/Down = move between items (wraps), auto-navigates page links
+- Right = enter main content (first container, or first button on container-free pages)
+- Left = nothing
+
+**Nav Bar** (mode-switcher tabs at top of content — e.g. My Apps / App Store / Services):
+- Left/Right = move between tabs
+- Down = jump to first card/container below (remembers tab for Up return)
+- Up = nothing (Escape to sidebar)
+- Left from leftmost = sidebar
+
+**Container Grid** (card tiles — Apps, Discover, Network, Home):
+- Arrows = spatial navigation between cards
+- Enter = primary action (Install, Launch, or enter inner controls)
+- Escape = sidebar
+- Left from leftmost card = sidebar
+- Up from top row = return to remembered nav bar tab
+
+**Inside Container** (after Enter on a card — inner buttons/controls):
+- Arrows = move between inner controls
+- Escape = exit back to the card
+- Cannot leave via arrows — must Escape first
+
+**Text Inputs** (search bars, form fields):
+- Up/Down = exit field, navigate to nearest element
+- Enter = submit (clicks the next button)
+- Left/Right = cursor movement (exits field at edges)
+
+#### Per-Page Mapping
+
+**Home** (`/dashboard`)
+- Right from sidebar → first status card
+- D-pad navigates between status cards spatially
+- Enter on card → navigates to that section
+
+**My Apps** (`/dashboard/apps`)
+- Right from sidebar → first app card
+- D-pad navigates app card grid spatially
+- Enter on card → app details page
+- Enter on focused card with Launch button → launches app
+
+**App Store / Discover** (`/dashboard/discover`)
+- Right from sidebar → first featured card
+- D-pad navigates card grid (Sovereignty Stack + All Applications)
+- Down from nav tabs → first card below
+- Up from top card → returns to last-focused tab
+- Enter on card → app detail / install
+- Cards lift on hover/focus (same as My Apps)
+
+**Network** (`/dashboard/server`)
+- Right from sidebar → Quick Actions card
+- D-pad navigates between cards: Quick Actions → Local Network / Web3 → Network Interfaces / Tor Services
+- Enter on Quick Actions → enters inner buttons (Restart, Check Tor, View Logs)
+- Escape from inner buttons → back to card
+- All cards lift on hover/focus
+
+**Settings** (`/dashboard/settings`) — **Linear navigation, no containers**
+- Right from sidebar → first button (server name row)
+- D-pad Up/Down steps through ALL buttons/controls top-to-bottom:
+  1. Server Name / What's New
+  2. Copy DID
+  3. Copy Onion Address
+  4. Change Password
+  5. Enable/Disable 2FA
+  6. Logout
+  7. Choose Language
+  8. Login with Claude
+  9. AI Data Access toggles (each enable/disable row)
+  10. Manage Updates
+  11. Webhook URL input
+  12. Webhook Secret input
+  13. Container Crash / Update Available toggles
+  14. Disk Space Warning / Backup Complete toggles
+  15. Save Configuration / Send Test Webhook
+  16. Enable Beta Telemetry
+  17. Create Backup
+  18. Export Channel Backup
+  19. Network Diagnostics
+  20. Reboot
+  21. Factory Reset
+- Enter = activates the focused button/toggle
+- Escape / Left = sidebar
+
+**Mesh** (`/dashboard/mesh`)
+- Right from sidebar → Device status card (left column)
+- D-pad navigates between left-column containers (Device, Actions, Peers)
+- Enter on peer → opens chat, auto-focuses message input
+- Type message + Enter = send
+- Escape = close chat / back to sidebar
+
+**Cloud** (`/dashboard/cloud`)
+- Right from sidebar → first folder/file card
+- D-pad navigates file grid spatially
+- Enter = open folder / file details
+
+**Detail Pages** (app details, marketplace app details):
+- Escape / B = go back to previous page
+
+---
+
+## Part 6: Maintenance
+
+### Regular Tasks
+
+| Task | Frequency | How |
+|------|-----------|-----|
+| Check for updates | Weekly | Settings > System Update |
+| Review app health | Daily (glance) | Home screen status cards |
+| Backup | Monthly | Settings > Backup |
+| Check disk space | Monthly | Server status page |
+
+### Updating Archipelago
+
+1. Go to Settings > System Update
+2. Click "Check for Updates"
+3. If available, click "Install Update"
+4. The system restarts automatically — do not power off during update
+
+### Creating a Backup
+
+1. Go to Settings > Backup
+2. Enter a passphrase (remember this!)
+3. Click "Create Backup"
+4. Download the backup file and store it safely offline
+
+---
+
+## Quick Reference
+
+| Action | Where |
+|--------|-------|
+| Start/stop an app | My Apps > App Card > Start/Stop |
+| Install new app | Marketplace > Find App > Install |
+| Check system health | Home or Server page |
+| Change password | Settings > Security |
+| Enable 2FA | Settings > Security > TOTP |
+| View logs | My Apps > App > Logs |
+| Access via Tor | Settings > Server > Tor Address |
+| Restart server | Settings > System > Restart |
+| Create backup | Settings > Backup |