This guide will show you how to setup your own dynamic DNS using your own self-hosted server, running Nginx Proxy Manager
NGINX Proxy Manager with port 80 and 443 forwarded properly
Bluebubbles server running and accessible from the machine which is running NGINX
Set Proxy Service to Dynamic DNS. Set your hostname to be https://bb.yourdomain.com
Keep Use Custom Certificate off
Ensure the local port is 1234
Add a new Proxy Host in NGINX
Set the domain name to bb.yourdomain.com
Set scheme to http
Set Forward Hostname / IP to the IP address of your mac
Set Forward Port to 1234
Turn on Block Common Exploits & Websocket Support
Click on the SSL Tab
Click on the dropdown and select Request a new SSL Certificate
Check all 4 options
Your Bluebubbles instance should now be accessible at https://bb.yourdomain.com !
Guide created by @pablito in the BlueBubbles Discord
Here you will find child guides for setting up BlueBubbles with a BYO (Bring Your Own) Proxy Service (Dynamic DNS).
By default, BlueBubbles has the Ngrok & Cloudflare proxy services built-into the server for you to utilize. However, these services are run by third parties and are by default, using a free license tier for the respective services. These guides will show you how you can self-host or utilize an existing license of a proxy or dynamic DNS service, to use with BlueBubbles.
Tailscale is a mesh VPN software that uses WireGuard technology. It also include other fun features like Tailscale Funnel.
Tailscale Funnel allows you to publicly expose your machine's local services without needing to purchase a domain & set up port forwarding. It hosts your machine's domain on their Funnel Servers. The Funnel Server accepts requests & sends a TCP proxy to your machine where TLS cert is terminated. Simple, secure & only requires a few short commands.
Requirements
Enable HTTPS certificates in the admin console.
Open the Access controls page in the admin console and click the Add Funnel to policy button
Download Tailscale from the Mac App Store or directly from Tailscale
Login from the top right menu icon & enable start on login from preferences
Add alias for the Tailscale CLI to your shell configuration by entering the command below into terminal.
Alternatively, you can use /Applications/Tailscale.app/Contents/MacOS/Tailscale <command>
Proxy requests to BlueBubbles's local web server on the default port 1234. Make sure to check your setup in case a different port is being used. Supported serve ports are 443, 8443, or 10000.
Enable the funnel to route proxy traffic over Tailscale funnel servers. Again, supported ports are 443, 8443, or 10000 - match with what you chose in Step 4. Replace port 1234 with your BlueBubble's local web server.
Check the funnel status with the following - you should see (Funnel on):
Finally, copy the entire URL that you see in step 6 to the BlueBubbles Proxy Service drop-down menu:
Thanks to @bobspop in Discord for creating this guide. Updated by @ampersandru
Pros:
Static URL, so no need to update Dynamic DNS in BlueBubbles server
Auto start at boot
You can configure a custom landing page to block unwanted connections to your server (in addition to the default one in BlueBubbles)
Cons:
You need a domain to link to Cloudflare (subdomain services like DuckDNS and No-IP won't work)
Setup is a tad bit more complicated
Sign up for a Cloudflare account at https://dash.cloudflare.com/sign-up
Add a site on the portal
Enter your domain name (do not use a subdomain)
Click the free plan and click continue
If you are using the domain for any other websites copy the records below (if you are just using the domain for BlueBubbles you can skip this part)
Configure your domain name servers to Cloudflare
Wait for Cloudflare to validate your domain
Login to the Zero Trust dashboard at https://dash.teams.cloudflare.com/ and go to Networks > Tunnels.
Select Create a tunnel
Enter a name for your tunnel. For example, you could name it Bluebubbles.
Select Save tunnel
Next, you will need to install cloudflared and run it. You can install it here, https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation/
After installing cloudflared, you can see that when choosing your OS as Mac, cloudflare provides a command to enter into terminal. Run this command.
Once the command has been run successfully, your connector will show up underneath the command in the Zero Trust Dashboard.
Select Next
Now in the Public Hostnames tab, type in your subdomain, for example, bluebubbles.(This does not have to be the name of your tunnel)
Choose the main domain you want to use for it.
Below, you should see a section called Service. For this, you want to put the localhost address for the bluebubbles server. The default one would be: HTTP://localhost:1234 .
Save the tunnel
After doing this, you may need to run sudo launchctl start com.cloudflare.cloudflared when initially setting up the tunnel to start it.
As we installed cloudflared as a service, it should automatically launch at startup.
Navigate to the settings page of the server app
Change the proxy to dynamic dns
For the URL, type in the url displayed in the tunnels section of the Zero Trust dashboard. Make sure you use HTTPS as cloudflare uses that by default.
Now try opening the bluebubbles app and see if it connects.
It is recommended that you ensure the server is fully working and the app is connecting before proceeding.
Login to the Zero Trust dashboard at https://dash.teams.cloudflare.com/ and go to Access > Service Auth.
Select Create Service Token.
Give it a name (This does not have to be the name of your server) like "bb".
Set the duration to as long as you want before a new token is required (Non-expiring means you'll not have to reset this in the future).
Click Generate Token.
Record somewhere the Header and client ID and the Header and client secret. Hit Save.
From the left hand menu go to Access > Applications.
Select Add an application, and select Self-hosted.
Leave everything as default unless specified below.
Under Application Name put "Blue Bubbles".
Under Subdomain set to the subdomain you used during "Setting up Cloudflare tunnels with your domain" above for example, "bluebubbles"
Under Domain select the main domain you used for it.
Click Next.
Under Policy name, insert "servicetoken".
Set Action to Service Auth.
Under Configure Rules, change Selector drop-down to Service Token and select the service token name you set in step 4 above.
Click Next & click Add application.
In the Blue Bubbles app on Android (or Windows etc), under "Settings/Connection & Server" scroll down to "Configure Custom Headers".
Add Header Key "cf-access-client-id" and set Value to your client id (remove "CF-Access-Client-Id:" from the start - ie only insert alphanumericstring.access)
Add Header Key "cf-access-client-secret" and set Value to your client secret (remove "CF-Access-Client-Secret:" from the start - ie only insert longalphanumericstring)
Hit OK.
Test syncing your messages by selecting "Manually Sync Messages" for the last hour.
In Cloudflare, from the left hand menu, go to Access > Service Auth and refresh the browser.
"Last Seen" should be updated to shown the Service Token has been used.
Congrats - your Blue Bubbles server is now secured so only your app can access it.
A way to get https when portforwarding with bluebubbles
This guide is written with the intention caddy is deployed on the same mac as your bluebubbles server but the process is similar if you have a remote caddy server.
Benefits:
Works nonstandard ports
A duckdns account with a domain https://www.duckdns.org/domains
A setup bluebubbles server
The ability to portforward your mac mini or reverse proxy to a machine that can be portforwarded (ex: aws, gcp, oracle, etc)
Download caddy with duckns and move it to your home folder with the following command
Intel Macs:
curl -o ./caddy https://caddyserver.com/api/download?os=darwin&arch=amd64&p=github.com/caddy-dns/duckdns&idempotency=8875705962096
Apple Silicon:
curl -o ./caddy https://caddyserver.com/api/download?os=darwin&arch=arm64&p=github.com/caddy-dns/duckdns&idempotency=28552737821716
Make caddy executable with the command chmod 755 ./caddy
Download the template caddy file with the following command:
curl -o ./Caddyfile https://raw.githubusercontent.com/Rihcus/BB-dynamic-dns-duckdns/main/Caddyfile
Edit the Caddyfile
replace the example domains with your domains
replace xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx with your duckdns token
Optional adjust the https/http or bluebubbles server ports as needed
For testing purposes set your duckdns domain to the local ip of your bluebubbles server using the duckdns web portal
test the config with ./caddy run
if the config works and you can access your domain via https use ./caddy start to make it auto run
Setup portforwarding (not covered in this guide)
Optional install duckdns to your mac server in order to auto-update public ip
Guide created by @Deemo in the BlueBubbles Discord
If you want to perform a manual setup of Nginx, instead of using the Nginx Proxy Manager, here is a guide on how to do it. Big thanks to @JustBen in the BlueBubbles Discord, for putting this guide tog
This page will guide you on setting up your own reverse proxy, given that you own a server to use for it. In order for this setup to work, you will need control of a server. This is typically a Linux server but could theoretically be any operating system. This guide will be for setting up a reverse proxy on Linux specifically. This will also assume that you have a Linux server on the same local network as your BlueBubbles server, as having the proxy and server on different networks adds several layers of complexity.
While the built-in proxy services in BlueBubbles are simple and easy to use, many users want a completely self-hosted setup where they control all pieces of the system. More specifically, control over the server, client, proxy, and domain. This eliminates almost all dependence on third-party resources and services.
The best use-case for this is that you already run a personal server of some sort and maybe you're already running a proxy for services running on this personal server. There is arguably more privacy in owning and controlling the proxy that handles your BlueBubbles traffic, or maybe you just enjoy learning about and/or managing application and server tools.
That said, the built-in options to BlueBubbles are more well-suited for the majority of users as they are generally reliable, secure, and (most importantly) easy to configure.
| Pros | Cons |
|---|
A server at your disposal on the same local network (LAN) as your BlueBubbles server
A static IP or DHCP reservation configured for your BlueBubbles server on your LAN
A static or reliable way to reach your home WAN IP (publicly addressable IP). This could be:
A static IP on your router. This is unlikely, as your WAN IP is usually not guaranteed by your ISP to stay the same, and it may change unexpectedly
A domain name and Dynamic DNS configured (more information below)
Port forwarding of your public BlueBubbles ports (recommended 80 and 443) to your proxy server
DISCLAIMER: If you aren't able to or don't know how to configure port forwarding, it is HIGHLY recommended that you instead opt for the built-in BlueBubbles proxy services
(Optional) A domain name
If you have a domain name, we recommend configuring Dynamic DNS. This will ensure that your domain name will always point to your WAN IP (which may change unexpectedly and/or frequently). Your registrar/DNS server must support Dynamic DNS, and configuration will depend on your router and your registrar/DNS. For a starting point, you can view the .
Of course, there are certain things that will vary depending on your configuration and setup. The following variables will be used as placeholders in the example configurations below. They will appear in the example configurations exactly as they appear here.
The following is the recommended configuration for BlueBubbles to work behind an Nginx proxy. For easiest configuration, this should be placed in a new file at /etc/nginx/conf.d/bluebubbles.conf
After creating this file and filling in the appropriate values, restart the Nginx service with systemctl restart nginx.service (you may need sudo).
If you plan to use SSL (recommended), see the SSL Configuration section at the bottom of this guide.
The directory conf.d may be named something else like vhosts.d, depending on your Linux distribution
If you have further problems with large files not sending to BlueBubbles, you can also define the configured client_body_buffer_size similar to client_max_body_size
Before writing your config, these apache modules are required for the config to work:
mod_proxy
proxy_http
proxy_wstunnel
mod_headers
The following is the recommended configuration for BlueBubbles to work behind an Apache proxy. This should be placed in a new file at /etc/httpd/conf.d/bluebubbles.conf
After creating this file and filling in the appropriate values, restart the apache service with systemctl restart httpd (you may need sudo)
If you plan to use SSL (recommended), see the SSL Configuration section at the bottom of this guide.
On certain Linux distributions, the configuration directory may be at /etc/apache2/vhosts.d/ or /etc/httpd/vhosts.d/
For reference, the following is the minimum viable configuration for BlueBubbles to work behind an Apache proxy. This configuration does not need the mod_headers module.
The following is the recommended configuration template for HAProxy. This should be in /etc/haproxy/haproxy.cfg.
There are a few variables specific to HAProxy here:
After writing/changing these files, reload HAProxy with systemctl restart haproxy (you may need sudo)
If you plan to use SSL (recommended), see the SSL Configuration section at the bottom of this guide.
If you do not use SSL/HTTPS (used interchangeably here), traffic sent from your client to your server will be sent in plain text. This includes message content and your BlueBubbles password. As such, configuring SSL is highly recommended if you intend to connect to your BlueBubbles server over the internet.
To access your BlueBubbles to use HTTPS, you need to use an SSL certificate and configure your proxy to either terminate or pass through the SSL traffic. Here we will provide example configurations that have SSL certificates configured and link to more resources for configuring SSL on your proxy.
Keep in mind that you can only use SSL if you have a domain -- it will not work with only an IP address.
The easiest way to use this is to use something called "SSL termination" or "SSL offloading." This just means that the connection from client to server uses HTTPS (encrypted traffic) to the proxy, then the proxy communicates with the backend server using HTTP (unencrypted/plaintext traffic). As long as the proxy server and backend server live on the same private network, there are minimal security concerns with this setup, as the unencrypted traffic is sent over a trusted, private network.
The primary alternative to SSL termination is SSL passthrough, in which the traffic is not decrypted at the proxy, but instead is passed through to the server where the traffic is decrypted. There are other alternatives such as two-way SSL in which the client talks to the proxy on one SSL connection, then the proxy opens a different SSL connection to talk with the backend server over an encrypted channel.
For simplicity's sake, we will only be covering SSL offloading configuration in this guide.
If you are using HAProxy, there are some added layers of complexity, but Certbot can still be used to seamlessly automate the management and renewal of SSL certificates. Skip to the section Certbot on HAProxy.
This is highly recommended as the solution for configuring SSL/HTTPS. This solution is easy, robust, and automated. Unless you have a good reason not to use Certbot, we highly recommend this option.
Certbot configuration steps
If you are using HAProxy, skip to the section Certbot on HAProxy.
On almost all Linux systems, the configuration is simple:
Install certbot with your distribution's package manager
You may also need to install the certbot addon for your specific proxy, e.g. certbot-nginx (package names vary by distro)
Configure your service as you normally would, with HTTP-only
You need to configure your service before running Certbot to configure SSL on your service. This is because Certbot will look through your config to match the <server name> you provide it with the server name in your configuration file. It does this to identify where it needs to add the configuration for SSL.
Issue a new certificate:
Run: sudo certbot --standalone --<proxy> -d <server name>
Fill in <proxy> appropriately for your proxy application (apache, nginx)
If this is your first time running certbot, it will run you through a simple first-time setup that just requires your email address, confirmation of the Terms of Service, and whether or not you want to receive emails about EFF projects and campaigns
Use cron to automatically renew the certificate(s) every 2 months
Add a line to your crontab
sudo crontab -e
Insert on its own line: 0 0 1 */2 * certbot renew
Enable the cron service, if it isn't already:
sudo systemctl enable --now cron
Certbot on HAProxy
Per Certbot's website: "Certificate installation with HAProxy is complicated." There are a few things that makes Certbot with HAProxy somewhat complicated:
HAProxy is not a web server, so it can not be used in standalone mode to run an HTTP server and respond to Let's Encrypt's HTTP-01 challenges
HAProxy requires a single .pem file that includes both the public certificate and the private key. This is not automatically generated by Certbot.
However, there are several guides available online which show you how to generate a certificate, install it, and then automate the renewal process. In short, it works by diverting HTTP calls to the .well-known directory (where HTTP-01 challenges are stored) to the localhost where Certbot is running its own web server during the challenge. Then, the new certificate and key are combined into a .pem file with a simple bash script.
An example configuration file may be provided in the future after more testing can be done.
To reiterate: Certbot is highly recommended as an easy solution for SSL configuration and management. If you do intend to configure SSL yourself, we have provided example configurations below and references to further reading on the subject. If you're having trouble, feel free to join our Discord and ask questions there (linked in the header above).
These example configuration files are the auto-generated files by Certbot and are provided for reference.
Nginx
Contents of /etc/nginx/conf.d/bluebubbles.conf (could also be /etc/nginx/vhosts.d/bluebubbles.conf, depending on distro)
Contents of /etc/letsencrypt/options-ssl-nginx.conf
Apache
Contents of /etc/httpd/conf.d/bluebubbles.conf (could also be /etc/apache2/vhosts.d/bluebubbles.conf, depending on Linux distribution)
HAProxy
If you intend to use Certbot with HAProxy, please reference the above section "Certbot on HAProxy"
For HAProxy, you need to have a .pem file that includes both the public certificate and the private key. If you don't already have this, you can simply create a .pem file that contains the appended content of both the .key and .cer/.crt files. Example: cat mydomain.key mydomain.crt >> output.pem
Contents of /etc/haproxy/haproxy.cfg
| Variable name | Description | Example values |
|---|
You can change client_max_body_size to whatever you want. You can use M and G to denote Megabytes and Gigabytes respectively, or you can set this to 0 (with no units) to put no restriction on the max client body size. This changes the max file size that can be sent through the proxy to BlueBubbles. For more information, you can see the
Keep in mind that HAProxy ACL configurations can be complex. For more information on configuring HAProxy ACLs, see .
| Variable name | Description | Example values |
|---|
The simplest solution for SSL certificate management and configuration is . Certbot is a tool built by the Electronic Frontier Foundation (EFF) and leverages to issue free certificates and then automatically install them in your existing server/proxy configuration. Certbot supports automatic SSL configuration for Apache, Nginx, HAProxy, and Plesk.
(Recommended)
<server name> | Domain name or WAN IP of your server to which the proxy will be responding |
|
<BlueBubbles IP> | The IP of your BlueBubbles server on the local network. If the proxy is running on the same server as your BlueBubbles server (as in a VM), use |
|
<BlueBubbles port> | The port that the BlueBubbles server is listening at on the local network (default is 1234) |
|
<backend name> | HAProxy backend name. This is an arbitrary name used to identify services in your HAProxy configuration file(s) |
|
<be server name> | HAProxy backend server name. This is an arbitrary name used to identify a specific backend server in your HAProxy configuration file(s) |
|
Completely self-hosted, no need to use a third-party service | Server maintenance & upkeep |
More secure, entirely controlled and operated by yourself | More prerequisites, niche use case |
More control, allowing you to configure everything exactly as you want it | More complex configuration |
