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
+239
@@ -0,0 +1,239 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user