archy/QUICKSTART.md

# Archipelago - Quick Start Guide

Welcome to Archipelago! This guide will help you get started in minutes.

## 📥 Installation

### Step 1: Download
Download the latest release:
- **macOS**: `Archipelago-[version]-macOS.dmg`

### Step 2: Install Docker Desktop
Archipelago requires Docker Desktop to run containerized apps.

1. Download: https://www.docker.com/products/docker-desktop
2. Install and launch Docker Desktop
3. Wait for Docker to fully start (whale icon in menu bar)

### Step 3: Install Archipelago
1. Open the downloaded DMG file
2. Drag **Archipelago** to your **Applications** folder
3. Eject the DMG

### Step 4: First Launch
1. Open **Applications** folder
2. Right-click **Archipelago** → **Open** (first time only)
3. Click **Open** if you see a security warning
4. The app will start in the background

## 🚀 Getting Started

### Access the Dashboard
Open your web browser and go to:
```
http://localhost:8100
```

### First Login
**Default Credentials (Dev Mode)**:
- Username: `admin`
- Password: `password123`

⚠️ **Change this password immediately in production!**

## 🎯 Core Features

### 1. My Apps
View and manage all your containerized applications:
- Bitcoin Core (Full Node)
- LND (Lightning Network)
- BTCPay Server (Payments)
- Penpot (Design)
- Nextcloud (Cloud Storage)
- And more...

**To start an app**:
1. Navigate to **My Apps**
2. Click on any app card
3. Click **Start** if not already running
4. Click **Launch** to open the app's UI

### 2. Bitcoin Core
Your personal Bitcoin full node in regtest mode (no blockchain sync required for testing).

**Access**: http://localhost:18445

Features:
- Node status and sync progress
- Network information
- Block explorer
- Configuration settings

### 3. Lightning Network (LND)
Lightning Network Daemon for instant Bitcoin payments.

**Access**: http://localhost:8085

Features:
- Channel management
- Balance overview
- Payment routing
- Network graph

### 4. Cloud Storage
Manage your files by type (Documents, Photos, Videos, Music).

**Features**:
- Click "Open Nextcloud" to access full cloud interface
- Upload and organize files
- Share files securely
- Access from any device

### 5. Web5
Decentralized identity and data management.

**Coming soon**: DID wallet, DWN nodes, decentralized apps

## 📱 Common Tasks

### Starting All Containers
```bash
# From Terminal
cd /Applications/Archipelago.app/Contents/MacOS
./manage-docker.sh start
```

### Stopping All Containers
```bash
./manage-docker.sh stop
```

### Viewing Logs
```bash
./manage-docker.sh logs
# Or for specific service:
./manage-docker.sh logs bitcoin
```

### Checking Status
```bash
./manage-docker.sh status
```

## 🔧 Configuration

### Data Location
All data is stored in:
```
~/Library/Application Support/Archipelago/
├── data/     # Application data
└── logs/     # Log files
```

### Environment Variables
Edit configuration:
```bash
nano ~/Library/Application\ Support/Archipelago/.env
```

Key settings:
```bash
ARCHIPELAGO_PORT=8100           # Web UI port
ARCHIPELAGO_BACKEND_PORT=3030   # Backend API port
RUST_LOG=info                   # Log level (debug, info, warn)
```

### Docker Compose
The main Docker configuration is at:
```
/Applications/Archipelago.app/Contents/Resources/docker-compose.yml
```

## 🐛 Troubleshooting

### App Won't Open
**Problem**: "Archipelago is damaged and can't be opened"

**Solution**:
```bash
xattr -cr /Applications/Archipelago.app
```
Then try opening again.

### Docker Containers Won't Start
**Check Docker is running**:
```bash
docker info
```

**If Docker is not running**:
1. Open Docker Desktop
2. Wait for it to fully start
3. Try again

### Port Already in Use
**Error**: Port 8100 already in use

**Solution**:
```bash
# Find what's using the port
lsof -i :8100

# Kill the process or change Archipelago's port
nano ~/Library/Application\ Support/Archipelago/.env
# Change ARCHIPELAGO_PORT=8100 to another port
```

### Web UI Shows "Connection Failed"
**Check backend is running**:
```bash
# Check if backend process is running
ps aux | grep archipelago

# Check logs
tail -f ~/Library/Application\ Support/Archipelago/logs/archipelago.log
```

### Bitcoin Core UI Not Loading
1. Check if container is running: `./manage-docker.sh status`
2. Restart Bitcoin Core: `docker restart archy-bitcoin`
3. Check logs: `./manage-docker.sh logs bitcoin`

### Out of Disk Space
Docker images can be large. Clean up:
```bash
# Remove unused containers and images
docker system prune -a

# Check disk usage
docker system df
```

## 📊 System Requirements

### Minimum
- macOS 10.15 (Catalina)
- 8GB RAM
- 20GB free disk space
- Docker Desktop 23.0+

### Recommended
- macOS 12.0 (Monterey) or later
- 16GB RAM
- 50GB+ free disk space (for blockchain data)
- SSD storage
- Fast internet connection

## 🔐 Security

### Best Practices
1. **Change default password** immediately
2. **Enable firewall** in System Preferences
3. **Keep Docker updated** for security patches
4. **Backup data** regularly from `~/Library/Application Support/Archipelago/`
5. **Don't expose ports** to the internet without VPN/firewall

### Network Security
By default, all services are only accessible on localhost (127.0.0.1).

To access from other devices on your network (not recommended):
- Edit `docker-compose.yml`
- Change bind addresses from `127.0.0.1:PORT` to `0.0.0.0:PORT`
- Ensure firewall is properly configured

## 🆘 Getting Help

### Resources
- **Documentation**: `/Applications/Archipelago.app/Contents/Resources/docs/`
- **GitHub Issues**: https://github.com/[your-repo]/archipelago/issues
- **Community**: [Discord/Telegram link]

### Logs Location
```bash
# Application logs
~/Library/Application Support/Archipelago/logs/archipelago.log

# Docker logs
./manage-docker.sh logs
```

### Reporting Bugs
When reporting issues, include:
1. macOS version: `sw_vers`
2. Docker version: `docker --version`
3. Archipelago version: Check "About" in app
4. Error message or log excerpt
5. Steps to reproduce

## 🎓 Next Steps

### Learn More
- **Architecture**: Read `docs/architecture.md`
- **Building from Source**: See `BUILD_MACOS.md`
- **Contributing**: Check `CONTRIBUTING.md`

### Explore Apps
1. **Set up Bitcoin Core** for mainnet (requires blockchain sync)
2. **Create Lightning channels** with LND
3. **Install BTCPay Server** for accepting payments
4. **Design in Penpot** (open-source Figma alternative)
5. **Track fitness with Endurain**
6. **Store files in Nextcloud**

### Join the Community
- Share your setup
- Report bugs
- Request features
- Contribute code

---

**Welcome to the Archipelago!** 🏝️

Your sovereign personal server awaits.