This guide will show you how to setup the BlueBubbles Docker container to run as a service on your Linux host. This is to make sure that the host starts up when your Linux host restarts.
If you do not have a physical Mac at your disposal and if you already have a Linux home server, it is relatively easy to turn BlueBubbles into a systemd service which you can configure to run at startup. This way, when your home server starts or reboots, it BlueBubbles automatically starts up.
BlueBubbles does have to be initially configured manually, including a full install of a macOS VM. However, using Docker-OSX makes this configuration much easier. If you are not already running BlueBubbles in a Docker-OSX container, first follow our guide on Configuring BlueBubbles in a container with Docker-OSX.
Once you are done configuring Docker-OSX and your BlueBubbles install:
Enable auto-login. This will make the boot faster and allow the BlueBubbles server to start automatically.
In your BlueBubbles server settings, enable "Startup with MacOS".
If using the Private API, ensure that MacForce launches at start:
MacForge Preferences > "General" tab > Check "Launch MacForce at Login"
Create a new systemd service:
2. Enter the following:
It's recommended that you replace the value of ExecStart with the script you made in Step 11 of the Configuring BlueBubbles in a container with Docker-OSX guide. If you do choose to paste the above code block into your new systemd service file, you will at least need to replace $PWD (in the -v options) with the full path to your Docker OSX virtual disks.
Alternatively, it is possible to point to the script file you saved. In that case, replace the ExecStart line with this instead:
NOTE: If using podman, replace docker.service with podman.service and the docker run command with podman run.
3. Reload the systemd daemons:
4. Enable the service to start it at boot, and activate it now:
This tutorial will show you how you can setup BlueBubbles in a Docker container, within a Linux host.
This guide is a contribution by @JustBen on our Discord
This guide is not for beginners. However, these steps should make it relatively easy to get up and running with a macOS Docker container running BlueBubbles on a Linux host. Before starting, you should familiarize yourself with the Linux CLI and be at least familiar with containerization and Docker (or Podman).
This guide is provided with no guarantees or warranty. If you encounter any problems, the community may be able to provide help in the Discord (linked in the header of this page), but we cannot guarantee that this will work for every configuration.
This guide has only been tested with MacOS Ventura, though it should work with only minor modifications for older versions.
This guide will walk you through setting up BlueBubbles on a macOS VM running in a Docker-OSX container. With the given configuration, your container will be accessible by VNC on port 5999.
You must have all of these already setup/installed in order to continue with the guide.
A Linux host
Comfort with bash
Packages:
docker (or podman)
docker-compose (or podman-compose)
tigervnc (or another vncviewer)
qemu
All dependencies outlined by Docker-OSX in its Initial Setup documentation
As noted in the link above, your system must support virtualization. The Docker-OSX documentation has steps on how to configure and verify that virtualization is supported and enabled on your system.
Create a directory for all the container resources
Create a virtual disk:
3. Run:
This will take a while because it's downloading the image for Docker-OSX and generating a unique serial number and bootdisk for your mac VM.
You may see a handful of errors particularly related to ALSA. These can be safely ignored.
NOTE: If using Podman, you can add --rmi to also remove the image after setup. However, this flag can be annoying if you need to start/stop this step repeatedly to troubleshoot because it will re-download the image every time NOTE: If using Podman as a non-root user, the additional flag --network slirp4netns:port_handler=slirp4netns must be added.
4. With your vnc viewer, open a connection to your IP on port 5999. If you're using tigervnc and running this on the same phost, you can use vncviewer localhost:5999. The password will be vncpass unless you changed it in the command.
5. If presented with a boot loader (a black screen with some icons in the center), select the option MacOS Base System to boot into the recover/install menu.
6. Before installing, you have to format the drive with APFS for a macOS install. Go into Disk Utility and find your drive. Click "Erase". Fill in the name for the drive that you want, then leave the rest as defaults and click "Erase". Close out of Disk Utility.
NOTE: On Ventura, you may have to use "MacOS extended (Journaled)" instead of APFS. See this GitHub issue for more information.
7. Click on "reinstall macOS" and install macOS as normal.
8. Once you're on your desktop, test sending an iMessage to yourself. If it does not succeed, it's likely best to restart from the beginning, though our Discord community may be able to help.
9. Before shutting down your VM, run this in a new terminal with the same user:
This copies the generated bootdisk and serial number information out of the container and saves it as bootdisk.qcow2 so it can be used for all your future boots.
10. Shutdown your VM then take down the container.
The container and image will automatically be removed from your system (to keep things clean) because of the --rm and --rmi options we passed above.
11. Save this into a file (e.g. start-bluebubbles.sh) and make sure you have execute permissions to run it (chmod +x start-bluebubbles.sh).
This new docker run command should cut down on boot time and general overhead.
As before, errors related to ALSA can be safely ignored.
It is HIGHLY RECOMMENDED that you replace $PWD in the above command (after both -v flags) with an absolute path. For example, replace $PWD/maindisk.qcow2:/image with /home/yourname/bluebubbles/maindisk.qcow2:/image. This allows you to more easily run this script from any working directory (as you may want to do with a systemd service file).
To change the VNC password, change data=vncpass to data=<yourpassword> in the EXTRA environment variable.
NOTE: As before, if using Podman as a non-root user, the additional flag --network slirp4netns:port_handler=slirp4netns must be added.
12. Start up the container again (by running the script file you made in step 11). It might take a little while the first time as it pulls down a new container image, but it'll be quicker to boot after this first time. Once it's up, you can connect again with VNC on port 5999 with password vncpass (unless you changed it).
14. When you want to start the container again, run the script you made in step 11. As before, you can connect to your VM with VNC on port 5999 with vncpass or the password you set. To stop the container, run:
To install the BlueBubbles Private API features, just follow the normal guide here.
When disabling SIP, follow the instructions for "Physical Mac, INTEL" on the Private API installation documentation.
To clarify, do NOT follow the documentation for disabling SIP on VMs. Everything you need is in the standard Private API installation guide.