fred/homelab-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
80debaf96858ccca761d9cb4410f3f8fe74c6d07
homelab-docs/infrastructure/BLUEBUBBLES-SETUP.md

7.5 KiB
Raw Blame History

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):

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:

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:

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:

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:

Status: Setup in progress

References

Installation Date: 2026-01-31 Installed By: Fred Last Verified: Pending initial setup

Reference in New Issue View Git Blame Copy Permalink