Self-Host Beeper

Beeper is a universal chat app. It’s a single app to chat with friends on 15 different chat networks. Learn more on beeper.com.

If you're just looking to install Beeper, you can get it here. If you're a developer wanting to contribute or if you want to self-host Beeper on your own infrastructure, read on.

How Beeper works

Read the full FAQ

Beeper is built on top of an open source chat protocol called Matrix. When we started building Beeper, we made a fundamental decision to open source the majority of our backend code and provide you with the option to self-host Beeper. We chose to do this because:

We want you to be able to inspect the source code that Beeper uses to connect to other chat networks
We want to contribute to the Matrix ecosystem
We want to provide great libraries for others to develop open source Matrix bridges

Our infrastructure stack is composed of:

Beeper Clients

Native iOS and Android clients (closed source forks of Element iOS and Android)
Mac OS, Windows and Linux clients (closed source forks of Element Web/Desktop)

Matrix Homeserver

Synapse

Open Source, Beeper-maintained Matrix bridges

mautrix/whatsapp	mautrix/signal
mautrix/telegram	mautrix/facebook
mautrix/iMessage	mautrix/twitter
android-sms	mautrix/discord
mautrix/slack	mautrix/instagram
hifi/heisenbridge	mautrix/googlechat
beeper/linkedin	beeper/groupme

Open source, community maintained Matrix bridges, Beeper sponsored

fair/kakaotalk	fair/line

What is a Matrix bridge? Learn more

Self-Host Install Guide

Self hosting Beeper is possible, but not an easy task right now. It requires experience and/or willingness to learn Linux system administration.

Note: only open source Matrix clients like Element or SchildiChat can connect to a self-hosted system at this time. Beeper clients require a Beeper account and use Beeper’s infrastructure.

Instructions (easiest path)

💡 We recommend using the https://github.com/spantaleev/matrix-docker-ansible-deploy playbook to deploy Beeper’s Matrix bridges alongside a Matrix homeserver and client

Purchase a domain
1. We recommend Google Domains
2. Insert this domain (eg selfhostbeeper.com) wherever <insert_domain> is shown in these instructions.
Select a hosting provider
1. We recommend a 2GB RAM 50GB disk Digital Ocean Droplet
2. Record the Droplet IP to use in next step
Configure DNS

Type Host Priority Weight Port Target

A matrix - - - droplet-ip
- Test your domain to make sure it’s pointing at the Droplet IP
  - nslookup -type=A matrix.<insert_domain>
Install necessary tools on your desktop/laptop

Mac OS brew install git pwgen Linux apt install git pwgen
Download playbook to your desktop/laptop

git clone https://github.com/spantaleev/matrix-docker-ansible-deploy.git && cd matrix-docker-ansible-deploy
Configure the installation mkdir inventory/host_vars/matrix.<insert_domain>
wget https://raw.githubusercontent.com/beeper/self-host/main/vars.yml
cp vars.yml inventory/host_vars/matrix.<insert_domain>/vars.yml
openinventory/host_vars/matrix.<insert_domain>/vars.yml in a text editor
1. Insert your <insert_domain> in line 12
2. Enter a real email address in line 27 and 40
3. Wherever <create_secretkey> shows up (eg line 22), switch back to your terminal, run pwgen -s 64 1 and insert that key into the file
4. Disable any bridges you do not want (saves RAM!) or enable Telegram by following instructions on Line 52
5. Save the file.
cp examples/hosts inventory/hosts
Open inventory/hosts in a text editor
1. Replace <your_domain> with your domain
2. Replace your-server's external IP address> with Droplet IP
3. add the following to the hosts file: ansible_connection=community.docker.nsenter. The hosts file shold now look like this:

Type	Host	Priority	Weight	Port	Target
A	matrix	-	-	-	droplet-ip

[matrix_servers]
 matrix.YOUR.DOMAIN ansible_host=YOUR_SERVERS_IP ansible_connection=local ansible_ssh_user=root ansible_connection=community.docker.nsenter

Install docker and make sure it is started

Mac OS - Follow instructions https://docs.docker.com/desktop/install/mac-install

Linux - Follow instructions https://docs.docker.com/desktop/install/linux-install/#generic-installation-steps

Run Ansible in docker from the /matrix-docker-ansible-deploy directory. If this doesn't work, check the playbook instructions.

docker run -it --rm \
-w /work \
-v `pwd`:/work \
-v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro \
--entrypoint=/bin/sh \
docker.io/devture/ansible:2.13.6-r0-1

Your terminal should now show /work, then issue these commands
1. git config --global --add safe.directory /work
2. make roles
3. ansible-playbook -i inventory/hosts setup.yml --tags=install-all,ensure-matrix-users-created,start
4. Your server is now installed! Check that everything is working ansible-playbook -i inventory/hosts setup.yml --tags=self-check
  1. ignore the errors about federation
- Additional configuration https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/configuring-playbook.md#other-configuration-options
- Note that if you remove components from vars.yml, or if we switch some component from being installed by default to not being installed by default anymore, you'd need to run the setup command with --tags=setup-all instead of --tags=install-all. See Playbook tags introduction****
e. Create your user account, change the command to include your preferred username (<insert_username) and password (<your_password>).

ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=<insert_username> password=<your_password> admin=yes' --tags=register-user
In a browser, open our recommended Matrix client, https://app.schildi.chat/#/login
1. Click ‘Edit’ and https://matrix.<your_domain> into the homeserver field, eg https://matrix.beeptest.org then click Continue
2. Sign in with your username/password created in step 14e
Set up each bridge
1. Click the + icon, then type in @whatsappbot:<your_domain> into the search bar and wait for a suggestion to appear, then click on it, then click Done. This will start a chat with the ‘bridge bot’ and provide you with a console to login and setup the bridge
2. Click the Whatsapp Bridge Bot chat in the left panel, then send the message help in the chat to see the list of commands. Each bridge has a slightly different sign in command, but it is usually login, link, or login-qr
3. Repeat Step 16 for each bridge you would like to configure (eg @instagrambot:<your_domain>)
4. Great! Now all your bridges are set up
Set up mobile apps

Android - SchildiChat
iOS - Recommended apps: Element or FluffyChat

Advanced and optional! Enable federation

Add a root A record to your DNS pointing at your Droplet IP
Modify vars.yml to matrix_nginx_proxy_base_domain_serving_enabled: true, then re-run the Ansible script
Confirm it’s working at https://federationtester.matrix.org/
How to upgrade your installation later
- https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/maintenance-upgrading-services.md#upgrading-the-matrix-services

Feedback