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
2. Onboarding Walkthrough
3. Dashboard Overview
4. Installing Apps
5. Managing Apps
6. Bitcoin Node
7. Lightning Network (LND)
8. Cloud Storage
9. Identity & Web5
10. Settings
11. Backup & Restore
12. Remote Access
13. 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 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 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 for technical details
• File issues at the project repository
• Join the community for support