BlueBubbles Server
  • Server Overview
  • Installation Guides
    • Standard Installation
    • Manual Setup
  • FAQ
  • Private API Setup
  • Supporting the Project
  • Licenses / Legal
  • Basic Guides
    • Basic Guides - Overview
    • Port Forwarding & Dynamic DNS
    • Prevent macOS from Sleeping
    • Migrating Servers
    • Multiple Users on the Same Mac
    • Autostart Server After Crash
  • Troubleshooting Guides
    • Troubleshooting Guides - Overview
    • BlueBubbles Server Cannot Access MacOS Contacts
    • Not Receiving Notifications or URL Changes on Android
    • Unable to Send Messages to International Contacts
    • BlueBubbles App is Taking Up Too Much Storage
    • Can't Send Messages from BlueBubbles
    • BlueBubbles Server Opens to a Blank White Screen
    • Slow Upload Speed When Connecting Over LAN
    • Restarting Your Server Without a Direct Connection
    • Fix FaceTime Features for Virtual Machines
  • Advanced Guides
    • Advanced Guides - Overview
    • Generating an SSL Certificate using CertBot
    • Disabling SIP on Unofficial Macs for the Private API
    • Registering a Phone Number with your iMessage Account
    • macOS Virtualization
      • Running a macOS VM
        • Deploying macOS in VMWare on Windows (Full Guide)
        • Enabling iMessage in a VM
        • External Guides
          • Big Sur VM on a Mac Device
          • Big Sur VM on Proxmox
          • Big Sur VM on AMD Windows
          • Big Sur VM on Intel Windows
          • Catalina VM on a Mac Device
          • Catalina VM on Proxmox
          • Catalina VM on Intel / AMD Windows
          • Catalina VM on Intel Windows
          • Monterey VM on AMD Windows
      • Running BlueBubbles in Docker-OSX
        • Configuring BlueBubbles as a Service
    • BYO Proxy Service Guides
      • Cloudflare with a Custom Domain
      • Caddy & DuckDNS
      • Nginx Proxy Manager
      • Nginx Manual Setup
      • Tailscale VPN Setup
  • Developer Guides
    • Developer Guides - Overview
    • Build Yourself / Contribution Guide
    • REST API & Webhooks
    • Simple Web Server for Webhooks
      • Python Web Server Example
Powered by GitBook
On this page
  • Server Installation
  • App Installation

Was this helpful?

Edit on GitHub
Export as PDF
  1. Installation Guides

Manual Setup

Set up BlueBubbles without signing into your Google account

PreviousInstallation GuidesNextSupporting the Project

Last updated 1 year ago

Was this helpful?

Server Installation

On the macOS device you'd like to use for the server, open the . Scroll to the bottom and download the .dmg file.

Locate the downloaded .dmg in your Downloads folder in Finder. Right click (or Ctrl + Left click) the .dmg file to Open the app. (Do not open the .dmg from the Downloads Center in the Dock!)

Apple disabled our Developer Account with no further explanation. As a result, the server app is now unsigned. The above process is required to install the unsigned app without visiting the security menus in System Preferences.

Drag the app icon to the applications folder when prompted. Right click (or Ctrl + Left click) the popup to Eject it. Finally, open the app from the applications folder, and you will be greeted with the welcome screen.

Proceed through the Intro, and Permissions steps, following the on-screen guide to enable accessibility and full disk access. Note that accessiblity is not required for BlueBubbles to function.

Once full disk access is enabled, proceed to the Notifications step. Switch to the Manual Setup tab to avoid signing in with Google.

The name of the project does not have to be BlueBubblesApp if you already have a project by that name.

  1. Click Create a Project and enter BlueBubblesApp as the name. Disable Google Analytics (why do you want Google spying on you?) and wait for the project to be created.

  2. In the tabs on the far left, click Build > Firestore Database.

  3. Next, Create database and press Next > Enable. You can change the database location if you are not based in North America so it is closer to you.

  4. If Cloud Firestore glitches and does not show you the database page, simply refresh the page.

  5. In the tabs near the top, click Rules

  6. Set the rule's condition from allow read, write: if false; to allow read, write: if true; (Change false to true) and click Publish.

  7. Click the gear cog in the top left and click Project Settings.

  8. In the tabs near the top, navigate to Service Accounts. Generate a new private key and save this locally. This will download file 1 / 2 needed for the manual setup.

  9. Next, navigate to the General tab.

  10. Scroll to the bottom of the page and click the Android icon to add an Android app. Set the package name to com.bluebubbles.messaging and leave the other fields blank.

  11. Click Register app, then Download google_services.json. This will download file 2 / 2 needed for the manual setup.

After getting the downloaded files, drag and drop them into the fields shown above.

Proceed to the Connection step.

Set a strong server password, and make sure to use the floppy disk icon to save it.

In most cases, Cloudflare is the proxy service you should use. If you experience any issues with it, please try the following:

  1. Cycle your wifi connection on the client device (not the server Mac)

  2. Restart the server app to get a new URL and repeat step 1 if necessary

  3. Set Cloudflare DNS (one.one.one.one) in your phone's Private DNS setting

If these fail, you can switch to Ngrok using the Proxy Service dropdown from the server settings. Ngrok may have increased outages and more rate limiting compared to Cloudflare.

Proceed to the Private API step.

Do not enable the Private API checkbox unless your requirements are passing and you have completed the setup.

Proceed to the Finish step. Here, you can customize any server settings to your liking, these are mostly cosmetic.

Be sure to visit any of our Basic or Advanced guides in the sidebar for even further configuration and customization possibilities!

You are now ready to download the app on your Android or PC!

App Installation

Open the app, making sure to grant all permissions and disable battery optimizations. On the server connection step, you can use the QR code button on the server homepage to quickly connect, or type your URL and password manually. Sync your messages, and you're ready to use BlueBubbles!

On your Mac, open the and login with your Google account. Create a Firebase account and generate google_services.json and firebase-adminsdk.json by following the below video or written tutorial.

The Private API setup (along with its requirements) is optional! If you would like to immediately set up the Private API, please follow .

Download and install the app for your desired device from the links on our .

Firebase Console
our guide
website
server GitHub
https://bluebubbles.app/install/manual-setup.mp4bluebubbles.app
Download the .dmg file in the Assets list
Welcome screen
Select Manual Setup
Connection Step