{"id":13613745,"url":"https://github.com/beeper/self-host","last_synced_at":"2025-09-28T19:31:16.422Z","repository":{"id":138777253,"uuid":"589434412","full_name":"beeper/self-host","owner":"beeper","description":"Learn how to self-host Beeper","archived":true,"fork":false,"pushed_at":"2024-02-05T06:15:55.000Z","size":45,"stargazers_count":1053,"open_issues_count":26,"forks_count":34,"subscribers_count":10,"default_branch":"main","last_synced_at":"2024-09-27T02:40:58.474Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/beeper.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-01-16T05:13:58.000Z","updated_at":"2024-09-23T00:26:21.000Z","dependencies_parsed_at":"2024-01-13T22:59:10.455Z","dependency_job_id":null,"html_url":"https://github.com/beeper/self-host","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beeper%2Fself-host","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beeper%2Fself-host/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beeper%2Fself-host/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beeper%2Fself-host/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beeper","download_url":"https://codeload.github.com/beeper/self-host/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234555721,"owners_count":18851829,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T20:00:53.199Z","updated_at":"2025-09-28T19:31:16.134Z","avatar_url":"https://github.com/beeper.png","language":null,"funding_links":[],"categories":["miscellaneous","Install from Source","Others","others"],"sub_categories":["iMessage"],"readme":"# This guide is obselete, please use [bridge-manager](https://github.com/beeper/bridge-manager) \nWe've made selt-hosting Beeper bridges infinitely easier! We recommend using our new tool [bridge-manager](https://github.com/beeper/bridge-manager) rather than this old method.\n\n\n---------\n\n\n## (deprecated) Self-Host Beeper\n\nIf you're just looking to install Beeper, you can get it [here](http://beeper.com). If you're a developer wanting to contribute or if you want to self-host Beeper on your own infrastructure, read on.\n\n## How Beeper works\n\n---\n\n*Read the full [FAQ](https://beeper.com/faq)*\n\nBeeper is built on top of an open source chat protocol called [Matrix](https://matrix.org). 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:\n- We want you to be able to inspect the source code that Beeper uses to connect to other chat networks\n- We want to contribute to the Matrix ecosystem\n- We want to provide great libraries for others to develop open source Matrix bridges\n\n\nOur infrastructure stack is composed of:\n\n**Beeper Clients**\n\n- Native [iOS](https://www.beeper.com/download) and [Android](https://play.google.com/store/apps/details?id=com.beeper.chat) clients (closed source forks of [Element iOS](https://github.com/vector-im/element-ios) and [Android](https://github.com/vector-im/element-android))\n- [Mac OS](https://www.beeper.com/download), [Windows](https://www.beeper.com/download) and [Linux clients](https://www.beeper.com/download) (closed source forks of [Element Web](https://github.com/vector-im/element-web)/[Desktop](https://github.com/vector-im/element-desktop))\n\n**Matrix Homeserver**\n\n- [Synapse](https://github.com/matrix-org/synapse)\n\n\n*********Open Source, Beeper-maintained Matrix bridges*********\n| [mautrix/whatsapp](https://github.com/mautrix/whatsapp) | [mautrix/signal](https://github.com/mautrix/signal) |\n| --- | --- |\n| [mautrix/telegram](https://github.com/mautrix/telegram) | [mautrix/facebook](https://github.com/mautrix/facebook) |\n| [mautrix/iMessage](https://github.com/mautrix/imessage) | [mautrix/twitter](https://github.com/mautrix/twitter) |\n| [android-sms](https://gitlab.com/beeper/android-sms) | [mautrix/discord](https://github.com/mautrix/discord) |\n| [mautrix/slack](https://github.com/mautrix/slack) | [mautrix/instagram](https://github.com/mautrix/instagram) |\n| [hifi/heisenbridge](https://github.com/hifi/heisenbridge) | [mautrix/googlechat](https://github.com/mautrix/googlechat) |\n| [beeper/linkedin](https://github.com/beeper/linkedin) | [beeper/groupme](https://github.com/beeper/groupme) |\n\n*********Open source, community maintained Matrix bridges, Beeper sponsored*********\n\n| [fair/kakaotalk](https://src.miscworks.net/fair/matrix-appservice-kakaotalk.git) | [fair/line](https://src.miscworks.net/fair/matrix-puppeteer-line.git) |\n| --- | --- |\n\nWhat is a Matrix bridge? [Learn more](www.beeper.com/new-faqs/what-is-a-bridge)\n\n\n## Self-Host Install Guide\n\n---\n\nSelf hosting Beeper is possible, but not an easy task right now. It requires experience and/or willingness to learn Linux system administration. \n\n***************************************************************************************************************************************************************************************************************************************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.***************************************************************************************************************************************************************************************************************************************\n\n### Instructions (easiest path)\n\n\u003caside\u003e\n💡 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\n\n\u003c/aside\u003e\n\n1. **Purchase a domain**\n    1. We recommend Google Domains\n    2. Insert this domain (eg `selfhostbeeper.com`) wherever `\u003cinsert_domain\u003e` is shown in these instructions.\n2. **Select a hosting provider**\n    1. We recommend a 2GB RAM 50GB disk Digital Ocean Droplet\n    2. Record the Droplet IP to use in next step\n3. **Configure DNS**\n    \n    \n    | Type | Host | Priority | Weight | Port | Target |\n    | --- | --- | --- | --- | --- | --- |\n    | A | matrix | - | - | - | droplet-ip |\n    - Test your domain to make sure it’s pointing at the Droplet IP\n        - `nslookup -type=A matrix.\u003cinsert_domain\u003e`\n4. Install necessary tools on your desktop/laptop \n    \n    ************Mac OS************\n    `brew install git pwgen`\n    ****************Linux****************\n    `apt install git pwgen`\n    \n5. **Download playbook to your desktop/laptop** \n    \n    `git clone https://github.com/spantaleev/matrix-docker-ansible-deploy.git \u0026\u0026 cd matrix-docker-ansible-deploy` \n    \n6. Configure the installation\n`mkdir inventory/host_vars/matrix.\u003cinsert_domain\u003e`\n7. `wget https://raw.githubusercontent.com/beeper/self-host/main/vars.yml`\n8. `cp vars.yml inventory/host_vars/matrix.\u003cinsert_domain\u003e/vars.yml`\n9.  open`inventory/host_vars/matrix.\u003cinsert_domain\u003e/vars.yml` in a text editor\n    1. Insert your `\u003cinsert_domain\u003e` in line 12\n    2. Enter a real email address in line 27 and 40\n    3. Wherever `\u003ccreate_secretkey\u003e` shows up (eg line 22), switch back to your terminal, run `pwgen -s 64 1` and insert that key into the file\n    4. Disable any bridges you do not want (saves RAM!) or enable Telegram by following instructions on Line 52\n    5. Save the file.\n10. `cp examples/hosts inventory/hosts`\n11. Open `inventory/hosts` in a text editor\n    1. Replace `\u003cyour_domain\u003e` with your domain\n    2. Replace `your-server's external IP address\u003e` with Droplet IP\n    3. add the following to the hosts file: `ansible_connection=community.docker.nsenter`. The hosts file shold now look like this:\n   ```\n   [matrix_servers]\n    matrix.YOUR.DOMAIN ansible_host=YOUR_SERVERS_IP ansible_connection=local ansible_ssh_user=root ansible_connection=community.docker.nsenter\n   ```\n12. Install docker and make sure it is started\n    \n    Mac OS - Follow instructions [https://docs.docker.com/desktop/install/mac-install](https://docs.docker.com/desktop/install/mac-install) \n    \n    Linux - Follow instructions [https://docs.docker.com/desktop/install/linux-install/#generic-installation-steps](https://docs.docker.com/desktop/install/linux-install/#generic-installation-steps)\n    \n13. Run Ansible in docker from the `/matrix-docker-ansible-deploy` directory. If this doesn't work, check the [playbook instructions](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/ansible.md#using-ansible-via-docker).\n    \n    ```bash\n    docker run -it --rm \\\n    -w /work \\\n    -v `pwd`:/work \\\n    -v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro \\\n    --entrypoint=/bin/sh \\\n    docker.io/devture/ansible:2.13.6-r0-1\n    ```\n    \n14. Your terminal should now show `/work`, then issue these commands\n    1. `git config --global --add safe.directory /work`\n    2. `make roles`\n    3. `ansible-playbook -i inventory/hosts setup.yml --tags=install-all,ensure-matrix-users-created,start`\n    4. Your server is now installed! Check that everything is working `ansible-playbook -i inventory/hosts setup.yml --tags=self-check`\n        1. ignore the errors about federation\n    - Additional configuration [https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/configuring-playbook.md#other-configuration-options](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/configuring-playbook.md#other-configuration-options)\n    - 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](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/installing.md#playbook-tags-introduction)****\n    \n    e. Create your user account, change the command to include your preferred username (`\u003cinsert_username`) and password (`\u003cyour_password\u003e`). \n    \n    `ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=\u003cinsert_username\u003e password=\u003cyour_password\u003e admin=yes' --tags=register-user`\n    \n15. In a browser, open our recommended Matrix client, [https://app.schildi.chat/#/login](https://app.schildi.chat/#/login) \n    1. Click ‘Edit’ and `https://matrix.\u003cyour_domain\u003e` into the homeserver field, eg `https://matrix.beeptest.org` then click Continue\n    2. Sign in with your username/password created in step 14e\n16. Set up each bridge\n\n    ![CleanShot 2023-01-26 at 23 08 40](https://user-images.githubusercontent.com/1048265/215031550-61f92954-6936-42af-bb4b-a8165e17389e.gif)\n    \n    1. Click the + icon, then type in `@whatsappbot:\u003cyour_domain\u003e` 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\n    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`\n    3. Repeat Step 16 for each bridge you would like to configure (eg `@instagrambot:\u003cyour_domain\u003e`)\n    4. Great! Now all your bridges are set up\n17. Set up mobile apps\n- Android - [SchildiChat](https://play.google.com/store/apps/details?id=de.spiritcroc.riotx)\n- iOS - Recommended apps: [Element](https://apps.apple.com/us/app/element-messenger/id1083446067) or [FluffyChat](https://apps.apple.com/us/app/fluffychat/id1551469600?platform=iphone) \n    \n18. Advanced and optional! Enable federation\n- Add a root `A record` to your DNS pointing at your Droplet IP\n- Modify `vars.yml` to `matrix_nginx_proxy_base_domain_serving_enabled: true`, then re-run the Ansible script\n- Confirm it’s working at [https://federationtester.matrix.org/](https://federationtester.matrix.org/)\n- How to upgrade your installation later\n    - [https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/maintenance-upgrading-services.md#upgrading-the-matrix-services](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/maintenance-upgrading-services.md#upgrading-the-matrix-services)\n\n## Feedback\n\n---\n\nWe would love to hear what you think about Beeper and our open source software. We hang out at #beeper:beeper.com on Matrix, or create an issue in this repository. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeeper%2Fself-host","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeeper%2Fself-host","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeeper%2Fself-host/lists"}