diff --git a/docs/configuring-playbook-bridge-rustpush.md b/docs/configuring-playbook-bridge-rustpush.md index 66e435d19..d3e85e208 100644 --- a/docs/configuring-playbook-bridge-rustpush.md +++ b/docs/configuring-playbook-bridge-rustpush.md @@ -4,11 +4,11 @@ SPDX-FileCopyrightText: 2025 MDAD project contributors SPDX-License-Identifier: AGPL-3.0-or-later --> -# Setting up RustPush bridging (optional) +# Setting up RustPush (iMessage) bridging (optional) Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md) -The playbook can install and configure [rustpush to bridge iMessage](https://github.com/jasonlaguidice/imessage) for you using Apple's push notification service (no Mac needed at runtime). +The playbook can install and configure [rustpush to bridge iMessage](https://github.com/jasonlaguidice/imessage) for you using Apple's push notification service. See the project's [documentation](https://github.com/jasonlaguidice/imessage/blob/main/README.md) to learn what it does and why it might be useful to you. @@ -20,6 +20,12 @@ To use this bridge on Linux (Docker), you need a **hardware key** extracted from The key is entered interactively through the bridge bot's login flow (not configured via Ansible variables). See the upstream [README](https://github.com/jasonlaguidice/imessage/blob/main/README.md) for instructions on extracting the key. +If extracted from an Intel Mac, the Mac does not need to remain running after the key is extracted for this bridge to work. Apple Silicon Macs must run a NAC relay. + +### Phone Number Registration (optional) + +This bridge can **not** do phone number registration (PNR). The only way to have your phone number registered and used (instead of an Apple ID e-mail address) is to have an iPhone connected to your Apple account. Reference the [BlueBubbles Phone Number Registration Guide](https://docs.bluebubbles.app/server/advanced/registering-a-phone-number-with-your-imessage-account) for information on how to set this up. + ### Enable Appservice Double Puppet (optional) If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook. @@ -34,15 +40,15 @@ To enable the bridge, add the following configuration to your `inventory/host_va matrix_rustpush_bridge_enabled: true ``` -### Backfill (optional) +### Disable Backfill (optional) -Backfill can be disabled globally if desired via config. Backfill from chat.db is disabled Linux Docker cannot access the macOS `chat.db` file. +Backfill can be disabled globally if desired via config. By default, the bridge will backfill from iCloud (CloudKit) and APNS if available. Backfill from `chat.db` is only possible when the bridge is running on MacOS. ```yaml matrix_rustpush_bridge_backfill_enabled: false ``` -### Extending the configuration +### Extending the Configuration There are some additional things you may wish to configure about the bridge. @@ -63,14 +69,22 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. -- The first run will take longer than usual because the Docker image is built from source (Rust + Go compilation). - ## Usage To use the bridge, you need to start a chat with `@imessagebot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). After logging in, the bridge will start receiving iMessages and creating portal rooms. +## Interference With Mautrix-iMessage & WSproxy + +By default, this bridge uses the same bot user name (`@imessagebot:example.com`) and same localpart for puppet users (`imessage_{{.}}`) as the mautrix-imessage bridge. If you use this bridge on your homeserver have a few options: + +1. Change the bot and appservice name templates: + + Set `matrix_rustpush_bridge_appservice_bot_username` and to a non-default value `matrix_rustpush_bridge_appservice_username_template` + +2. After deactivating mautrix-imessage, delete the bot user and all its portal rooms from the database, then re-start the server (more difficult) + ## Troubleshooting As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-rustpush-bridge`. @@ -82,4 +96,7 @@ The default logging level for this component is `warn`. If you want to increase ```yaml # Valid values: fatal, error, warn, info, debug, trace matrix_rustpush_bridge_logging_level: 'debug' + +# Enable debug logging for RustPush +matrix_rustpush_bridge_rust_log: "warn,rustpushgo=info,openabsinthe=debug" ```