# 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