268 lines
7.5 KiB
Markdown
268 lines
7.5 KiB
Markdown
# 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
|