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

```bash
./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
```bash
open build/macos/Archipelago.app
```

### For System-Wide Installation
```bash
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:
   ```bash
   ~/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:

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

```bash
# 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)

```bash
# 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.):

```yaml
- 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:
```bash
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