archy/docs/user-guide.md

# Archipelago User Guide

Welcome to Archipelago — your personal server for a sovereign digital life. This guide walks you through everything from first boot to daily usage.

## Table of Contents

1. [First-Time Setup](#first-time-setup)
2. [Onboarding Walkthrough](#onboarding-walkthrough)
3. [Dashboard Overview](#dashboard-overview)
4. [Installing Apps](#installing-apps)
5. [Managing Apps](#managing-apps)
6. [Bitcoin Node](#bitcoin-node)
7. [Lightning Network (LND)](#lightning-network-lnd)
8. [Cloud Storage](#cloud-storage)
9. [Identity & Web5](#identity--web5)
10. [Settings](#settings)
11. [Backup & Restore](#backup--restore)
12. [Remote Access](#remote-access)
13. [Troubleshooting](#troubleshooting)

---

## First-Time Setup

### What You Need

- A dedicated computer (Intel/AMD x86_64 or ARM64)
- 16 GB RAM minimum (32 GB recommended)
- 500 GB+ SSD/NVMe storage
- Ethernet connection to your home router
- A USB drive (8 GB+) for the installer

### Flashing the Installer

1. Download the latest Archipelago ISO from the releases page
2. Flash the ISO to a USB drive using [balenaEtcher](https://etcher.balena.io/) or `dd`
3. Insert the USB into your target machine and boot from it
4. The auto-installer partitions your disk, installs Debian 12, and sets up all Archipelago services
5. When complete, the installer prompts you to remove the USB and reboot

### Finding Your Server

After reboot, Archipelago starts automatically. Find your server on your local network:

- **Default address**: `http://archipelago.local` (if mDNS works on your network)
- **IP address**: Check your router's DHCP client list for the new device
- **Direct**: Connect a monitor — the IP is displayed on the console login screen

Open your browser and navigate to the server address. You should see the Archipelago welcome screen.

---

## Onboarding Walkthrough

On first visit, Archipelago guides you through a 7-step onboarding process.

### Step 1: Welcome Screen

A cinematic intro video plays. Click **"Begin"** to start setup.

### Step 2: Create Admin Password

Set your admin password. This password protects:
- The web interface login
- SSH access to your server
- Encrypted secrets on disk

**Requirements**: Minimum 8 characters. Choose something strong — this protects your entire server.

### Step 3: Choose Your Path

Select the sovereign use case that interests you most:
- **Self Sovereignty** — Own your data, identity, and digital life
- **Community Commerce** — Peer-to-peer commerce on Bitcoin
- **Sovereign Projects** — Collaborative workspace without third parties
- **Data Transmitter** — Run relays and network services
- **Hoster** — Monetize hosting capacity
- **Sovereign AI** — Run AI models locally, no surveillance

This is informational — all features are available regardless of your choice.

### Step 4: Setup Type

Choose **Fresh Start** for a new installation. (Restore from backup and connect to existing server are coming in future releases.)

### Step 5: Generate Your Identity (DID)

Archipelago generates a Decentralized Identifier (DID) for you. This is your sovereign digital identity — it proves you are you without any company in the middle.

- Your DID is displayed on screen — copy it if you like
- This identity is stored locally on your server
- It's used for passwordless authentication and Web5 features

Wait for the server health check to complete (1–3 minutes on first boot as services start up).

### Step 6: Name Your Identity

Give your identity a name (e.g., "Personal", "Business") and choose its purpose. This is optional and can be changed later.

### Step 7: Create a Backup

**Important**: Set a passphrase and download your identity backup file (`archipelago-did-backup.json`). Store this file securely — it's the only way to recover your identity if your server is lost.

### Done

After completing onboarding, you're taken to the Dashboard.

---

## Dashboard Overview

The Dashboard is your home screen with two tabs:

### Dashboard Tab

Quick overview cards showing:

- **My Apps** — How many apps are installed and running. Quick links to browse the store or manage apps.
- **Cloud** — Storage usage and folder count. Access your files.
- **Server** — Connection status and system health.
- **Web5** — DID status, wallet connection, and Nostr relay count.

### Setup Tab

Goal-based guided setup cards for first-time users. These walk you through installing and configuring recommended apps step by step.

---

## Installing Apps

### From the App Store

1. Navigate to **App Store** from the sidebar (desktop) or bottom bar (mobile)
2. Browse by category (Finance, Storage, Communication, Network, etc.) or search by name
3. Click an app to see its details
4. Click **Install**

### Installation Progress

When you install an app, a progress banner appears at the top of the App Store showing:
- Download progress (percentage and MB downloaded)
- Current status (Downloading, Installing, Starting)

Most apps take 1–5 minutes to install depending on image size and network speed.

### Dependency Resolution

Some apps require others to be running first:
- **Electrs** requires Bitcoin Knots
- **LND** requires Bitcoin Knots
- **Mempool** requires Bitcoin Knots + Electrs
- **BTCPay Server** requires Bitcoin Knots

The App Store shows dependency requirements and offers to install them automatically.

### Available Apps

| App | Category | Description |
|-----|----------|-------------|
| Bitcoin Knots | Finance | Full Bitcoin node with enhanced features |
| Electrs | Finance | Electrum server for wallet connectivity |
| LND | Finance | Lightning Network node for instant payments |
| BTCPay Server | Finance | Self-hosted payment processor |
| Mempool | Finance | Bitcoin blockchain explorer |
| Fedimint | Finance | Federated e-cash and community banking |
| File Browser | Storage | Web-based file manager |
| Immich | Storage | Photo and video management (Google Photos alternative) |
| PhotoPrism | Storage | AI-powered photo organizer |
| Penpot | Productivity | Open-source design tool (Figma alternative) |
| SearXNG | Privacy | Privacy-respecting metasearch engine |
| Ollama | AI | Run large language models locally |
| Nostr Relay | Network | Decentralized social protocol relay |
| Nginx Proxy Manager | Network | Reverse proxy with SSL management |
| Home Assistant | IoT | Smart home automation |
| Tailscale | Network | Zero-config VPN for remote access |

---

## Managing Apps

### My Apps View

Navigate to **My Apps** to see all installed applications in a grid view. Each card shows:
- App icon and name
- Status badge (Running, Stopped, Installing)
- Version number

### App Actions

Click an app to open its details page. Available actions:

- **Launch** — Open the app's web interface
- **Start** — Start a stopped app
- **Stop** — Stop a running app
- **Restart** — Restart the app
- **Uninstall** — Remove the app and its container (data volumes are preserved)

### App Interfaces

Most apps open in an embedded view within Archipelago. Some apps (BTCPay Server, Home Assistant) open in a new browser tab due to security restrictions.

---

## Bitcoin Node

### First-Time Bitcoin Setup

1. Install **Bitcoin Knots** from the App Store
2. The node begins syncing the blockchain automatically
3. Initial sync takes 1–7 days depending on your hardware and connection
4. Monitor sync progress by launching the Bitcoin Knots interface

### What Bitcoin Knots Provides

- Full validation of all Bitcoin transactions
- Privacy — no third party sees your wallet queries
- Foundation for Lightning (LND), Electrs, Mempool, and BTCPay

### Bitcoin Data Location

Bitcoin blockchain data is stored at `/var/lib/archipelago/bitcoin-knots/` on the server. Plan for 600+ GB of storage.

---

## Lightning Network (LND)

### Setup

1. Ensure Bitcoin Knots is installed and running
2. Install **LND** from the App Store
3. LND connects to your Bitcoin node automatically

### Managing Channels

Navigate to **My Apps → LND → Channels** to:
- View open channels and their balances
- Open new channels to peers
- Close existing channels

### Integration with BTCPay

When both LND and BTCPay Server are installed, BTCPay automatically detects LND and enables Lightning payments. No manual configuration needed.

---

## Cloud Storage

### File Browser

The built-in File Browser gives you web-based access to your server's files.

1. Navigate to **Cloud** from the sidebar
2. Click **File Browser** to open it
3. Upload, download, create folders, and manage files

### Photo Management (Immich)

For photo and video management similar to Google Photos:

1. Install **Immich** from the App Store
2. Access it from the Cloud section
3. Upload photos/videos or use the Immich mobile app to auto-backup your phone

### Storage Location

All cloud data is stored under `/var/lib/archipelago/` on your server's disk.

---

## Identity & Web5

### Your Decentralized Identifier (DID)

Your DID is a globally unique identifier that you control. Navigate to **Web5** to see:

- Your DID string (copy it to share)
- Wallet connection status
- Connected Nostr relays

### Nostr Relay

If you've installed the Nostr Relay, it runs locally on your server. You can use it with any Nostr client by adding your server's relay URL.

### DID Features (Coming Soon)

- Verifiable credentials
- Passwordless authentication to other services
- Data portability between servers

---

## Settings

Navigate to **Settings** from the sidebar.

### Account Information

- **Server Name** — Your server's display name
- **Version** — Current Archipelago version
- **DID** — Your Decentralized Identifier (with copy button)
- **Tor Address** — Your .onion address for Tor access (with copy button)

### Change Password

1. Click **Change Password**
2. Enter your current password
3. Enter and confirm your new password (12+ characters, must include uppercase, lowercase, digit, and special character)
4. All other active sessions are invalidated after password change

### Two-Factor Authentication (2FA)

1. Click **Enable 2FA** in Settings
2. Scan the QR code with your authenticator app (Google Authenticator, Authy, etc.)
3. Enter the 6-digit code to verify
4. Save your backup codes securely — they're the only way to log in if you lose your authenticator

### Logout

Click **Logout** to end your session. You'll be redirected to the login screen.

---

## Backup & Restore

### Identity Backup

During onboarding, you created an identity backup file. To create a new one:

1. Go to **Settings**
2. Look for backup options (identity backup is tied to your DID)

### App Data

App data is stored in `/var/lib/archipelago/{app-id}/` on the server. To back up:

1. Use File Browser to download important files
2. Or SSH into the server and use standard backup tools (rsync, tar)

### Full System Recovery

If your server fails:

1. Flash a new USB installer and install on replacement hardware
2. During onboarding, choose **Restore from Backup** (when available)
3. Upload your `archipelago-did-backup.json` file
4. Re-install your apps from the App Store

---

## Remote Access

### Local Network

Your Archipelago server is accessible on your home network at its IP address or `http://archipelago.local`.

### Tor (Built-in)

Every Archipelago server has a Tor hidden service. Your `.onion` address is shown in Settings. Access it via Tor Browser from anywhere in the world — no port forwarding required.

### Tailscale (Recommended)

For easy, secure remote access without Tor:

1. Install **Tailscale** from the App Store
2. Launch it and sign in with your Tailscale account
3. Install Tailscale on your phone/laptop
4. Access your server from anywhere via its Tailscale IP

See [Tailscale Setup Guide](USER-GUIDE-TAILSCALE.md) for detailed instructions.

---

## Troubleshooting

### Can't Find Server on Network

- Ensure the server is powered on and connected to your router via Ethernet
- Check your router's DHCP client list for the server's IP
- Try `http://archipelago.local` (requires mDNS support)
- Connect a monitor to see the IP displayed on the console

### Login Issues

- **Forgot password**: Connect a monitor and keyboard. Log in at the console and run the password reset tool
- **2FA locked out**: Use your backup codes on the login screen (click "Use backup code")
- **Session expired**: Sessions expire after 24 hours of inactivity. Simply log in again.

### App Won't Start

- Check if dependent apps are running (e.g., Bitcoin Knots must run before Electrs)
- Try stopping and starting the app again
- Check app logs in **My Apps → [App] → Logs**
- Restart the Archipelago service: SSH in and run `sudo systemctl restart archipelago`

### Bitcoin Node Sync Issues

- Initial sync can take several days — this is normal
- Ensure your server has a reliable internet connection
- Check available disk space: Bitcoin needs 600+ GB

### WebSocket Disconnected

The UI shows a "Reconnecting..." banner if the WebSocket connection drops.
- This auto-recovers within 30 seconds
- If persistent, check that the backend service is running: `sudo systemctl status archipelago`
- Hard refresh the browser (Ctrl+Shift+R)

### Server Unresponsive

If the web UI is unreachable:

1. SSH into the server: `ssh archipelago@<your-ip>`
2. Check service status: `sudo systemctl status archipelago`
3. Restart if needed: `sudo systemctl restart archipelago`
4. Check system resources: `free -h` (RAM), `df -h` (disk)

### Getting Help

- Check the [Architecture Guide](architecture.md) for technical details
- File issues at the project repository
- Join the community for support