archy/docs/user-walkthrough.md

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 (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
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