5 Bridge setup with Docker
MaximilianS edited this page 2021-02-08 18:14:03 +01:00

Requirements

  • Docker
  • A Matrix homeserver that supports application services (e.g. Synapse)

Setup

Docker images are hosted on dock.mau.dev

  1. Create a directory for the bridge and cd into it: mkdir mautrix-whatsapp && cd mautrix-whatsapp.
    N.B. The docker image will chown its /data directory to UID 1337. The commands below mount the working directory as /data, so make sure you always run them in the correct directory.
  2. Pull the docker image with docker pull dock.mau.dev/tulir/mautrix-whatsapp:latest.
  3. Run the container for the first time, so it can create a config file for you:
    docker run --rm -v `pwd`:/data:z dock.mau.dev/tulir/mautrix-whatsapp:latest
    
  4. Update the config to your liking. Don't forget to change the address and domain to match those of your server. Don't change the database URI if using SQLite.
  5. Generate the appservice registration by running the container again, same command as above.
  6. Add the path to the registration file (registration.yaml by default) to your Synapse's homeserver.yaml under the app_service_config_files section: app_service_config_files: ["/path/to/your/mautrix-whatsapp/registration.yaml"]
  7. Restart Synapse to apply changes.
  8. Run the bridge:
    docker run --restart unless-stopped -p 29318:29318 -v `pwd`:/data:z dock.mau.dev/tulir/mautrix-whatsapp:latest
    
    N.B. If using postgres database hosted at localhost/127.0.0.1 (outside the container), then use --network=host to avoid errors like dial tcp 127.0.0.1:5432: connect: connection refused

Upgrading

  1. Pull the new version (setup step 1)
  2. Start the new version (setup step 7)

Docker compose

If you already run synapse using docker-compose:

  1. Edit the docker-compose.yml and add the mautrix-whatsapp section as stated below.

If not, consider doing it. It can simplify things a lot. Otherwise:

  1. create a directory as in step #0 and create docker-compose.yml that contains something like this:
version: "3.7"

services:
  mautrix-whatsapp:
    container_name: mautrix-whatsapp
    image: dock.mau.dev/tulir/mautrix-whatsapp:latest
    restart: unless-stopped
    environment: 
      - UID=XXXX  # (optional) User id of your docker user. Make sure to use the same one for your server (synapse). 
      - GID=XXXX  # (optional) Group id of your docker user.
    volumes:
    - ./mautrix-whatsapp/:/data  # Use a sub directory if you plan to run another bridge. 
  1. Start the bridge once with docker-compose up mautrix-whatsapp to generate the config file.
  2. Edit the config.yaml with the correct address and domain. Proposed changes:
homeserver:
   address: https://<your server domain>
   domain: <your server domain>
appservice:
   address: http://mautrix-whatsapp:29318 # depends on the name you chose in the `docker-compose.yml`. Only works if synapse is defined in the same docker-compose.yml.
   hostname: mautrix-whatsapp
  1. Run docker-compose up -d mautrix-whatsapp to start the bridge and to generate the registration.yaml.
  2. (Optional) If you didn't use the user and group id environment variables, fix ownership of registration.yaml. If synapse is running as root, ignore this step.
  3. If the mautrix-whatsapp volume is not reachable by synapse, copy registration.yaml somewhere into the synapse volume path.
  4. Edit homeserver.yaml and add the path to the registration.yaml to app_service_config_files:
app_service_config_files: 
   - "/path/to/your/mautrix-whatsapp/registration.yaml"
  1. Restart synapse docker-compose restart synapse

Use docker-compose up -d to start, docker-compose stop to stop. To update, run docker-compose pull to download the new images and docker-compose up -d to recreate running containers with the updated ones.

Adding UID and GID is optional, but encouraged. Otherwise the registration.yaml might not be readable by synapse.

Note

If you have connection problems and changed something in your config.yaml, delete registration.yaml and mautrix-whatsapp.db, then restart the bridge. Those files are not recreated automatically and need to be regenerated after making changes in the config.