Update README and configuration for macOS support
- Revamped README.md to enhance clarity and detail on features, installation, and system requirements for Archipelago. - Added macOS-specific configuration in `config.rs` to detect when running from a macOS app bundle, adjusting data directory paths accordingly. - Introduced a new production build script in `package.json` for optimized deployment of the Neode UI.
This commit is contained in:
Dorian
+293
@@ -0,0 +1,293 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user