Initial infrastructure documentation - comprehensive homelab reference
This commit is contained in:
Funky (OpenClaw)
267
infrastructure/BLUEBUBBLES-SETUP.md
Normal file
267
infrastructure/BLUEBUBBLES-SETUP.md
Normal file
@@ -0,0 +1,267 @@
|
||||
# BlueBubbles Server Setup Guide
|
||||
|
||||
**Last Updated:** 2026-01-31
|
||||
**Service:** BlueBubbles iMessage Server
|
||||
**Host:** Fred's iMac (10.0.10.11 / 10.0.10.144)
|
||||
**Version:** v1.9.9
|
||||
**Status:** In Setup
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
BlueBubbles allows you to access iMessage on Android, Windows, and Linux devices by running a server on your Mac that forwards messages via WebSocket.
|
||||
|
||||
**Architecture:**
|
||||
```
|
||||
iMessage on iMac (10.0.10.11)
|
||||
↓
|
||||
BlueBubbles Server (Port 1234)
|
||||
↓
|
||||
Caddy VPS Proxy (bluebubbles.nianticbooks.com)
|
||||
↓
|
||||
BlueBubbles Clients (Android/Web/Desktop)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Installation Steps
|
||||
|
||||
### Step 1: Download BlueBubbles Server
|
||||
|
||||
**IMPORTANT:** You need to download this via Safari on your iMac due to GitHub's download mechanism.
|
||||
|
||||
On your iMac:
|
||||
|
||||
1. Open Safari and navigate to:
|
||||
```
|
||||
https://github.com/BlueBubblesApp/bluebubbles-server/releases/tag/v1.9.9
|
||||
```
|
||||
|
||||
2. Scroll down to "Assets" section
|
||||
3. Click on **`BlueBubbles-v1.9.9.dmg`** (NOT the `.zip` file)
|
||||
4. The file will download to your ~/Downloads folder
|
||||
|
||||
### Step 2: Install BlueBubbles Server
|
||||
|
||||
1. Open the downloaded `.dmg` file
|
||||
2. Drag BlueBubbles to your Applications folder
|
||||
3. Open BlueBubbles from Applications
|
||||
4. If you get a security warning:
|
||||
- Go to System Settings → Privacy & Security
|
||||
- Click "Open Anyway" for BlueBubbles
|
||||
|
||||
### Step 3: Initial Configuration
|
||||
|
||||
When BlueBubbles opens for the first time:
|
||||
|
||||
1. **Grant Permissions:**
|
||||
- Full Disk Access (required to read iMessage database)
|
||||
- Accessibility (required for Private API features)
|
||||
- Go to: System Settings → Privacy & Security → Full Disk Access
|
||||
- Add BlueBubbles and enable it
|
||||
|
||||
2. **Server Settings:**
|
||||
- **Port:** 1234 (default, or choose your own)
|
||||
- **Password:** Create a strong password (save it securely)
|
||||
- **Server Name:** "Fred's BlueBubbles" (or any name you prefer)
|
||||
|
||||
3. **Enable Private API** (Recommended):
|
||||
- This enables advanced features like:
|
||||
- Typing indicators
|
||||
- Read receipts
|
||||
- Message reactions
|
||||
- Send messages as specific accounts
|
||||
- Toggle "Enable Private API" in settings
|
||||
- Follow the on-screen instructions to install the helper
|
||||
|
||||
4. **Auto-Start Settings:**
|
||||
- ✅ Enable "Start server on login"
|
||||
- ✅ Enable "Start minimized"
|
||||
- This ensures BlueBubbles runs automatically
|
||||
|
||||
### Step 4: Configure Firewall (if enabled)
|
||||
|
||||
If macOS Firewall is enabled on your iMac:
|
||||
|
||||
1. Go to System Settings → Network → Firewall
|
||||
2. Click "Options..."
|
||||
3. Add BlueBubbles to allowed apps
|
||||
4. OR allow incoming connections on port 1234
|
||||
|
||||
### Step 5: Test Local Access
|
||||
|
||||
Before setting up external access, verify local functionality:
|
||||
|
||||
1. Note your server URL shown in BlueBubbles (should be like `http://10.0.10.11:1234`)
|
||||
2. Note your password
|
||||
3. Install BlueBubbles client on your phone/another device
|
||||
4. Connect using:
|
||||
- **Server URL:** `http://10.0.10.11:1234`
|
||||
- **Password:** [Your password]
|
||||
5. Verify you can see your messages
|
||||
|
||||
---
|
||||
|
||||
## External Access Setup (via Caddy VPS)
|
||||
|
||||
Once local access works, we'll set up external access via your VPS.
|
||||
|
||||
### Option 1: Use BlueBubbles Built-in Proxy (Easiest)
|
||||
|
||||
BlueBubbles includes built-in support for Cloudflare Tunnel, Ngrok, and Zrok:
|
||||
|
||||
1. In BlueBubbles settings, go to "Proxy Service"
|
||||
2. Choose one of the free options:
|
||||
- **Cloudflare Tunnel** (recommended - free, reliable)
|
||||
- **Zrok** (free, open source)
|
||||
- **Ngrok** (free tier available)
|
||||
3. Follow the on-screen setup for your chosen service
|
||||
4. Use the generated URL for remote connections
|
||||
|
||||
### Option 2: Use Your Caddy VPS (More Control)
|
||||
|
||||
Add to your Caddyfile on VPS (66.63.182.168):
|
||||
|
||||
```caddyfile
|
||||
bluebubbles.nianticbooks.com {
|
||||
reverse_proxy 10.0.10.11:1234 {
|
||||
header_up X-Forwarded-Host {host}
|
||||
header_up X-Forwarded-Proto {scheme}
|
||||
header_up X-Real-IP {remote_host}
|
||||
header_up X-Forwarded-For {remote_host}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then reload Caddy:
|
||||
```bash
|
||||
ssh fred@66.63.182.168
|
||||
sudo systemctl reload caddy
|
||||
```
|
||||
|
||||
**Client Connection:**
|
||||
- **Server URL:** `https://bluebubbles.nianticbooks.com`
|
||||
- **Password:** [Your password]
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Use HTTPS:** Always use HTTPS for external connections (Caddy handles this automatically)
|
||||
2. **Strong Password:** Use a unique, strong password for BlueBubbles
|
||||
3. **Keep iMac Secure:** Since it has access to all your messages:
|
||||
- Enable FileVault disk encryption
|
||||
- Use a strong user password
|
||||
- Keep macOS updated
|
||||
4. **Network Security:** Your iMac is already on static IP 10.0.10.11, which is in the static range
|
||||
|
||||
---
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Keep BlueBubbles Running
|
||||
|
||||
BlueBubbles needs to run 24/7 to relay messages. To ensure it stays running:
|
||||
|
||||
1. Set iMac to never sleep:
|
||||
- System Settings → Energy Saver → Prevent automatic sleeping
|
||||
- OR: Use "caffeinate" command to keep it awake
|
||||
|
||||
2. Enable "Start server on login" in BlueBubbles settings
|
||||
|
||||
3. Optionally: Set up monitoring in Uptime Kuma (10.0.10.26)
|
||||
|
||||
### Updates
|
||||
|
||||
Check for updates periodically:
|
||||
- BlueBubbles → Settings → Check for Updates
|
||||
- Or visit: https://github.com/BlueBubblesApp/bluebubbles-server/releases
|
||||
|
||||
### Logs
|
||||
|
||||
If you encounter issues:
|
||||
- BlueBubbles → Settings → Logs
|
||||
- Logs are stored in: `~/Library/Application Support/bluebubbles-server/`
|
||||
|
||||
---
|
||||
|
||||
## Client Apps
|
||||
|
||||
Download BlueBubbles clients for your devices:
|
||||
|
||||
- **Android:** https://play.google.com/store/apps/details?id=com.bluebubbles.messaging
|
||||
- **Web:** https://bluebubbles.app/web
|
||||
- **Desktop (Windows/Linux):** https://github.com/BlueBubblesApp/bluebubbles-app/releases
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Messages not syncing
|
||||
- Verify Full Disk Access is granted
|
||||
- Check iMessage is signed in and working on iMac
|
||||
- Restart BlueBubbles server
|
||||
|
||||
### Can't connect remotely
|
||||
- Verify local connection works first (http://10.0.10.11:1234)
|
||||
- Check Caddy configuration and reload
|
||||
- Verify WireGuard tunnel is up
|
||||
- Check firewall settings on iMac
|
||||
|
||||
### Private API not working
|
||||
- Ensure SIP (System Integrity Protection) is not blocking it
|
||||
- Reinstall Private API helper from BlueBubbles settings
|
||||
- Check macOS version compatibility
|
||||
|
||||
### iMac goes to sleep
|
||||
- Disable sleep in Energy Saver settings
|
||||
- Check "Prevent automatic sleeping when display is off"
|
||||
- Use "caffeinate" command to prevent sleep
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
After completing this setup:
|
||||
|
||||
1. ✅ Test local connection
|
||||
2. ✅ Set up external access (choose Option 1 or 2)
|
||||
3. ✅ Install client apps on your devices
|
||||
4. ✅ Test sending/receiving messages remotely
|
||||
5. ⬜ Set up monitoring in Uptime Kuma (optional)
|
||||
6. ⬜ Document final configuration in SERVICES.md
|
||||
|
||||
---
|
||||
|
||||
## Service Information
|
||||
|
||||
**Service Details:**
|
||||
- **Host:** Fred's iMac (Late 2013, 3.2GHz i5, 24GB RAM, macOS Sequoia)
|
||||
- **IP Address (Ethernet):** 10.0.10.11 (configured, cable not connected)
|
||||
- **IP Address (Wi-Fi):** 10.0.10.144 (currently active)
|
||||
- **Port:** 1234 (default)
|
||||
- **Version:** 1.9.9
|
||||
- **Auto-Start:** Enabled
|
||||
- **Private API:** Enabled (recommended)
|
||||
|
||||
**Public Access:**
|
||||
- **Option 1:** Built-in proxy (Cloudflare/Ngrok/Zrok)
|
||||
- **Option 2:** https://bluebubbles.nianticbooks.com (via Caddy VPS)
|
||||
|
||||
**Status:** Setup in progress
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- GitHub: https://github.com/BlueBubblesApp/bluebubbles-server
|
||||
- Documentation: https://bluebubbles.app/faq/
|
||||
- Web Client: https://bluebubbles.app/web
|
||||
- Community: https://discord.gg/bluebubbles
|
||||
|
||||
---
|
||||
|
||||
**Installation Date:** 2026-01-31
|
||||
**Installed By:** Fred
|
||||
**Last Verified:** Pending initial setup
|
||||
Reference in New Issue
Block a user