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

# From Terminal
cd /Applications/Archipelago.app/Contents/MacOS
./manage-docker.sh start

Stopping All Containers

./manage-docker.sh stop

Viewing Logs

./manage-docker.sh logs
# Or for specific service:
./manage-docker.sh logs bitcoin

Checking Status

./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:

nano ~/Library/Application\ Support/Archipelago/.env

Key settings:

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:

xattr -cr /Applications/Archipelago.app

Then try opening again.

Docker Containers Won't Start

Check Docker is running:

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:

# 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:

# 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:

# 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

# 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.