lfg2025/archy
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases 33 Wiki Activity
Files
6a90cf9a13a5aebd2725aec324cd69c4b91a2ad3
archy/docs/user-walkthrough.md
Dorian 13f13346a3 docs: add user walkthrough with screenshot placeholders (FINALDOC-02) 
Complete user flow documentation from hardware prep through daily use.
6 parts: hardware, installation, onboarding, dashboard, advanced ops,
and maintenance. Ready for screenshot capture and video production.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-11 17:21:40 +00:00

9.6 KiB
Raw Blame History

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

Screenshot: Dashboard with visible focus indicators showing controller navigation in action.

Archipelago supports Xbox-style controller navigation:

  • D-pad / Arrow keys: Navigate between elements
  • A / Enter: Select / activate
  • B / Escape: Go back
  • Bumpers: Switch between pages
  • Focus indicators show the current selection

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
Reference in New Issue View Git Blame Copy Permalink