archy/BUILD_MACOS.md

Archipelago macOS Production Build

Overview

This guide explains how to create a production-ready macOS application bundle (.app) and DMG installer for Archipelago Bitcoin Node OS.

Prerequisites

• macOS 10.15 (Catalina) or later
• Xcode Command Line Tools: xcode-select --install
• Rust toolchain: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
• Node.js 18+: brew install node
• Docker Desktop (for running containerized apps)

Quick Build

./build-macos-production.sh

This will:

1. Build the Rust backend in release mode
2. Build the Vue.js frontend for production
3. Create a macOS app bundle structure
4. Generate app metadata (Info.plist)
5. Create app icon from your logo
6. Package everything into a DMG installer

Build Output

The build creates:

• build/macos/Archipelago.app - macOS application bundle
• build/macos/Archipelago-[version]-macOS.dmg - DMG installer

Installation

For Testing

open build/macos/Archipelago.app

For System-Wide Installation

cp -R build/macos/Archipelago.app /Applications/

For Distribution

Share the DMG file: build/macos/Archipelago-[version]-macOS.dmg

Users can drag the app to their Applications folder.

App Bundle Structure

Archipelago.app/
├── Contents/
│   ├── Info.plist           # App metadata
│   ├── PkgInfo              # Package type
│   ├── MacOS/
│   │   ├── launch.sh        # Launch script
│   │   └── archipelago      # Rust backend binary
│   ├── Resources/
│   │   ├── AppIcon.icns     # App icon
│   │   ├── frontend/        # Vue.js production build
│   │   ├── docker-ui/       # Docker app UIs (Bitcoin Core, LND)
│   │   └── env.template     # Configuration template
│   └── Frameworks/          # (Reserved for future use)

Data Directories

The app stores data in standard macOS locations:

~/Library/Application Support/Archipelago/
├── data/              # Application data
└── logs/              # Log files

Configuration

On first run, the app uses default settings. To customize:

1. Edit the configuration:

   ~/Library/Application Support/Archipelago/.env
   

2. Available settings:

   • ARCHIPELAGO_PORT - Web UI port (default: 8100)
   • ARCHIPELAGO_BACKEND_PORT - Backend API port (default: 3030)
   • RUST_LOG - Log level (info, debug, trace)

Docker Integration

Archipelago requires Docker Desktop for running Bitcoin Core, LND, and other containerized apps.

First-Time Setup

1. Install Docker Desktop: https://www.docker.com/products/docker-desktop
2. Start Docker Desktop
3. Launch Archipelago
4. Open http://localhost:8100
5. Navigate to "My Apps" to start containers

Docker Compose File

The app uses the included docker-compose.yml for container orchestration:

• Bitcoin Core (regtest mode)
• LND (Lightning Network)
• BTCPay Server
• Mempool Explorer
• Penpot (Design)
• Nextcloud (Cloud Storage)
• And more...

Code Signing (Optional but Recommended)

For distribution outside the App Store, sign the app with your Developer ID:

# Sign the app
codesign --deep --force --verify --verbose \
  --sign "Developer ID Application: Your Name" \
  build/macos/Archipelago.app

# Verify signature
codesign --verify --verbose build/macos/Archipelago.app

Notarization (Required for macOS 10.15+)

To distribute on macOS Catalina and later:

# Create a zip for notarization
ditto -c -k --keepParent build/macos/Archipelago.app Archipelago.zip

# Submit for notarization (requires Apple Developer account)
xcrun notarytool submit Archipelago.zip \
  --apple-id "your@email.com" \
  --team-id "TEAMID" \
  --password "app-specific-password" \
  --wait

# Staple the notarization ticket
xcrun stapler staple build/macos/Archipelago.app

Troubleshooting

App won't open - "damaged or can't be verified"

This happens with unsigned apps. Users can:

1. Right-click → Open (first time only)
2. Or remove quarantine: xattr -cr /Applications/Archipelago.app

Backend fails to start

Check logs: ~/Library/Application Support/Archipelago/logs/archipelago.log

Docker containers won't start

Ensure Docker Desktop is running: docker info

Port conflicts

Edit port in ~/Library/Application Support/Archipelago/.env

Building for Distribution

Universal Binary (Intel + Apple Silicon)

# Build for both architectures
rustup target add x86_64-apple-darwin
rustup target add aarch64-apple-darwin

# Build Intel
cd core
cargo build --release --target x86_64-apple-darwin

# Build Apple Silicon
cargo build --release --target aarch64-apple-darwin

# Create universal binary
lipo -create \
  target/x86_64-apple-darwin/release/archipelago \
  target/aarch64-apple-darwin/release/archipelago \
  -output target/release/archipelago

# Then run build script
cd ..
./build-macos-production.sh

Automated Release Pipeline

For CI/CD (GitHub Actions, etc.):

- name: Build macOS Release
  run: |
    ./build-macos-production.sh
    
- name: Upload DMG
  uses: actions/upload-artifact@v3
  with:
    name: Archipelago-macOS
    path: build/macos/*.dmg

Size Optimization

The production build is optimized:

• Rust backend: Strip symbols, LTO optimization
• Frontend: Minified, tree-shaken, compressed
• Total size: ~50-100MB (without Docker images)

To further reduce size:

cd core
cargo build --release
strip target/release/archipelago  # Remove debug symbols

Security Considerations

1. Code Signing: Required for Gatekeeper
2. Notarization: Required for macOS 10.15+
3. Sandboxing: Consider for Mac App Store
4. Hardened Runtime: Enable for notarization
5. Secrets: Never bundle private keys or passwords

Support

For issues or questions:

• GitHub: https://github.com/archipelago/archipelago
• Docs: See /docs directory

---

Built with ❤️ by the Archipelago team