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

docs: add user walkthrough with screenshot placeholders (FINALDOC-02)

Browse Source 
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>
This commit is contained in:
Dorian
2026-03-11 17:21:40 +00:00
parent 2b19ca9641
commit 1f178a2dcb
2 changed files with 301 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

300
docs/user-walkthrough.md Normal file
View File

@@ -0,0 +1,300 @@
# 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
> **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 |